# progress.md discipline ## When to have one Every project with **concurrent dispatches** in flight maintains a live progress tracker at `projects//progress.md`. Concurrent = two or more workers running at the same time under the same project umbrella. Single-thread work does not need a progress.md; the chat thread is sufficient. But if you find the chat becoming lossy (worker returns mix with operator replies about a different topic), the fix is to spin up a project and create the tracker. ## Shape - **Newest entries on top.** Log-style — most recent first. - **Each entry.** Timestamp (UTC ISO), one-line status, key artefacts (work-item IDs, PR URLs, commit SHAs, agent IDs). - **Top-of-file "Status" block.** Current overall state, live work items, live dispatches. Rewritten in-place as state changes. ## What NOT to put here - Full work-item JSON — work items live in `work/`. - Full brief text — briefs live in the spawn-log entry or a briefs directory. - Chat conversation transcript — the tracker is a state doc, not a conversation log. - Discussion / design notes — those go in project-specific notes docs. The tracker **references**, does not duplicate. Work items in `work/` and `spawn-log.json` stay the system of record. `progress.md` is the human-readable digest that links to them. ## When to create it - As soon as you open a project. - As soon as concurrent work starts on an existing project that doesn't have one yet. Do not wait for two dispatches to be in flight to create the tracker — create it at the trigger and let the first dispatch's entry be the first log line. ## When to update At every material state change. New dispatch fired; dispatch returned; PR opened; PR merged; blocker discovered; blocker cleared; direction change. Do not batch to session-end. ## Related - CLAUDE.md.template Bucket 2 rule 3. - `pa project doc add projects//progress.md --label "Live progress tracker" --status live` — register the tracker on the project manifest.