Doc Harness

Doc Harness — Document-Based Project Control

Doc Harness creates and maintains five status documents per project that enable any agent or human to understand and resume project work purely from reading files — no external memory needed.

Core principle: "Write It Down or Lose It" — all information in context is temporary. If it is not written to a file and registered in FILE_INDEX, it will be lost.

---

The Five Documents

| Document | Role | Answers | |----------|------|---------| | CLAUDE.md | Project entry point | "What is this project? What are the rules? Where do I start?" | | CURRENTSTATUS.md | Active state | "What just happened? What's happening now? What's next?" | | FILEINDEX.md | File catalog | "What files exist, what are they, and where are they?" | | WORKLOG.md | Permanent history | "What exactly happened in phase 2, three weeks ago?" | | DOCHARNESSSPEC.md | Complete reference | Full specification for unusual situations |

Metaphor: A project in motion is like a moving car.

• Tire Tracks (Recent Completed) — the road behind
• Car Body (Current Work) — where you are right now
• Headlights (Next Steps) — where you're going
• Driving Manual (Working Principles) — rules for this road

---

Natural-Language Commands

Kimi has no slash commands. Use the table below to map user requests to the correct procedure.

| User says | Procedure | See | |-----------|-----------|-----| | "Set up doc-harness" / "init project docs" / "create status documentation" | Init — create the five documents for a new or existing project | [references/init.md](references/init.md) | | "Check documentation health" / "audit project docs" / "run a health check" | Check — audit file health and reflect on principles | [references/check.md](references/check.md) | | "Sync project state" / "update status docs" / "catch up documentation" | Sync — repair drift, refresh dates, register missing files | [references/sync.md](references/sync.md) | | "Save everything" / "flush context" / "prepare for compact" / "ensure nothing is lost" | Flush — emergency save: extract all important context into documents. Runs five phases: (A) sync, (B) context inventory, (C) write and register, (D) verification, (E) flush marker. Phases B and C are the defining feature — they scan context for information that exists only in memory and write it to files. Without Phase B and C, flush has failed and is indistinguishable from sync. | [references/flush.md](references/flush.md) | | "Resume this project" / "continue work" / "where were we" / "back to project" / "pick up where we left off" / "what's the current status" | Resume — structured state recovery. Execute Recovery Chain, produce Recovery Report, verify understanding before continuing. Four phases: (A) Recovery Chain, (B) Recovery Report synthesis, (C) Understanding Verification, (D) Resume decision. | [references/resume.md](references/resume.md) | | "Recall" / "remember" / "find in docs" / "search project docs" / "where did we discuss" / "why did we decide" / "what is the current plan" | Recall — retrieve information from registered documents along the Doc Harness hierarchy | [references/recall.md](references/recall.md) |

---

Daily Workflow

Session Start

1. Identity anchor: Read the AGENT IDENTITY LOCK at the top of CLAUDE.md. Confirm:

"I am this project's agent. My role is [role from the lock]."

1. Read project's CLAUDE.md → understand overview, iron rules, recovery chain
2. Read CURRENT_STATUS.md → tire tracks (history), car body (current state), headlights (next steps), driving manual (principles)
3. If user is present → confirm whether next steps have changed
4. If context was compressed → resume from car body per headlights

During Work

• Complete a meaningful step → update CURRENT_STATUS car body
• Create a new file → do two things: (1) register in FILE_INDEX (2) record in car body
• Important analysis / decision / insight → write to file immediately and register
• Watch remaining context (if runtime exposes it). When low (~3 days); car body exceeds ~200 lines.

Five steps (strict order):

1. Protect data: Copy CURRENT_STATUS car body in full to WORKLOG top (after TOC). Add phase summary. → After this step, even if interrupted, no data is lost.
2. Insert new summary (3-5 lines) at top of CURRENT_STATUS tire tracks.
3. If tire tracks exceed 3 → remove the oldest (already in WORKLOG).
4. Clear car body → fill in new phase goal. Review driving manual principles (promote to iron rule / keep / remove).
5. Update CLAUDE.md "current phase" and "one-line status". Update WORKLOG TOC.

Interrupt safety: Step 1 is protective. If compact occurs during Steps 2-5, data is safe. On next session start, run mid-transition detection (three-way coherence check: CLAUDE.md phase / WORKLOG TOC / CURRENT_STATUS tire tracks) and repair deterministically.

---

Agent Behavior Rules

Iron Rules vs Driving Manual

| Type | Location | Lifecycle | |------|----------|-----------| | Iron rules | CLAUDE.md | Permanent, phase-independent | | Driving manual | CURRENT_STATUS | Lives and dies with the phase |

At phase transition, review each driving-manual principle: promote to iron rule (if ≥3 phases)? Keep? Remove?

Single Source of Truth

| Fact Type | Sole Source | |-----------|------------| | Current state / progress | CURRENTSTATUS.md | | File catalog | FILEINDEX.md | | Historical details | WORKLOG.md | | Project overview / rules | CLAUDE.md |

Anti-patterns

• File created but not registered → register immediately
• Information only in context → "Write It Down"
• CURRENT_STATUS grows indefinitely → transfer to WORKLOG at phase transitions
• WORKLOG grows past ~1000 lines untouched → archive per spec §5.5
• Phase principles become permanent legacy → review at transition

---

Optional Extensions

• PARKING_LOT.md — Deferred items with preconditions for revival. Create only when needed.
• PHILOSOPHY.md — Principles forged by project practice. Create only when insights generalize.
• inbox/outbox — File-based cross-project messaging. Adopt only if project has dependencies.

See [references/spec.md](references/spec.md) for full details.

---

Reference Documents

| File | When to read | |------|-------------| | [references/init.md](references/init.md) | User asks to set up / initialize doc-harness | | [references/check.md](references/check.md) | User asks to audit / check documentation health | | [references/sync.md](references/sync.md) | User asks to sync / update status docs | | [references/flush.md](references/flush.md) | User asks to save / flush context before compression | | [references/resume.md](references/resume.md) | User asks to resume / continue project work after context loss or on arrival | | [references/recall.md](references/recall.md) | User asks to recall / search / find information in project docs | | [references/spec.md](references/spec.md) | Unusual situation, edge case, or understanding design rationale |

Language note: All documents are written in English with Chinese annotations where helpful. Kimi should respond in the user's language regardless of document language.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cilidinezy-commits
• Source: cilidinezy-commits/doc-harness
• License: MIT

Install and usage instructions live in the source repository linked above.