project-update

Project Update

Run this workflow only for existing projects with initialized docs.

Before starting:

Require both docs/architecture.md and docs/plans.md .
If both files are missing and code exists, switch to project-convert .
If docs and code are both missing, switch to project-init .
If only one required doc exists, report partial state and ask user whether to repair via convert, continue with caution, or re-init.

Load current state first:

Read docs/architecture.md and docs/plans.md .
Read supporting docs: docs/implement.md , docs/secrets.md , docs/documentation.md , docs/design.md .
Auto-create missing supporting docs from templates before update edits.
Summarize current milestones, architecture, and patterns to the user.
If code exists, scan code roots and compare docs vs code; report major divergences before planning.

Classify and announce one type (allow override):

Reclassify if discovered scope no longer matches the original type.

Update existing files instead of recreating:

Always update docs/plans.md by inserting new milestones before the final Production Readiness Gate milestone.
Always update docs/documentation.md status section.
Update docs/architecture.md only where behavior/spec/architecture is affected.
Update docs/design.md , docs/secrets.md , CLAUDE.md , AGENTS.md only when the change impacts them.
Keep completed milestone history intact unless fixing proven inconsistency.
Do not silently remove replaced requirements; mark and explain transitions.
Keep docs/implement.md aligned with these mandatory sections:
First-Principles Execution
Atomic Task Execution
Rewrite-First Policy
No-Compatibility Rule
In docs/plans.md , every new or modified task must include Commit Boundary: exactly one atomic commit .
In tasks/todo.md , every new or modified task must include Task ID and Commit Status (pending or done ).

5.5. Implementation Discipline (Mandatory)

Apply these rules to every update task:

Use first-principles execution: address root causes based on product intent and architecture, not workaround layers.
Treat task and sub-task as the same execution unit.
Enforce one task -> one atomic commit .
Complete one task end-to-end before commit, including all impacted files (code/tests/config/scripts/docs).
Follow code is cheap : prefer deleting and rewriting problematic modules instead of patching around them.
Never introduce compatibility code (adapter , shim , dual-path logic, deprecated aliases, temporary compatibility flags).
If a rewrite changes interfaces, update all impacted callers in the same task.
Do not split breakage repair into later tasks.

Run lightweight review on modified scope:

Agent 2 (plans coverage) + Agent 3 (cross-doc consistency).
Mandatory mcp__codex__codex review on changed sections (or full docs if needed).
Apply valid findings, then run exactly one Agent 2 + Agent 3 post-Codex re-review.
Run one user annotation pass on updated docs/architecture.md

docs/plans.md (Bug Fix can skip only when strictly local and behavior docs are unchanged).

If mcp__codex__codex is unavailable, stop and ask user to choose manual checklist path or alternate-model path.

Install/update hooks for both platforms:

bash <resolved-setup-hooks-path> --pm <detected-pm> --project-dir <project-dir> --platform both

Detect package manager using lockfiles (bun.lock , pnpm-lock.yaml , yarn.lock , fallback npm).
If no installer path exists, ask the user where their hook installer lives and stop.
If install fails, show error and stop.

Tell the user:

Source Transparency