pm-as-code

name: pm-as-code description: "Strict Markdown project management with status.md as the canonical entrypoint: checkbox-only tasks with IDs, acceptance criteria, evidence, and append-only pulse history. Includes no-dependency Bash and Windows (PowerShell/CMD) ticket and collab wrappers for long-running and multi-agent repos."

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