@entelligentsia/forgecli 0.3.0 → 0.7.6

package/dist/forge-payload/commands/config.md

@@ -0,0 +1,202 @@
+---
+name: config
+description: Inspect or change Forge project configuration. Owns the mode field — the explicit verb for promoting a fast-mode install to full.
+---
+
+# /forge:config
+
+Read or change `.forge/config.json` values that are user-facing decisions
+(currently: `mode`). Other config keys remain managed by their respective
+commands (e.g. `paths.forgeRoot` is refreshed by `/forge:update`).
+
+## Locate the Forge plugin
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+Read `.forge/config.json`. If it does not exist, stop and emit:
+
+```
+× .forge/config.json not found. Run /forge:init first.
+```
+
+Then exit. (`manage-config.cjs` already prints this same message on missing
+config, so the user-visible behaviour is consistent if you only invoke the
+tool.)
+
+## Arguments
+
+$ARGUMENTS
+
+Parse the argument:
+
+```
+/forge:config                    # Print summary of .forge/config.json
+/forge:config mode               # Print current mode
+/forge:config mode full          # Promote fast → full
+/forge:config mode fast          # Refused (one-way transition)
+```
+
+The command shape is reserved for future expansion (e.g. `/forge:config kb
+<path>`, `/forge:config paths <key> <value>`). Only the subcommands above
+are implemented today.
+
+---
+
+## Visual
+
+For all subcommands, open with a single `north` badge (config = bearings):
+
+```sh
+node "$FORGE_ROOT/tools/banners.cjs" --badge north
+```
+
+Subcommands that change state (`mode full`) also render a `forge` badge
+inside the promotion sequence; subcommands that are read-only just print
+the summary after the badge.
+
+`banners.cjs` strips ANSI in `NO_COLOR` / non-tty / `--plain` contexts.
+
+---
+
+## Subcommand: `/forge:config` (no args) — summary
+
+Read `.forge/config.json`. Emit a summary block:
+
+```
+━━━ Forge Configuration ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  mode:        {mode | "unset"}
+  version:     {version}
+  project:     {project.name} ({project.prefix})
+
+  Paths
+    engineering:   {paths.engineering}
+    store:         {paths.store}
+    workflows:     {paths.workflows}
+    commands:      {paths.commands}
+    templates:     {paths.templates}
+    forgeRoot:     {paths.forgeRoot}
+
+  Installed skills ({installedSkills.length})
+    {one per line}
+```
+
+Use these tool invocations:
+
+```sh
+node "$FORGE_ROOT/tools/manage-config.cjs" get mode 2>/dev/null || echo "unset"
+node "$FORGE_ROOT/tools/manage-config.cjs" get version
+node "$FORGE_ROOT/tools/manage-config.cjs" get project
+node "$FORGE_ROOT/tools/manage-config.cjs" get paths
+node "$FORGE_ROOT/tools/manage-config.cjs" get installedSkills 2>/dev/null
+```
+
+This subcommand is **read-only** — it never writes to disk.
+
+---
+
+## Subcommand: `/forge:config mode` — print current mode
+
+Read the `mode` field. Print one of:
+
+```
+fast
+full
+unset
+```
+
+Use:
+```sh
+node "$FORGE_ROOT/tools/manage-config.cjs" get mode 2>/dev/null || echo "unset"
+```
+
+Read-only.
+
+---
+
+## Subcommand: `/forge:config mode full` — promote fast → full
+
+Promote the project from fast mode to full mode. This is a one-way
+transition: it materialises every deferred artifact and refreshes everything
+that was already materialised, then writes `mode: full`.
+
+### Promotion sequence
+
+1. **Read current mode**:
+   ```sh
+   CURRENT_MODE=$(node "$FORGE_ROOT/tools/manage-config.cjs" get mode 2>/dev/null || echo "unset")
+   ```
+
+2. **Short-circuit if already full**:
+   - If `CURRENT_MODE == "full"`: emit `〇 Already in full mode. Nothing to do.` and exit 0.
+   - If `CURRENT_MODE == "unset"`: treat as `full` (the project predates the
+     mode field — it is already a full install). Emit
+     `〇 mode is unset (legacy full install). Writing mode: full.`, then jump
+     to Step 5 (skip materialize + regenerate, just write the field).
+
+3. **Emit promotion banner** (forge badge + em-dash separator):
+   ```sh
+   node "$FORGE_ROOT/tools/banners.cjs" --badge forge
+   ```
+   ```
+   ━━━ Promoting to Full Mode ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```
+
+4. **Run materialize-all**: read `$FORGE_ROOT/commands/materialize.md` and
+   follow the **Full warm-up** branch (no arguments). This fills any
+   missing or stubbed personas, skills, templates, and workflows.
+
+   This step is intentionally invoked by reading the rulebook — do not
+   inline its logic. If materialize errors, surface the error and stop;
+   do not write `mode: full`.
+
+5. **Run default regenerate**: read `$FORGE_ROOT/commands/regenerate.md`
+   and follow the **Default (no argument)** branch. With everything now
+   materialised, every artifact gets refreshed against the current
+   meta-definitions.
+
+   If regenerate errors, surface the error and stop; do not write
+   `mode: full`.
+
+6. **Write `mode: full`**:
+   ```sh
+   node "$FORGE_ROOT/tools/manage-config.cjs" set mode full
+   ```
+
+7. **Emit completion**:
+   ```
+   〇 Promoted to full mode.
+   ```
+
+### Invariant
+
+This is the only code path in the Forge plugin that writes `mode: full`
+after initial install. `regenerate` and `materialize` are
+mode-neutral — they read mode but never write it.
+
+---
+
+## Subcommand: `/forge:config mode fast` — refused
+
+Read the current mode.
+
+- If `CURRENT_MODE == "fast"` (or `unset`): emit
+  `〇 Already in fast mode.` and exit 0.
+- Otherwise: emit and exit non-zero (status 1):
+  ```
+  × Cannot downgrade full → fast. Use /forge:remove and re-init to reset.
+  ```
+
+There is no automatic full → fast transition — the artefacts that were
+materialised in full mode are real files with content; "demoting" them
+would mean deleting work without telling the user what was lost. The
+remove-and-re-init path is the explicit, observable way to reset.
+
+---
+
+## On error
+
+If any step above fails unexpectedly, describe what went wrong and ask:
+
+> "This looks like a Forge bug. Would you like to file a report to help improve it? Run `/forge:report-bug` — I'll pre-fill the report from this conversation."

