/project -- Project Orchestrator

Bootstraps project state on first run, reports status, and routes to the correct next
skill on every subsequent invocation. Read-only after bootstrap.

Rules

• Read fresh every time. Read all state files from disk on every invocation -- never
  rely on conversation memory or cached values (STATE-03).
• Read-only after bootstrap. After the initial progress.txt creation, /project
  never modifies progress.txt or any other file (PROJ-10) -- two exceptions exist:
  bootstrap (Step 2) and Gate 3 closure (Step 5, when all milestones are complete).
• Route, never dispatch. Tell the user which skill to run next via plain-language
  instruction. Never auto-invoke or auto-dispatch another skill (DD-2).
• Write-ordering contract for downstream skills. When both milestone-status.txt and
  progress.txt need updates, write milestone-status.txt first -- source-of-truth-first
  ordering (STATE-04). This rule applies to /build and /milestone, not to /project or /plan-feature.
• Interactive prompts. Use AskUserQuestion for all user-facing choices (2-4 options,
  max 12-character option headers).

Prerequisites

• Working directory is the project root (the directory where progress.txt lives or will
  be created).
• No other files or directories are required -- /project handles first-run detection
  automatically.

Step 1 -- Detect Project State

Read progress.txt from the project root.

• If the file does not exist, proceed to Step 2 (Bootstrap).
• If the file exists but is a light progress.txt (inline [ ] Feature X.Y lines and no
  ## Gates / ## Milestones sections), it is owned by /create-prd + /start-feature, not the
  gated workflow. Stop and tell the user: this directory is under the light workflow — use
  /start-feature here, or run /project from a directory with no light progress.txt. Do not
  parse it as gated state and do not overwrite it.
• If the file exists with the gated schema (## Gates / ## Milestones), proceed to Step 3
  (Read State).

Step 2 -- Bootstrap

This is the ONLY time /project writes to disk.

1. Read references/progress-format.md for the exact bootstrap template, slug derivation
   rules, and format rules.
2. Detect greenfield vs brownfield:
   • Greenfield: project directory is empty or contains only boilerplate files (README,
     .gitignore, package.json with no src/ directory). Use the greenfield variant --
     Gate 0 recorded as [-] Gate 0: Codebase Alignment Skipped (greenfield) (per DD-10).
   • Brownfield: existing source code is present. Use the standard template -- Gate 0
     recorded as [ ] Gate 0: Codebase Alignment.
3. Determine the project name and slug:
   • Derive a candidate name from the working directory name.
   • Derive a candidate slug from that name using the slug derivation rules in
     references/progress-format.md (lowercase, hyphens, alphanumeric only).
   • Use AskUserQuestion to confirm or override the name before writing:
     • Present the derived name and slug as the default option.
     • Offer the user a chance to provide a custom name; the slug is always re-derived
       from the name — it is not set independently.
4. Use the Write tool to create progress.txt with the bootstrap template, replacing
   <Project Name> with the confirmed project name, <slug> with the confirmed slug,
   and <ISO date> with today's date (YYYY-MM-DD).
5. Read the file back and confirm it was created correctly.
6. Show the user the created file content.
7. Proceed to Step 3 (Read State) to display the initial status report.

Step 3 -- Read State

Read progress.txt from disk (fresh read -- STATE-03). Parse:

• # Project-ID: <slug> header line -- derive the artifact base path: .project/<slug>/.
  All artifact reads and writes use this base path for the remainder of the invocation.
• All gate entries in the ## Gates section (status marker, name, date, artifact path).
• All milestone summary lines in the ## Milestones section (status, name, path, feature
  counts).
• All spike entries in the ## Spikes section (status, name, path, resolution date).

For each milestone found, read its milestone-status.txt at
.project/<slug>/milestones/<NN>-<name>/milestone-status.txt (the directory path is read
verbatim from the milestone summary line, which already carries the resolved
.project/<slug>/ base path -- do not prepend the base path again).

Read references/routing-logic.md for validation rules, then perform:

• Artifact validation (PROJ-04): For each [x] gate, check that the artifact path
  listed on the gate entry line exists on disk. If missing, record an inline warning.
• Consistency validation (PROJ-05): For each milestone, compare the N/M features complete count in progress.txt against the actual [x] feature count in the
  corresponding milestone-status.txt. If they diverge, record a consistency warning.

Collect all warnings. Proceed to Step 4 (Status Report).

Step 4 -- Status Report

Read references/status-report-format.md for the exact output format and structure.

Display the status report to the user following this order:

1. Gate WB Pending reminder (conditional): If Gate WB is [ ] Pending, show a gentle
   reminder at the top of the report per D-09. This does NOT suppress the rest of the
   report -- the full status display continues below the reminder.
2. GATES: Checklist of all gates with status, dates, artifact paths. Inline warnings
   (D-06) appear directly after the gate entry they affect.
3. ACTIVE MILESTONE: Expanded view with per-feature status from milestone-status.txt.
   Consistency divergence warnings appear inline after the milestone header.
4. COMPLETED MILESTONES: One-line summaries (shown only if any milestones are complete).
5. UPCOMING MILESTONES: One-line summaries (shown only if upcoming milestones exist).
6. SPIKES: All spikes -- both open and resolved (per D-02). Never remove resolved spikes.

If a consistency divergence is detected (D-07 blocking behavior): display the full status
report, but replace the RECOMMENDED section with a request for the user to acknowledge the
discrepancy before routing can proceed.

Proceed to Step 5 (Route).

Step 5 -- Route

Read references/routing-logic.md for the complete routing table and re-planning keywords.

Re-planning intent detection (D-05, PROJ-08, PROJ-09): Check if the user's message
contains keywords signaling revision intent:

• PRD revision triggers: "goals changed", "revise PRD", "pivot", "change direction",
  "update requirements", "scope change" -- route to /define in revision mode.
• Milestone revision triggers: "re-plan", "revise milestone", "regroup features",
  "change milestone", "re-scope" -- route to /milestone in revision mode.

Normal routing: Determine the recommended next action based on the current project
state using the routing table. Display per D-03:

• One RECOMMENDED action, clearly highlighted.
• 2-3 Also available alternatives listed below (per D-04: only actions valid for the
  current project state).

Gate WB offer (DD-11, D-08): If Gate 0 is approved ([x]) or skipped ([-] greenfield),
no .project/{slug}/docs/working-backwards.md exists (where {slug} is the value parsed
from the # Project-ID: header), Gate WB has not been offered yet, and the customer
outcome is unclear -- offer Gate WB using AskUserQuestion with options:

• Yes -- proceed with Working Backwards exercise (routes to /define)
• Skip -- record Gate WB as skipped
• Defer -- record Gate WB as Pending for later decision

Include a 2-3 sentence explanation of the Working Backwards value proposition.

Gate 3 closure offer (D-01 through D-05, PROJ-10): If all milestones in progress.txt
are [x] complete AND Gate 3 is still [~] In progress -- offer Gate 3 closure using
AskUserQuestion with options:

• Close Gate 3 -- write [x] Gate 3: Milestone Review Approved: <YYYY-MM-DD> (closed by /project)
  to progress.txt (replacing the [~] In progress line), where <YYYY-MM-DD> is today's date.
  Then continue to routing (the "All milestones complete" row will show "Project complete").
• Leave open -- skip the write. Continue to normal routing (the "All milestones complete"
  row will still show "Project complete").

Show a 1-line explanation before the prompt: "Gate 3 tracks milestone planning. Closing it
marks the milestone review phase officially complete."

After AskUserQuestion resolves (regardless of which option the user chose), continue to
normal routing table evaluation.

If the user chose Close Gate 3: use the Write tool to update the Gate 3 line in
progress.txt. Read the file first, replace [~] Gate 3: Milestone Review In progress
with [x] Gate 3: Milestone Review Approved: <YYYY-MM-DD> (closed by /project). Read the
file back and confirm the update was applied correctly before proceeding to routing.

Error Handling

• Malformed progress.txt: If the file is missing required headers or has corrupted
  entries, report the issue to the user. Suggest checking git history for a clean version.
  Do not attempt to repair the file.
• Missing milestone-status.txt: If a milestone directory exists but its
  milestone-status.txt is missing, warn the user but continue -- the milestone may be
  partially created. Show the warning inline in the status report.
• Ambiguous user intent: If the user's request is unclear, use AskUserQuestion to
  ask for clarification rather than guessing the intended action.
• Empty project (post-bootstrap): When all gates are pending, no milestones exist, and
  no spikes exist, display the empty project report format from references/status-report-format.md.
  The only valid recommendation is to run /define.
• Interrupted bootstrap: If /project is re-invoked after a failed bootstrap attempt
  (e.g., progress.txt exists but is empty or incomplete), treat the file as malformed and
  report the issue rather than attempting a second bootstrap.