@entelligentsia/forgecli 0.6.6 → 0.7.7

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

@@ -0,0 +1,119 @@
+---
+name: materialize
+description: Use when you've run /forge:init --fast and want to fill in missing scaffolding — either for a specific workflow's closure or as a full warm-up. Fills missing or stubbed artifacts; does not change config mode. Unlike /forge:regenerate (which rebuilds regardless), materialize only fills what is missing or stubbed, leaving pristine user-modified files untouched.
+---
+
+# /forge:materialize
+
+Fills missing or stubbed Forge scaffolding without overwriting pristine files.
+This is the on-demand complement to `/forge:init --fast`.
+
+`materialize` is **mode-neutral** — it never writes `.forge/config.json`
+`mode`. Promotion from fast → full is a separate explicit decision owned
+by `/forge:config mode full`. After a `materialize --all`, it is normal
+for `mode` to remain `fast` even though every artifact is now present.
+
+## Locate the Forge plugin
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+Read `.forge/config.json`. If it does not exist, stop and tell the user to run
+`/forge:init` first.
+
+## Arguments
+
+$ARGUMENTS
+
+Parse the argument:
+
+```
+/forge:materialize                          # full warm-up — all stubs + missing
+/forge:materialize --all                    # same as no args
+/forge:materialize workflows plan_task      # just this workflow's closure
+/forge:materialize workflows:plan_task      # colon form
+```
+
+---
+
+## Full warm-up (`/forge:materialize` or `--all`)
+
+Open with the forge badge + status line:
+
+```sh
+node "$FORGE_ROOT/tools/banners.cjs" --badge forge
+```
+
+Emit: `〇 forge:materialize — full warm-up…`
+
+Then announce the fast-mode capability state — silent on full installs:
+
+```sh
+node "$FORGE_ROOT/tools/ensure-ready.cjs" --announce --all
+```
+
+`banners.cjs` strips ANSI in `NO_COLOR` / non-tty / `--plain` contexts.
+
+Follow `$FORGE_ROOT/init/generation/lazy-materialize.md` for each stub or missing
+workflow in `.forge/workflows/`. Work from a single collected list:
+
+1. Read `$FORGE_ROOT/schemas/structure-manifest.json` for the full workflow list.
+2. For each workflow id in `namespaces.workflows.files`:
+   - Check if `.forge/workflows/{id}.md` is a stub (starts with `<!-- FORGE FAST-MODE STUB`)
+     or is missing.
+   - Collect all stubs/missing into one list.
+3. Compute the union closure across all stubs/missing workflows.
+4. Fan-out materialisation following the lazy-materialize rulebook steps 5–10
+   for the union closure (one pass, not per-workflow).
+5. Rebuild the persona pack so `meta-orchestrate` and `meta-fix-bug` use
+   a fresh reference index (consumed when `FORGE_PROMPT_MODE=reference`):
+   ```sh
+   node "$FORGE_ROOT/tools/build-persona-pack.cjs" \
+     --out .forge/cache/persona-pack.json
+   ```
+   On exit 1, surface the stderr message (it includes the offending file
+   path) and continue — the pack is refreshable later via `/forge:regenerate`.
+6. Rebuild the architecture context pack:
+   ```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" \
+     --out-md .forge/cache/context-pack.md \
+     --out-json .forge/cache/context-pack.json
+   ```
+   On exit 1 (architecture directory not yet present), emit a warning and
+   continue — the pack can be built later via `/forge:regenerate`.
+7. Emit: `〇 forge:materialize complete — gaps filled (mode unchanged)`
+8. If `.forge/config.json` `mode` is still `"fast"`, append the promotion hint:
+   ```
+   〇 To declare the project fully generated: /forge:config mode full
+   ```
+
+---
+
+## Single-workflow (`/forge:materialize workflows <id>`)
+
+Open with the forge badge + status line:
+
+```sh
+node "$FORGE_ROOT/tools/banners.cjs" --badge forge
+```
+
+Emit: `〇 forge:materialize — materialising closure for {id}…`
+
+Follow `$FORGE_ROOT/init/generation/lazy-materialize.md` with `workflow_id={id}`.
+Pass the full argument (caller intent) so the rulebook can re-read and execute
+the real workflow after materialisation.
+
+Do NOT flip config mode for any materialize invocation. Mode is owned by
+`/forge:config`.
+
+---
+
+## On error
+
+If any generation step fails unexpectedly:
+
+> "This looks like a Forge bug. Would you like to file a report? Run
+> `/forge:report-bug` — I'll pre-fill the report from this conversation."

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

