# Generation: Commands

## Purpose

Generate standalone slash commands in `.claude/commands/forge/` that serve as
entry points to the generated workflows. The namespace is FIXED to `forge`
(CLI-first redesign): every project gets the same `/forge:*` surface, matching
what the `4ge` bootstrap vendors. Project-prefix namespaces (`/acme:*`,
`/ember:*`) are retired — they existed to avoid collisions with the Forge
*plugin's* own commands, moot now that the plugin mechanism is retired.

## Inputs

- Generated workflows (from Phase 5) — their exact filenames and paths
- `.forge/config.json` — paths (project prefix no longer affects the command namespace)

## Outputs

`.claude/commands/forge/` with the fixed-namespace commands:
- `new-sprint.md` → `/forge:new-sprint`
- `plan.md` → `/forge:plan {TASK_ID}`
- `review-plan.md` → `/forge:review-plan {TASK_ID}`
- `implement.md` → `/forge:implement {TASK_ID}`
- `review-code.md` → `/forge:review-code {TASK_ID}`
- `fix-bug.md` → `/forge:fix-bug {BUG_ID}`
- `plan-sprint.md` → `/forge:plan-sprint`
- `run-task.md` → `/forge:run-task {TASK_ID}`
- `run-sprint.md` → `/forge:run-sprint {SPRINT_ID} [--parallel]`
- `collate.md` → `/forge:collate [SPRINT_ID]`
- `retro.md` → `/forge:retro {SPRINT_ID}`
- `approve.md` → `/forge:approve {TASK_ID}`
- `commit.md` → `/forge:commit {TASK_ID}`
- `check-agent.md` → `/forge:check-agent $ARGUMENTS`
- `enhance.md` → `/forge:enhance $ARGUMENTS`
- `validate.md` → `/forge:validate {TASK_ID}`

## Instructions

**Scope boundary:** Only ever read, write, or delete files in the explicit output list above (16 files).
Never touch any other file in `.claude/commands/` — custom commands, project-specific
wrappers, and unrecognised files must be left completely untouched.

**Pre-generation check (idempotency):** For each command file listed above, before writing:
1. Check first whether the file exists at the **flat path** `.claude/commands/{filename}.md`
   (old non-namespaced location). If it does, treat it as non-conformant — overwrite into
   the namespaced path and log: `Replaced flat command (now namespaced): <filename>`.
2. If the file does not exist at either path — write it fresh to the namespaced path.
3. If the file exists at the namespaced path `.claude/commands/forge/{filename}.md` — read it
   and extract the workflow path it references (the `.forge/workflows/` path).
   - If it does NOT reference `.forge/workflows/` — overwrite and log: `Replaced stale command: <filename>`.
   - If it references `.forge/workflows/` but that workflow file **does not exist on disk** — overwrite and log: `Replaced command pointing to missing workflow: <filename>`.
   - If it references `.forge/workflows/` and the workflow file exists — check whether the file matches the template format. If it is missing `effort:` frontmatter, contains `model:` frontmatter, contains a MASTER_INDEX read line, or uses old workflow naming (`engineer_*`, `supervisor_*`) — overwrite and log: `Replaced non-conformant command: <filename>`.
   - **wfl: dispatch rung (scoped to three filenames only):** If the filename is one of `run-task.md`, `run-sprint.md`, or `fix-bug.md` — and the file body contains `Read .forge/workflows/` — it is non-conformant (it should use `wfl:` dispatch instead). Overwrite it with the `workflow('wfl:run-task'|'wfl:run-sprint'|'wfl:fix-bug', $ARGUMENTS)` body and log: `Replaced non-conformant command: <filename>`. Do NOT apply this rung to any other command — the other 13 commands legitimately use `Read .forge/workflows/` and must not be flagged.
   - If it matches the template format and the workflow exists — skip it (already up to date).

This ensures any workflow that has been renamed or replaced causes its command wrapper to be regenerated rather than silently left pointing at a missing file.

Each command file MUST follow this exact template — no variations, no additions:

```markdown
---
description: {{description}}
effort: {{effort}}
---
Read `.forge/workflows/{{workflow}}.md` and follow it exactly.
{{argument_line}}
<!-- AUTO-GENERATED by /forge:init -->
```

Where:
- `{{description}}` — from the descriptions table below (fixed, not model-generated)
- `{{effort}}` — from the effort table below (fixed mapping, not model choice)
- `{{workflow}}` — the exact filename of the generated workflow (no path prefix, no `engineer_`/`supervisor_` role prefix)
- `{{argument_line}}` — one of: `Task ID: $ARGUMENTS`, `Sprint ID: $ARGUMENTS`, `Bug ID: $ARGUMENTS`, or `Arguments: $ARGUMENTS`