package/dist/forge-payload/commands/enhance.md

@@ -0,0 +1,38 @@
+---
+name: enhance
+description: Run the enhancement agent to fill placeholders, propose persona enrichments, or detect drift
+---
+
+# /forge:enhance
+
+Run the Enhancement Agent to improve installed `.forge/` structural elements. The agent
+operates in three modes selected by the `--phase` flag.
+
+## Locate the Forge plugin
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+Read `$FORGE_ROOT/meta/workflows/meta-enhance.md` and follow it. Pass `$ARGUMENTS` through
+so the workflow receives the phase flag and any other options.
+
+## Arguments
+
+$ARGUMENTS
+
+| Flag | Purpose |
+|------|---------|
+| `--phase 1` | Auto-apply: fill unsubstituted `{{KEY}}` placeholders using codebase signals (post-init mode) |
+| `--phase 2` | Propose diffs: scan sprint artifacts and friction events; propose persona/skill enrichments for user review |
+| `--phase 3` | Drift detection: full codebase vs structural-element comparison; propose targeted patches |
+| `--auto`    | Synonym for `--phase 1` — used by the post-init hook (T09) |
+
+Default: `--phase 3` when no flag is provided.
+
+## On error
+
+If the enhancement workflow is not found at `$FORGE_ROOT/meta/workflows/meta-enhance.md`,
+emit:
+
+> △ meta-enhance.md not found — your installed Forge version may predate the enhancement agent. Run `/forge:update` to upgrade.

package/dist/forge-payload/commands/health.md

