pm-as-code

# PM as Code ## Contract - Read `status.md` first in every session. - Treat `status.md` as a generated snapshot; never edit it manually. - Keep all actionables as checkboxes only: `- [ ]` or `- [x]`. - Give every task an ID (`T-0001`, `T-0002`, ...), and keep counters in `status.md`. - Keep required section order exactly as defined in `references/status-template.md`. - Keep acceptance criteria for active tasks keyed by task ID. - Treat Pulse history as append-only. - Resolve ambiguity by updating docs, never by relying on chat memory. - Route every state mutation through collab wrappers by default: - `scripts/pm-collab.sh` (Bash) - `scripts/pm-collab.ps1` or `scripts/pm-collab.cmd` (Windows) - Use `pm-collab run <pm-ticket command...>`; it auto-resolves agent identity and auto-claims task IDs when needed. - Agent identity resolution order: `PM_AGENT` -> `CODEX_THREAD_ID` -> `CLAUDE_SESSION_ID` -> host fallback. - Use `pm-ticket.*` directly only for read-only/status commands or maintenance. - Empty state is not a blocker: if `status.md`/`.pm` do not exist yet, run `pm-collab ... init` and continue. - If repo-local wrappers are missing, invoke installed skill scripts directly (for example from `~/.codex/skills/pm-as-code/scripts/` or `~/.claude/skills/pm-as-code/scripts/`). ## Done Gate A task is done only when all are true: - task checkbox is `[x]` - acceptance criteria are `[x]` - evidence is recorded - `Now / In progress / Blocked / Next` are updated - a new Pulse entry is appended ## Session Loop 1. Read `status.md`. 2. Select scope (`--scope` or `PM_SCOPE`) and ensure initialization (`pm-collab ... init` or automatic bootstrap on first `pm-collab run` mutation). 3. Execute one active task ID (prefer `Now`) with `pm-collab run ...`. 4. If new work appears, create a new task ID immediately via `pm-collab run new ...`. 5. If blocked, move task to `Blocked` with explicit blocker text via `pm-collab run move ...`. 6. On completion, run the Done Gate through `pm-collab run done ...` (render is automatic). ## Mode Selection Use ledger mode by default: - `scripts/pm-collab.sh` (Bash) - `scripts/pm-collab.ps1` or `scripts/pm-collab.cmd` (Windows) - Prefer scoped ledgers for parallel teams: `--scope <name>` (or `PM_SCOPE`). - Ledger files in `.pm/scopes/<scope>/*` are the machine record. - Manual edits to `status.md` are forbidden; script render is authoritative. - `status.md` is rendered: - single default scope: full snapshot - multiple scopes (or non-default only): compact scope index to `status.<scope>.md` Notes: - `pm-collab run ...` works for both single-agent and multi-agent workflows. - Explicit `claim`/`unclaim` remains available for manual reservation control. ## Concurrency Policy Concurrent edits are expected in multi-agent work. Default behavior: - Do not hand-edit `status.md` during concurrent work. - Perform writes through `pm-collab ... run` for lock + claim enforcement. - Re-render snapshot after task updates. Escalate only on true same-task conflicts: - target task ID missing - duplicated task ID - acceptance criteria block for that ID cannot be mapped safely If conflict is true same-task: - create a new task `Resolve status conflict for <ID>` - move original task to `Blocked` with blocker noted For teammate handoffs, use a bounded task pack: - `scripts/pm-ticket.sh [--scope <name>] render-context <T-0001> [evidence-tail]` - `scripts/pm-ticket.ps1 [--scope <name>] render-context <T-0001> [evidence-tail]` ## References - `references/pm-rules.md` - `references/status-template.md` - `references/optional-doc-templates.md` - `references/compact-ticket-system.md`