**Do NOT deviate from this template.** Specifically:
- Do NOT include a `Read {KB_PATH}/MASTER_INDEX.md` line. The workflow loads MASTER_INDEX as its first step — pre-loading it gives the model enough context to rationalise skipping the workflow entirely and doing the work inline. Workflow first, always.
- Do NOT include `model:` frontmatter (use `effort:` instead — model-agnostic).
- Do NOT add numbered step lists, explanations, or any content beyond the template.
- Do NOT add a `Also read` line for any file — the workflow controls all context loading.

**Per-command descriptions** (fixed, not model-generated):

| Command | description |
|---|---|
| `plan.md` | Design and document the implementation plan for a task |
| `review-plan.md` | Architectural review of a task implementation plan |
| `implement.md` | Execute the approved implementation plan for a task |
| `review-code.md` | Code quality review of a completed task implementation |
| `fix-bug.md` | Triage, diagnose, and fix a bug |
| `approve.md` | Final architect approval gate for a completed task |
| `commit.md` | Stage and commit completed task artifacts |
| `run-task.md` | Orchestrate the full plan→implement→review→approve pipeline for a task |
| `run-sprint.md` | Execute all tasks in a sprint (sequential or parallel) |
| `new-sprint.md` | Elicit and structure requirements for a new sprint |
| `plan-sprint.md` | Decompose sprint requirements into tasks with dependencies |
| `collate.md` | Regenerate KB documents from the JSON store |
| `retro.md` | Produce sprint retrospective and lessons-learned document |
| `check-agent.md` | Verify an agent has read and understood the project KB before high-stakes tasks |
| `enhance.md` | Progressive project-specific enrichment of structural elements |
| `validate.md` | Validate that a task implementation satisfies acceptance criteria |

**Effort levels** — use `effort:` frontmatter (capability request, model-agnostic):

| Command | effort | Rationale |
|---|---|---|
| `review-plan.md` | `max` | Architectural gate — needs deepest reasoning |
| `review-code.md` | `max` | Quality gate — needs deepest reasoning |
| `approve.md` | `max` | Final approval gate |
| `plan.md` | `high` | Design work with broad codebase context |
| `implement.md` | `high` | Non-trivial code generation |
| `fix-bug.md` | `high` | Diagnosis + fix |
| `plan-sprint.md` | `high` | Decomposition and dependency analysis |
| `run-task.md` | `high` | Full task orchestration |
| `run-sprint.md` | `high` | Multi-task orchestration |
| `new-sprint.md` | `high` | Structured requirements elicitation |
| `retro.md` | `medium` | Reflection and summary |
| `collate.md` | `low` | Mechanical markdown regeneration |
| `commit.md` | `low` | Staging and committing completed work |
| `check-agent.md` | `medium` | Short factual quiz — moderate reasoning, no deep codebase traversal |
| `enhance.md` | `high` | Enhancement agent — broad structural enrichment |
| `validate.md` | `max` | Validation gate — needs deepest reasoning |

Do **not** include `model:` frontmatter — that directive pins a specific model and is
not appropriate for user command files.

After writing each command file, record it in the generation manifest:
```sh
node "$FORGE_ROOT/tools/generation-manifest.cjs" record {paths.commands}/forge/{filename}.md
```

(`FORGE_ROOT` is available from the parent init flow; tool invocations use `$FORGE_ROOT/tools/` throughout.)

## Post-generation: flat-file cleanup

After all 16 command files have been written and recorded, scan for pre-v0.13.0
flat command files that were never namespaced. These are the **13 known flat filenames**:

```
new-sprint.md  plan-sprint.md  run-task.md   run-sprint.md  plan.md
review-plan.md    implement.md    review-code.md fix-bug.md     approve.md
commit.md         collate.md      retro.md
```

Check for each at `.claude/commands/{filename}.md` (the flat path, NOT the namespaced
subdirectory).

**Logic:**

- If **none** of the 13 files exist at the flat path — skip silently. No prompt.

- If **one or more** exist, display the list:
  ```
  Found pre-v0.13.0 flat command files that are no longer used:
    .claude/commands/plan.md
    .claude/commands/implement.md
    ... (list each found file)

  These have been replaced by namespaced commands under .claude/commands/forge/.
  Remove them now? (yes / skip)
  ```

  - **On `yes`:** Delete each found file. For each deletion, print:
    `Removed: .claude/commands/{filename}.md`
    When done: `Flat command cleanup complete.`

  - **On `skip`:** Print:
    `Skipped. Remember to delete these files manually to avoid command name collisions.`

**Do NOT delete any file that is not in the 13-filename list above.** Custom commands,
project-specific wrappers, and unrecognised files are strictly off-limits.