@@ -0,0 +1,225 @@
+---
+name: health
+description: Use when you want to check if the engineering knowledge base is stale, has gaps, or has store integrity issues
+---
+
+# /forge:health
+
+Assess the health and currency of the project's SDLC knowledge base.
+
+## Checks
+
+| Check | What It Detects |
+|-------|----------------|
+| **Config completeness** | Missing required fields in `.forge/config.json` — blocks further checks if incomplete |
+| **KB freshness** | Hash mismatch between current `MASTER_INDEX.md` and calibration baseline — detects technical or business drift |
+| **Stale docs** | Architecture sub-docs not updated in N sprints |
+| **Orphaned entities** | Entities in code (ORM models, types) not in `engineering/business-domain/entity-model.md` |
+| **Unused checklist items** | Stack-checklist items never triggered in reviews |
+| **Coverage gaps** | Architecture areas with no sub-document |
+| **Writeback backlog** | `[?]` items not yet confirmed by a retrospective |
+| **Store integrity** | Run `node "$FORGE_ROOT/tools/validate-store.cjs" --dry-run` |
+| **Modified generated files** | Generated files that have been manually edited since last recorded — run `node "$FORGE_ROOT/tools/generation-manifest.cjs" list --modified` |
+| **Generated file structure** | Files expected by the plugin's structure-manifest that are absent from `.forge/` or `.claude/commands/` |
+| **Skill gaps** | Marketplace skills relevant to the stack that are not installed |
+| **Feature Test Coverage** | Features with zero tagged tests |
+| **Concepts freshness** | `docs/concepts/*.md` pages older than `forge/meta/store-schema/` updates |
+| **Context pack freshness** | `source_hash` in `.forge/cache/context-pack.json` vs. current hash of `engineering/architecture/*.md` |
+| **Plugin integrity** | Plugin command and agent files modified since last release hash was recorded |
+
+## How to run
+
+First, resolve the plugin root and project root:
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+Open the run with the oracle hero + subtitle:
+
+```sh
+node "$FORGE_ROOT/tools/banners.cjs" oracle
+node "$FORGE_ROOT/tools/banners.cjs" --subtitle "Reading the project's pulse — config, KB freshness, store integrity, structural completeness"
+```
+
+`banners.cjs` strips ANSI in `NO_COLOR` / non-tty / `--plain` contexts.
+
+Parse `$ARGUMENTS` for a `--path <dir>` argument:
+- If present, `PROJECT_ROOT = <dir>` (absolute or relative to the current working directory — resolve to absolute).
+- If absent, `PROJECT_ROOT = .` (current working directory).
+
+All file paths below are relative to `PROJECT_ROOT`. All shell tool invocations must be run from `PROJECT_ROOT`:
+```sh
+cd "$PROJECT_ROOT" && node "$FORGE_ROOT/tools/..."
+```
+
+1. **Config-completeness check** — Read `$PROJECT_ROOT/.forge/config.json`.
+   If it does not exist, stop and tell the user to run `/forge:init` in that directory first.
+   If it exists, validate it against `$FORGE_ROOT/sdlc-config.schema.json`:
+   - Read the schema and extract all `required` fields at each level (top-level and nested objects).
+   - Required top-level fields: `version`, `project`, `stack`, `commands`, `paths`.
+   - Nested required fields: `project.prefix`, `project.name`, `commands.test`, `paths.engineering`, `paths.store`, `paths.workflows`, `paths.commands`, `paths.templates`.
+   - For each required field, verify it exists in the config and has a non-empty value.
+   - If all required fields are present and non-empty, emit:
+     > 〇 Config complete — all required fields present.
+   - If any required fields are missing or empty, list each missing field by path (e.g. `project.prefix`, `commands.test`) with a short description, then **exit early** with:
+     > △ Config incomplete — missing required fields:
+     >   · `project.prefix` — short project prefix (e.g. ACME)
+     >   · `commands.test` — test command (e.g. npm test)
+     >
+     > Run `/forge:init` to complete configuration.
+     Do **not** cascade into subsequent checks that may fail on incomplete config.
+2. **KB freshness check** — Read `calibrationBaseline` from `$PROJECT_ROOT/.forge/config.json`.
+   - If `calibrationBaseline` is absent, emit:
+     > △ No calibration baseline found — run `/forge:calibrate` to establish one.
+     Skip the freshness check and proceed to step 3.
+   - If `calibrationBaseline` exists, compute the current hash of `MASTER_INDEX.md` using the same algorithm as `/forge:init`:
+     ```sh
+     cd "$PROJECT_ROOT" && node -e "const crypto=require('crypto'),fs=require('fs'); const cfg=JSON.parse(fs.readFileSync('.forge/config.json','utf8')); const engPath=(cfg.paths&&cfg.paths.engineering)||'engineering'; const lines=fs.readFileSync(engPath+'/MASTER_INDEX.md','utf8').split('\n').filter(l=>l.trim()&&!l.trim().startsWith('<!--')); console.log(crypto.createHash('sha256').update(lines.join('\n')).digest('hex'))"
+     ```
+   - Compare the computed hash against `calibrationBaseline.masterIndexHash`:
+     - If they match, emit:
+       > 〇 KB fresh — no drift since last calibration (last calibrated: `calibrationBaseline.lastCalibrated`, version: `calibrationBaseline.version`)
+     - If they differ, read `$PROJECT_ROOT/engineering/MASTER_INDEX.md` and categorize the drift based on which sections have changed. Categorize sections as follows:
+       - **Technical sections**: stack, routing, database, deployment, processes, architecture, schemas, conventions, stack-checklist
+       - **Business sections**: entity-model, domain, features, acceptance criteria, business-domain
+       If changes are only in technical sections: emit "technical". If only in business sections: emit "business". If in both: emit "technical + business".
+       Emit:
+       > △ KB drifted — <category> changes detected since last calibration (last calibrated: `calibrationBaseline.lastCalibrated`)
+       >   Run `/forge:calibrate` to re-align the knowledge base.
+3. Read the knowledge base files in `$PROJECT_ROOT/engineering/`
+4. Read the store in `$PROJECT_ROOT/.forge/store/` for sprint/task history
+5. Scan the codebase for entities not in the knowledge base (Grep for model/type definitions)
+6. Run store validation:
+   ```sh
+   cd "$PROJECT_ROOT" && node "$FORGE_ROOT/tools/validate-store.cjs" --dry-run
+   ```
+   Include the result in the report.
+7. Check modified generated files:
+   ```sh
+   cd "$PROJECT_ROOT" && node "$FORGE_ROOT/tools/generation-manifest.cjs" list --modified
+   ```
+   If any modified or missing files are reported, include them in the health
+   report under **Modified generated files** with the note:
+   > These files were manually edited after generation. Regeneration will warn
+   > before overwriting them. Run `/forge:regenerate` to review and update.
+   If all files are pristine (or the tool is absent), omit this section.
+8. Check generated file structure:
+   ```sh
+   cd "$PROJECT_ROOT" && node "$FORGE_ROOT/tools/check-structure.cjs" --path "$PROJECT_ROOT"
+   ```
+   If missing files are reported, include them in the health report under
+   **Generated file structure** with note:
+   > N expected file(s) are missing from generated output. Run `/forge:update` to
+   > regenerate missing files, or `/forge:regenerate <namespace>` for targeted repair.
+   If all files are present (exit 0), emit:
+   > 〇 Generated file structure — all expected files present.
+   If the tool is absent (file not found), skip this check silently.
+   Note: custom `paths.*` overrides in `.forge/config.json` are respected by
+   check-structure.cjs. Projects using default paths will see no difference.
+9. Check skill gaps: run `node "$FORGE_ROOT/tools/list-skills.js"` to get the live
+   installed skill list from `~/.claude/plugins/installed_plugins.json` (source of
+   truth — not the config, which can be stale). Read `$FORGE_ROOT/meta/skill-recommendations.md`,
+   cross-reference the stack against live installed skills, report any uninstalled
+   high-confidence recommendations with one-line install instructions. If the live
+   list differs from `installedSkills` in config, update config to match.
+10. Check test coverage for active features:
+    - Read `$PROJECT_ROOT/.forge/store/features/` to find all features with `"status": "active"`.
+    - If zero active features exist, skip this check.
+    - Otherwise, scan all test directories under `$PROJECT_ROOT` (e.g. `test/`, `tests/`, `spec/`, `__tests__/`) and test files (`*.test.*`, `*.spec.*`) for the `FEAT-NNN` identifier of each active feature.
+    - You should account for three tag forms: filename (`feat-NNN-login.test.js`), test name string (`describe('[FEAT-NNN]')`), or docblock comment (`// @feat FEAT-NNN`).
+    - For each active feature, report the count of test files or names matching its ID.
+    - Warn explicitly: `⚠ FEAT-NNN has 0 tagged tests` if an active feature has zero hits.
+11. Check concepts freshness:
+    - Compare the modification timestamps of files in `$PROJECT_ROOT/docs/concepts/*.md` against the newest schema modification in `$FORGE_ROOT/meta/store-schema/`.
+    - If any concept doc is older than the newest schema change, emit a notice that it may be stale.
+12. Check persona pack freshness:
+    - If `$PROJECT_ROOT/.forge/cache/persona-pack.json` does not exist, emit:
+      > △ Persona pack missing — run `/forge:regenerate` to build it.
+      (The pack is consumed by `meta-orchestrate` and `meta-fix-bug` when `FORGE_PROMPT_MODE=reference`.)
+    - Otherwise read the pack's `source_hash`, then compute the current hash:
+      ```sh
+      CURRENT=$(node -e "const t=require('$FORGE_ROOT/tools/build-persona-pack.cjs'); console.log(t.computeSourceHash({personaDir:'$FORGE_ROOT/meta/personas', skillDir:'$FORGE_ROOT/meta/skills'}))")
+      STORED=$(node -e "console.log(require('$PROJECT_ROOT/.forge/cache/persona-pack.json').source_hash)")
+      ```
+      If `CURRENT != STORED`, emit:
+      > △ Persona pack stale — meta/ has changed since last build. Run `/forge:regenerate` to refresh.
+      Otherwise emit:
+      > 〇 Persona pack fresh.
+13. Check context pack freshness:
+    - Compute the current source hash over `engineering/architecture/*.md`
+      (excluding `*.draft.md`) using the same algorithm as `build-context-pack.cjs`:
+      ```sh
+      ENGINEERING=$(node "$FORGE_ROOT/tools/manage-config.cjs" get paths.engineering 2>/dev/null || echo engineering)
+      node "$FORGE_ROOT/tools/build-context-pack.cjs" --arch-dir "$ENGINEERING/architecture" 2>/dev/null
+      # The tool exports computeSourceHash — call it programmatically if preferred:
+      CURRENT=$(node -e "const t=require('$FORGE_ROOT/tools/build-context-pack.cjs'); try { console.log(t.computeSourceHash('$PROJECT_ROOT/$ENGINEERING/architecture')); } catch(e) { console.log('n/a'); }")
+      ```
+    - If `engineering/architecture/` does not exist, skip this check silently.
+    - If `.forge/cache/context-pack.json` does not exist, emit:
+      > △ Context pack missing — run `/forge:regenerate` to build it.
+      (The pack is injected by `meta-orchestrate` and `meta-fix-bug` to reduce per-phase architecture reads.)
+    - Otherwise read `source_hash` from `.forge/cache/context-pack.json` and compare:
+      ```sh
+      STORED=$(node -e "console.log(require('$PROJECT_ROOT/.forge/cache/context-pack.json').source_hash)")
+      ```
+      If `CURRENT != STORED` (and `CURRENT != 'n/a'`), emit:
+      > △ Context pack stale — architecture docs have changed since last build. Run `/forge:regenerate` or `/forge:collate` to rebuild.
+      Otherwise emit:
+      > 〇 Context pack fresh.
+14. Check plugin integrity:
+    First, verify the integrity verifier itself has not been tampered with:
+    ```sh
+    ACTUAL=$(node -e "const c=require('crypto'),f=require('fs'); console.log(c.createHash('sha256').update(f.readFileSync('$FORGE_ROOT/tools/verify-integrity.cjs')).digest('hex'))")
+    EXPECTED="3ec3c970dd3d7c3001f8f373bcc40556803eadd2fc2afafb14f1c232cba4cc3f"
+    ```
+    If `ACTUAL != EXPECTED`, emit:
+    > △ Integrity verifier itself appears modified — run `/forge:update` to restore. Skipping integrity check.
+    And skip the rest of this step.
+
+    If the verifier hash matches, run:
+    ```sh
+    node "$FORGE_ROOT/tools/verify-integrity.cjs" --forge-root "$FORGE_ROOT"
+    ```
+    Include the output line verbatim in the report (it already uses 〇/△/× format).
+    Note: local verification is tamper-evident, not tamper-proof. `/forge:update` is
+    the authoritative restore path.
+
+15. Report all findings with actionable recommendations.
+    If `--path` was used, open the report with: `Health report for: $PROJECT_ROOT`
+16. Close the report with: `If you've found a bug in Forge itself, run /forge:report-bug`
+
+## Output
+
+A health report to stdout — no files modified.
+
+After the report's findings, close with a single status line that
+reflects the overall verdict (synthesized from check 12's findings):
+
+```sh
+# Pick one of three status emojis based on the worst finding observed:
+#   〇 = all checks pass         (green)
+#   △ = warnings, no errors      (caution)
+#   × = at least one failure     (alert)
+node "$FORGE_ROOT/tools/banners.cjs" --subtitle "{〇|△|×} Health check complete — {N} 〇, {W} △, {E} ×"
+```
+
+If exactly zero issues were found, also re-render the oracle badge as a
+"sealed" closing mark:
+
+```sh
+node "$FORGE_ROOT/tools/banners.cjs" --badge oracle
+```
+
+## Arguments
+
+$ARGUMENTS
+
+| Argument | Purpose |
+|----------|---------|
+| `--path <dir>` | Run health check against a different project directory instead of the current working directory. Accepts an absolute path or a path relative to the current directory. |
+
+## On error
+
+If any step above fails unexpectedly, describe what went wrong and ask:
+
+> "This looks like a Forge bug. Would you like to file a report to help improve it? Run `/forge:report-bug` — I'll pre-fill the report from this conversation."

package/dist/forge-payload/commands/init.md

@@ -0,0 +1,165 @@
+---
+name: init
+description: Use when the current project has no Forge SDLC instance and you need to bootstrap one from scratch
+---
+
+# /forge:init
+
+You are the Forge init orchestrator. Your job is to generate a complete, project-specific
+AI software development lifecycle for the codebase in the current working directory.
+
+## Locate the Forge plugin
+
+Set `$FORGE_ROOT` to the plugin root provided by Claude Code:
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+`$FORGE_ROOT` is the directory containing `meta/`, `init/`, `hooks/`, and `commands/`.
+
+## Execute
+
+### Resume Detection
+
+Before showing the pre-flight plan, check for an existing checkpoint:
+
+```sh
+cat .forge/init-progress.json 2>/dev/null
+```
+
+If the file exists and contains valid JSON, inspect it:
+
+- If `lastPhase > 4`, contains a `mode` field, contains a `phase-7-substep-map` key,
+  or is missing a `timestamp` field — treat as a stale checkpoint from a previous
+  run of the old 12-phase init. Delete the file:
+  ```sh
+  rm -f .forge/init-progress.json
+  ```
+  Then proceed to the **Pre-flight Plan** (new 4-phase flow, no mode prompt).
+
+- If the file contains valid JSON with `lastPhase` in range 1–4 and a `timestamp`
+  field, emit the resume banner:
+
+```
+〇 Previous init detected — last completed phase: {lastPhase} of 4
+
+Resume from Phase {nextPhase}? [Y] Start over [n]
+```
+
+Use the following mapping:
+
+| lastPhase | Resume from (nextPhase) |
+|-----------|-------------------------|
+| 1         | Phase 2                 |
+| 2         | Phase 3                 |
+| 3         | Phase 4                 |
+
+If the user chooses to resume: jump to the mapped resume phase.
+
+If the user chooses to start over: delete `.forge/init-progress.json`
+(`rm -f .forge/init-progress.json`) and proceed to the **Pre-flight Plan**.
+
+If the file does not exist, or contains invalid JSON, or contains an
+unrecognised `lastPhase` value outside 1–4: delete any corrupt file and
+proceed to the **Pre-flight Plan**.
+
+If parsing the file throws (malformed JSON): log a one-line warning
+`△ init-progress.json is malformed — deleting and starting fresh.`, delete
+the file, and proceed to the **Pre-flight Plan**.
+
+### Hero
+
+Render the Forge hero block once per session:
+
+```sh
+node "$FORGE_ROOT/tools/banners.cjs" forge
+node "$FORGE_ROOT/tools/banners.cjs" --subtitle "AI SDLC bootstrapper · forge:init v$(node -p "require('$FORGE_ROOT/.claude-plugin/plugin.json').version")"
+```
+
+The hero runs once. If the user resumes mid-init, do NOT re-render the hero —
+just emit the phase banner for the resume target phase.
+
+### Flag handling
+
+**Conflict check first:** if `$ARGUMENTS` contains BOTH `--fast` AND `--full`, halt
+immediately with:
+```
+× Conflicting flags: --fast and --full cannot be combined.
+```
+Do not write `.forge/init-progress.json`. Do not proceed.
+
+**Single flag present (`--fast` or `--full`):** accept with a one-line acknowledgement
+and continue to **Pre-flight Plan** — both flags run the identical new 4-phase flow:
+
+- `--fast` present → emit `〇 --fast accepted — running 4-phase base-pack init (fast and full are now equivalent)`
+- `--full` present → emit `〇 --full accepted — running 4-phase base-pack init`
+
+**No flags:** proceed directly to **Pre-flight Plan**. There is no interactive mode
+prompt — the 4-phase flow is the only flow.
+
+### Pre-flight Plan
+
+Before executing Phase 1, emit a summary block and wait for the user to confirm
+or specify a start phase.
+
+```
+## Forge Init — <project-name if discoverable, otherwise current directory name>
+
+4 phases will run in this session (~45 seconds non-interactive):
+
+  1   Collect      — 5 parallel discovery scans → config.json
+                     KB folder prompt (interactive)
+  2   Discover     — KB doc generation (LLM fan-out) + project-context.json
+  3   Materialize  — substitute-placeholders.cjs → fully functional workflows
+  4   Register     — versioning, manifest, cache, store entries, Tomoshibi
+
+Phase 1 is interactive (KB folder name prompt). Phases 2–4 are non-interactive
+and complete in under 45 seconds.
+
+Start from Phase 1? [Y] or specify phase (1–4): ___
+```
+
+If the user specifies a valid phase (1–4), jump there directly.
+Any other input (including 0, 5+, or non-numeric text) re-prompts with the same table.
+
+If a `$ARGUMENTS` phase number was combined with a flag (e.g. `--fast 3`),
+skip both the flag acknowledgement and the pre-flight table and go straight
+to the specified phase.
+
+Read `$FORGE_ROOT/init/sdlc-init.md` — that document is your complete orchestration.
+Follow it exactly. It defines 4 phases:
+
+1. **Collect** — 5 parallel discovery prompts, KB folder prompt, `config.json`
+2. **Discover** — KB doc fan-out + inline `project-context.json` construction
+3. **Materialize** — `substitute-placeholders.cjs` + `build-overlay.cjs` smoke test
+4. **Register** — tools, versioning, manifest, cache, store seed, Tomoshibi, `.gitignore` update (unconditional), CLAUDE.md KB-link offer
+
+The current working directory is the target project. All generated artifacts go into
+`.forge/`, the configured KB folder (default: `engineering/`), and `.claude/commands/`
+in the project.
+
+## Arguments
+
+$ARGUMENTS
+
+### Mode flags (backwards compatibility)
+
+`--fast` and `--full` are accepted for scripted and CI use. Both flags select the
+new 4-phase base-pack init — the distinction between fast and full mode is
+obsolete because base-pack template substitution is instant and always produces
+fully functional (non-stub) workflows.
+
+#### Conflicting flags
+
+`--fast` and `--full` together halt the run before any write:
+
+```
+× Conflicting flags: --fast and --full cannot be combined.
+```
+
+## On error
+
+If any step above fails unexpectedly, describe what went wrong and ask:
+
+> "This looks like a Forge bug. Would you like to file a report to help improve it? Run `/forge:report-bug` — I'll pre-fill the report from this conversation."