@@ -0,0 +1,160 @@
+---
+name: migrate
+description: Use after forge:init to migrate a pre-existing AI-SDLC store to Forge format — interviews you to define the project-specific mapping
+---
+
+# /forge:migrate
+
+Migrate an existing project store to Forge format. Requires `forge:init` to have been completed first.
+
+## Locate the Forge plugin
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+## Step 0 — Detect migration type
+
+Check whether a structural migration (v0.x prose-heavy → v0.40 base-pack
+format) is needed:
+
+- If the user passed `--structural` explicitly, OR
+- If `.forge/structure-versions.json` is absent (pre-T05 install detected):
+
+  → Load and run the structural migration workflow:
+    Read `"$FORGE_ROOT/meta/workflows/meta-migrate.md"` and follow it.
+  → Do NOT proceed to Step 1 of this command.
+
+If neither condition applies (post-T05 install and no `--structural` flag):
+continue to Step 1 (store schema migration).
+
+## Step 1 — Verify forge:init has run
+
+Check that `.forge/config.json` exists. If it does not, stop and tell the user:
+
+> "Forge has not been initialised in this project. Run `/forge:init` first, then come back to `/forge:migrate`."
+
+Read `.forge/config.json` to get `paths.store` (default: `.forge/store`).
+
+## Step 2 — Scan for non-Forge values
+
+Read every JSON file under `{paths.store}/sprints/`, `{paths.store}/tasks/`, and `{paths.store}/bugs/`.
+
+Collect the distinct values present in each `status` field and `severity` field (bugs only), grouped by record type. Cross-reference against the known Forge enums:
+
+**Sprint status:** `planning`, `active`, `completed`, `retrospective-done`, `blocked`, `partially-completed`, `abandoned`
+
+**Task status:** `draft`, `planned`, `plan-approved`, `implementing`, `implemented`, `review-approved`, `approved`, `committed`, `plan-revision-required`, `code-revision-required`, `blocked`, `escalated`, `abandoned`
+
+**Bug status:** `reported`, `triaged`, `in-progress`, `fixed`, `verified`
+
+**Bug severity:** `critical`, `major`, `minor`
+
+Report only the values that are **not** already valid Forge enums. If all values are already valid, tell the user:
+
+> "Store is already fully Forge-compatible — no migration needed. Run `node \"$FORGE_ROOT/tools/validate-store.cjs\"` to confirm."
+
+Then exit.
+
+## Step 3 — Interview the user
+
+Present the unrecognised values grouped by record type. For each value, ask the user to choose the Forge equivalent (or mark it as custom/skip):
+
+```
+Found values not in Forge format. Please map each one:
+
+Sprint status:
+  "✅ Complete"    → ? (Forge options: planning / active / completed / retrospective-done / blocked / partially-completed / abandoned)
+  "🔵 In Progress" → ?
+
+Task status:
+  "✅ Complete"    → ?
+  "📋 Prompt Ready" → ?
+  ...
+
+Bug severity:
+  "Major" → ? (Forge options: critical / major / minor)
+
+For each value above, enter the Forge equivalent. Type "skip" to leave that value unchanged (it will remain invalid and fail validate-store).
+```
+
+Wait for the user to provide the full mapping before proceeding.
+
+## Step 4 — Preview changes
+
+Count how many records will be affected per type. Show a preview table:
+
+```
+Migration preview:
+
+  Sprints:  N records — M values will change
+  Tasks:    N records — M values will change
+  Bugs:     N records — M values will change
+
+  Example changes:
+    sprints/S01.json  status: "✅ Complete"    → "completed"
+    tasks/WI-T001.json status: "✅ Complete"   → "committed"
+    bugs/WI-BUG-01.json severity: "Major"     → "major"
+
+Apply? [Y/n]
+```
+
+If the user declines, exit without changes.
+
+## Step 5 — Apply migration
+
+For each affected record, apply the migration via the store custodian:
+
+```sh
+export FORGE_ROOT
+node "$FORGE_ROOT/tools/store-cli.cjs" write <entity> '{updated-json}'
+```
+
+where `<entity>` is `sprint`, `task`, or `bug` as appropriate, and
+`'{updated-json}'` is the full record with the mapped field values applied.
+Construct the JSON by reading the current record (using the Read tool or
+`/forge:store read <entity> <id>`), applying only the agreed mapping, and
+passing the complete updated record to the custodian.
+
+**Error handling:** If the custodian exits with code 1, read stderr for the
+validation error, fix the data, and retry (max 2 retries). If the command still
+fails after retries, report the validation error to the user and stop. **Never
+fall back to writing store files directly.**
+
+Do not modify any field that was not part of the agreed mapping. Do not add or remove fields.
+
+## Step 6 — Verify
+
+Run:
+
+```sh
+export FORGE_ROOT
+node "$FORGE_ROOT/tools/validate-store.cjs" --dry-run
+```
+
+Report the result. If errors remain (e.g. values the user chose to skip), list them clearly so the user knows what still needs attention.
+
+## Step 7 — Close
+
+Report a summary:
+
+```
+Migration complete:
+  N sprint(s) updated
+  N task(s) updated
+  N bug(s) updated
+
+Run /forge:health to check overall knowledge base status.
+```
+
+## Arguments
+
+$ARGUMENTS
+
+If the user passes `--dry-run`, run Steps 1–4 only (no writes).
+
+## 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/quiz-agent.md

@@ -0,0 +1,38 @@
+---
+name: quiz-agent
+description: Verify an agent has loaded and understood the project knowledge base — run a short factual quiz before starting high-stakes tasks
+---
+
+# /forge:quiz-agent
+
+Verify that the active agent has correctly read and understood this project's
+knowledge base before beginning a high-stakes task (schema changes, migrations,
+release engineering, significant refactors).
+
+## Locate plugin root
+
+```
+FORGE_ROOT: !`echo "${CLAUDE_PLUGIN_ROOT}"`
+```
+
+## Arguments
+
+$ARGUMENTS
+
+## How to Run
+
+Read `.forge/workflows/quiz_agent.md` and follow it exactly.
+
+Pass `$ARGUMENTS` to the workflow so the agent can include task context in its
+responses if provided.
+
+## On error
+
+If `.forge/workflows/quiz_agent.md` does not exist, tell the user:
+
+> △ The quiz_agent workflow is missing. Run `/forge:regenerate workflows` to
+> regenerate it, then retry.
+
+If any other step 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."