@entelligentsia/forgecli 1.0.21 → 1.0.36

package/dist/forge-payload/init/generation/generate-knowledge-base.md

@@ -0,0 +1,56 @@
+# Generation: Knowledge Base
+
+## Purpose
+
+Generate the project's architecture documentation, business domain documentation,
+and initial stack review checklist from the discovery context.
+
+## Inputs
+
+- Discovery context (from Phase 1)
+- `$FORGE_ROOT/meta/personas/` (to understand what agents need to know)
+
+## Setup
+
+Read the configured KB path:
+
+```sh
+KB_PATH=$(node -e "try{console.log(require('./.forge/config.json').paths.engineering)}catch{console.log('engineering')}")
+```
+
+## Outputs
+
+```
+{KB_PATH}/
+  architecture/
+    INDEX.md
+    stack.md
+    processes.md
+    database.md
+    routing.md
+    deployment.md
+  business-domain/
+    INDEX.md
+    entity-model.md
+  stack-checklist.md
+  MASTER_INDEX.md          (empty scaffold)
+  sprints/                 (empty, with .gitkeep)
+  bugs/                    (empty, with .gitkeep)
+  tools/                   (empty, created for Phase 8)
+
+.forge/
+  store/
+    sprints/               (empty, with .gitkeep)
+    tasks/                 (empty, with .gitkeep)
+    bugs/                  (empty, with .gitkeep)
+    events/                (empty, with .gitkeep)
+```
+
+## Instructions
+
+1. For each architecture sub-doc, synthesise from the discovery context
+2. Include confidence header: `<!-- AUTO-GENERATED by /forge:init — confidence: N% -->`
+3. Mark uncertain lines with `[?]`
+4. The stack-checklist should have 5-10 items based on auth/framework detection
+5. entity-model.md should list all discovered entities with fields and relationships
+6. INDEX.md files should link to all sub-docs with one-line descriptions

package/dist/forge-payload/init/generation/generate-persona.md

@@ -0,0 +1,73 @@
+# Persona Generation — Per-Subagent Instructions
+
+You are generating **ONE** persona file. You have been given two inputs:
+
+1. A **project brief** (`.forge/init-context.md`) — authoritative for all names,
+   paths, command values, and installed-skill wiring
+2. A **meta-persona source** — the role definition and Generation Instructions
+
+Your job is to produce exactly one file and return a one-line status.
+
+---
+
+## Inputs
+
+Read these two sources before writing anything:
+
+- `$FORGE_ROOT/meta/personas/{meta}` — the meta-persona for your assigned role
+- `.forge/init-context.md` — the project brief (passed inline in your prompt)
+
+---
+
+## Rules
+
+1. **Write EXACTLY ONE file:** `.forge/personas/{role}.md`
+
+2. **Opening line** — the first non-blank line must be the persona's symbol
+   (emoji from the meta-persona's `## Symbol` section) followed by a brief
+   first-person announcement in this exact format:
+   ```
+   {symbol} **{Project} {Role Name}** — {quiet first-person voice, present-tense}
+   ```
+   Do not use `symbol:` YAML frontmatter. The symbol must appear as the first
+   non-blank line of the file.
+
+3. **Project substitution** — replace every `{Project}` placeholder with the
+   project name from the brief's `## Commands` / `## Paths` header line.
+   All entity names, architecture doc names, persona names, and command values
+   MUST come from the brief. Do not invent values.
+
+4. **Stack wiring** — substitute actual commands from the brief's `## Commands`
+   section wherever the meta-persona references test/build/lint/syntax-check.
+
+5. **Skill invocation wiring** — read `## Installed Skill Wiring` from the
+   brief. For each skill that maps to this persona's role, add an explicit
+   YOU MUST directive. Follow the wiring pattern in the meta-persona's
+   Generation Instructions exactly.
+
+6. **Follow Generation Instructions** — each meta-persona has a
+   `## Generation Instructions` section (or equivalent). Follow it fully.
+   Do not add sections, steps, or notes beyond what it prescribes.
+
+---
+
+## Self-check (mandatory last step)
+
+After writing the file, verify before returning:
+
+1. Read back `.forge/personas/{role}.md`
+2. Confirm the **first non-blank line** starts with the persona's symbol emoji
+3. Confirm **no unsubstituted `{Project}` placeholders** remain
+4. Confirm **no literal `{TEST_COMMAND}`, `{BUILD_COMMAND}`, `{SYNTAX_CHECK}`,
+   or `{LINT_COMMAND}`** remain
+5. Record in the manifest:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record ".forge/personas/{role}.md"
+   ```
+   (If generation-manifest.cjs is not yet installed, skip silently.)
+
+6. Return **exactly one line**:
+   - `done: <first 80 chars of the written file>` — on success
+   - `FAILED: <reason>` — if any step above failed or the file could not be written
+
+Do not output anything else after the status line.

package/dist/forge-payload/init/generation/generate-personas.md

@@ -0,0 +1,54 @@
+# Generation: Personas
+
+## Purpose
+
+Generate project-specific agent persona context from meta-personas,
+the discovery context, and the generated knowledge base.
+
+## Inputs
+
+- `$FORGE_ROOT/meta/personas/meta-*.md` (6 meta-personas)
+- Discovery context (from Phase 1)
+- Generated knowledge base (from Phase 2)
+
+## Outputs
+
+Personas are written as standalone files in `.forge/personas/`.
+Each file is named after the persona's role (e.g., `.forge/personas/supervisor.md`).
+
+These files are consumed by Phase 5 (Generate Atomic Workflows) to establish the agent's identity, knowledge, and constraints.
+
+## Instructions
+
+For each meta-persona, read its Generation Instructions section and
+produce a project-specific version that incorporates:
+- The project's actual stack, test commands, build commands
+- The project's actual entity names and business rules
+- The project's actual auth patterns and conventions
+- The project's actual directory structure and paths
+
+**Persona block format** — each persona file opens with a single line using the
+persona's symbol (from its `## Symbol` section) and a quiet first-person announcement.
+Follow the `Persona block format` template in each meta-persona's Generation Instructions,
+substituting `{Project}` with the project's name. The line should be brief, present-tense,
+and speak to what the persona is about to do — not a role description, but a voice.
+
+## Skill Invocation Wiring
+
+Read `.forge/config.json` for `installedSkills`. For each installed skill
+that is relevant to a persona's domain, add an explicit invocation instruction
+to that persona's context.
+
+Read `$FORGE_ROOT/meta/skill-recommendations.md` for the persona integration
+pattern. Apply it: the instruction must be a YOU MUST directive placed at
+the relevant persona's context.
+
+Example — if `vue-best-practices` is installed and the persona is Supervisor:
+
+> "When reviewing Vue components, YOU MUST invoke the `vue-best-practices`
+> skill before applying the stack checklist. That skill provides universal
+> Vue technique depth; the checklist provides project conventions. Both are required."
+
+This wiring is what distinguishes Forge-generated personas from plain skill
+invocation: the persona carries project-specific knowledge *and* knows exactly
+when to reach for a universal technique skill. Neither layer alone is sufficient.

package/dist/forge-payload/init/generation/generate-skill.md

@@ -0,0 +1,66 @@
+# Skill Generation — Per-Subagent Instructions
+
+You are generating **ONE** skill file. You have been given two inputs:
+
+1. A **project brief** (`.forge/init-context.md`) — authoritative for all names,
+   paths, command values, and installed-skill wiring
+2. A **meta-skill source** — the role's universal capability set and Generation Instructions
+
+Your job is to produce exactly one file and return a one-line status.
+
+---
+
+## Inputs
+
+Read these two sources before writing anything:
+
+- `$FORGE_ROOT/meta/skills/{meta}` — the meta-skill for your assigned role
+- `.forge/init-context.md` — the project brief (passed inline in your prompt)
+
+---
+
+## Rules
+
+1. **Write EXACTLY ONE file:** `.forge/skills/{role}-skills.md`
+
+2. **Project interpolation** — replace every generic placeholder with the
+   project's actual tools, libraries, paths, and conventions from the brief.
+   All entity names, stack names, and command values MUST come from the brief.
+   Do not invent values.
+
+3. **Stack specificity** — replace abstract references (e.g. "your test runner",
+   "your ORM") with the actual tools discovered for this project. Substitute
+   actual command values from the brief's `## Commands` section.
+
+4. **Installed skill integration** — read `## Installed Skill Wiring` from the
+   brief. For each skill that maps to this role, add an explicit reference
+   explaining how the persona should combine the marketplace skill with this
+   project-specific skill set.
+
+5. **Follow Generation Instructions** — each meta-skill has a
+   `## Generation Instructions` section. Follow it fully. Do not add sections,
+   steps, or notes beyond what it prescribes.
+
+6. **No free-form additions** — produce only the sections the meta-skill defines.
+
+---
+
+## Self-check (mandatory last step)
+
+After writing the file, verify before returning:
+
+1. Read back `.forge/skills/{role}-skills.md`
+2. Confirm **no unsubstituted placeholders** remain
+3. Confirm **no abstract project references** remain (e.g. "your framework",
+   "your ORM" — these must be replaced with the actual project values)
+4. Record in the manifest:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record ".forge/skills/{role}-skills.md"
+   ```
+   (If generation-manifest.cjs is not yet installed, skip silently.)
+
+5. Return **exactly one line**:
+   - `done: <first 80 chars of the written file>` — on success
+   - `FAILED: <reason>` — if any step above failed or the file could not be written
+
+Do not output anything else after the status line.

package/dist/forge-payload/init/generation/generate-skills.md

@@ -0,0 +1,36 @@
+# Generation: Skills
+
+## Purpose
+
+Generate project-specific skill sets for each persona, mapping universal 
+techniques to project-specific tools and contexts.
+
+## Inputs
+
+- `$FORGE_ROOT/meta/skills/meta-*.md` (Meta-skill templates)
+- Discovery context (from Phase 1)
+- Generated knowledge base (from Phase 2)
+- `.forge/config.json` (specifically `installedSkills`)
+
+## Outputs
+
+Skill sets are written as standalone files in `.forge/skills/`.
+Each file uses the `-skills.md` suffix matching the persona role (e.g., `.forge/skills/supervisor-skills.md`).
+
+## Instructions
+
+For each persona role defined in the project:
+1. Identify the relevant meta-skills from `$FORGE_ROOT/meta/skills/`.
+2. For each skill, produce a project-interpolated version that:
+   - Replaces generic placeholders with actual project tools, libraries, and paths.
+   - Incorporates specific constraints discovered during Phase 1.
+   - Maps universal techniques to the project's actual implementation patterns.
+3. Integrate `installedSkills` from `.forge/config.json`:
+   - If a marketplace skill is installed that enhances a specific technique, 
+     explicitly reference it in the skill set.
+   - Ensure the skill set explains *how* the persona should combine the 
+     universal marketplace skill with the project-specific skill set.
+
+**Skill set format**:
+Each file should be structured as a cohesive set of capabilities, 
+techniques, and checklists tailored for that specific role within the project.

package/dist/forge-payload/init/generation/generate-template.md

@@ -0,0 +1,60 @@
+# Template Generation — Per-Subagent Instructions
+
+You are generating **ONE** template file. You have been given two inputs:
+
+1. A **project brief** (`.forge/init-context.md`) — authoritative for all names,
+   paths, command values, and entity names
+2. A **meta-template source** — the document structure and Generation Instructions
+
+Your job is to produce exactly one file and return a one-line status.
+
+---
+
+## Inputs
+
+Read these two sources before writing anything:
+
+- `$FORGE_ROOT/meta/templates/{meta}` — the meta-template for your assigned document
+- `.forge/init-context.md` — the project brief (passed inline in your prompt)
+
+---
+
+## Rules
+
+1. **Write EXACTLY ONE file:** `.forge/templates/{filename}.md`
+
+2. **Stack-specific sections** — add framework-specific subsections based on the
+   stack information in the brief. Use the detected languages and frameworks to
+   decide which optional sections to include.
+
+3. **Project substitution** — replace all `{Project}`, `{PREFIX}`, entity name
+   placeholders, and ID format examples with actual values from the brief.
+   All entity names and command values MUST come from the brief. Do not invent.
+
+4. **Test output formats** — reference the project's actual test runner output
+   format in any template sections that involve test results.
+
+5. **Follow Generation Instructions** — each meta-template has a
+   `## Generation Instructions` section. Follow it fully. Do not add sections
+   or notes beyond what it prescribes.
+
+---
+
+## Self-check (mandatory last step)
+
+After writing the file, verify before returning:
+
+1. Read back `.forge/templates/{filename}.md`
+2. Confirm **no unsubstituted placeholders** remain (no literal `{Project}`,
+   `{PREFIX}`, `{TEST_COMMAND}`, etc.)
+3. Record in the manifest:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record ".forge/templates/{filename}.md"
+   ```
+   (If generation-manifest.cjs is not yet installed, skip silently.)
+
+4. Return **exactly one line**:
+   - `done: <first 80 chars of the written file>` — on success
+   - `FAILED: <reason>` — if any step above failed or the file could not be written
+
+Do not output anything else after the status line.

package/dist/forge-payload/init/generation/generate-templates.md

@@ -0,0 +1,39 @@
+# Generation: Templates
+
+## Purpose
+
+Generate project-specific document templates from meta-templates,
+adding stack-specific sections.
+
+## Inputs
+
+- `$FORGE_ROOT/meta/templates/meta-*.md` (8 meta-templates)
+- Discovery context (from Phase 1)
+- Generated knowledge base (from Phase 2)
+
+## Outputs
+
+`.forge/templates/` with project-specific templates:
+- `TASK_PROMPT_TEMPLATE.md`
+- `PLAN_TEMPLATE.md`
+- `PROGRESS_TEMPLATE.md`
+- `CODE_REVIEW_TEMPLATE.md`
+- `PLAN_REVIEW_TEMPLATE.md`
+- `SPRINT_REQUIREMENTS_TEMPLATE.md`
+- `SPRINT_MANIFEST_TEMPLATE.md`
+- `RETROSPECTIVE_TEMPLATE.md`
+
+## Instructions
+
+For each meta-template:
+1. Read its sections and Generation Instructions
+2. Add framework-specific subsections based on the detected stack
+3. Reference the project's actual entity names and test output formats
+4. Use the project's ID format in template headers
+
+After writing each template file, record it in the generation manifest:
+```sh
+node {paths.tools}/generation-manifest.cjs record {paths.templates}/{filename}.md
+```
+
+If `generation-manifest.cjs` is not yet installed, skip silently.

package/dist/forge-payload/init/generation/generate-tools.md

@@ -0,0 +1,133 @@
+# Generation: Tools
+
+## Purpose
+
+Vendor the plugin tools closure and validation schemas into the project so
+generated workflows can invoke tools via `node .forge/tools/<tool>.cjs` from
+the project root without resolving `$FORGE_ROOT` at runtime.
+
+Store validation schemas are loaded at runtime from `.forge/schemas/`
+(project-installed), `forge/schemas/` (in-tree fallback), or
+`$FORGE_ROOT/schemas/` (plugin-installed fallback). During init, schemas
+are copied to `.forge/schemas/` so that validation works without relying
+on fallback paths.
+
+## Inputs
+
+- `.forge/config.json` — target paths
+
+## Outputs
+
+- `.forge/tools/` — vendored plugin tools closure
+- `.forge/tools/.forge-tools-version` — version marker for `/forge:health` staleness check
+- `.forge/schemas/` — JSON Schema copies from the installed plugin
+
+## Instructions
+
+Read `.forge/config.json` for:
+- `paths.store` (default: `.forge/store`)
+
+### Step 1 — Copy validation schemas
+
+Copy all JSON Schema files from the installed plugin to the project:
+
+```sh
+mkdir -p .forge/schemas
+cp "$FORGE_ROOT/schemas/"*.schema.json .forge/schemas/
+```
+
+This ensures `store-cli.cjs` and `validate-store.cjs` can validate records
+using the full schema (not the minimal fallback) even when the project is
+not inside the Forge source tree.
+
+### Step 2 — Vendor plugin tools
+
+Copy the plugin tools closure into the project's `.forge/tools/` so that
+generated artifacts can invoke `node .forge/tools/<tool>.cjs` from the
+project root without resolving `$FORGE_ROOT`:
+
+Copy BOTH `.cjs` and `.js` files. Some tools require `.js` helpers at load
+time — e.g. `store-cli.cjs` does a top-level `require('./lib/validate.js')`
+and `collate.cjs` requires `./lib/result.js` — so a `.cjs`-only copy leaves
+`store-cli.cjs` dead-on-arrival and breaks KB collation. `-maxdepth 1`
+excludes the `__tests__/` subtree without copying any `*.test.*` files.
+
+```sh
+mkdir -p .forge/tools/lib
+
+# Copy top-level tool files (.cjs and .js — e.g. list-skills.js)
+find "$FORGE_ROOT/tools" -maxdepth 1 -type f \( -name '*.cjs' -o -name '*.js' \) \
+  -exec cp {} .forge/tools/ \;
+
+# Copy lib/ helper files (.cjs and .js — e.g. result.js, validate.js)
+find "$FORGE_ROOT/tools/lib" -maxdepth 1 -type f \( -name '*.cjs' -o -name '*.js' \) \
+  -exec cp {} .forge/tools/lib/ \;
+```
+
+After copying, record each vendored file in the generation manifest so that
+`/forge:health` can detect modifications or stale copies:
+
+```sh
+for f in $(find .forge/tools .forge/tools/lib -maxdepth 1 -type f \( -name '*.cjs' -o -name '*.js' \)); do
+  node "$FORGE_ROOT/tools/generation-manifest.cjs" record "$f"
+done
+```
+
+### Step 2b — Write version marker
+
+After the tool copy loop, write the version marker so `/forge:health` can
+detect whether the vendored tools are stale relative to the active plugin:
+
+```sh
+ACTIVE_VERSION=$(node -e "console.log(require('$FORGE_ROOT/.claude-plugin/plugin.json').version)")
+node -e "
+const fs = require('fs');
+fs.writeFileSync('.forge/tools/.forge-tools-version', JSON.stringify({ version: '${ACTIVE_VERSION}' }) + '\n');
+"
+```
+
+### Step 3 — Verify
+
+```sh
+node "$FORGE_ROOT/tools/validate-store.cjs" --dry-run
+```
+
+If it exits non-zero, report the error. Do not proceed to Phase 9 until this passes.
+
+### Step 4 — Register the Forge root
+
+Write the project-relative Forge root into config. In the CLI-first vendored
+world the `.forge/` directory IS the Forge root (tools, schemas, hooks, init,
+meta are all vendored there) — NEVER write an absolute path (plugin cache,
+npm global payload, …): absolute paths break on version upgrades, nvm/node
+switches, and machine moves.
+
+```sh
+node .forge/tools/manage-config.cjs set paths.forgeRoot '".forge"'
+```
+
+### Step 5 — Record hashes
+
+Record all generated artifacts in the generation manifest so health checks
+can detect later modifications:
+
+```sh
+for f in .forge/schemas/*.schema.json; do
+  node "$FORGE_ROOT/tools/generation-manifest.cjs" record "$f"
+done
+node "$FORGE_ROOT/tools/generation-manifest.cjs" record .forge/config.json
+```
+
+## Notes
+
+- `/forge:update` automatically refreshes schemas and re-vendors tools as part
+  of its normal flow — run it after upgrades to pick up any changed tools or
+  schema updates from the new version.
+- Generated workflow files invoke tools using the vendored project-relative path:
+  ```
+  node .forge/tools/<tool>.cjs
+  ```
+  This works from the project root without resolving `$FORGE_ROOT` at runtime.
+- `paths.forgeRef` in config records the plugin version the project was generated
+  against. `forge-preflight.cjs` uses it to resolve the plugin root via cache
+  lookup when runtime telemetry requires the original plugin path.

package/dist/forge-payload/init/generation/generate-workflows.md

@@ -0,0 +1,78 @@
+# Workflow Generation — Per-Subagent Instructions
+
+You are generating **ONE** workflow file. You have been given three inputs:
+
+1. A **project brief** (`.forge/init-context.md`) — authoritative for all names,
+   paths, and placeholder values
+2. A **meta-workflow source** — your generation algorithm and Generation Instructions
+3. A **persona file** (already generated) — embed verbatim as the opening section
+
+Your job is to produce exactly one file and return a one-line status.
+
+---
+
+## Inputs
+
+Read these three sources before writing anything:
+
+- `.forge/init-context.md` — the project brief (passed inline in your prompt)
+- `$FORGE_ROOT/meta/workflows/{meta}` — the meta-workflow for your assigned workflow
+- `.forge/personas/{persona}.md` — the persona file for your assigned role
+
+---
+
+## Rules
+
+1. **Write EXACTLY ONE file:** `.forge/workflows/{id}.md`
+
+2. **Opening section** — the generated file must begin with:
+   a. The meta-workflow's YAML frontmatter block (`---` … `---`) verbatim,
+      if present. This carries `requirements:` fields used for runtime model
+      selection and must be preserved exactly.
+   b. Immediately after the closing `---`, embed the persona file content
+      verbatim as the first section. Do not paraphrase or summarise.
+
+3. **Placeholder substitution** — all `{SYNTAX_CHECK}`, `{TEST_COMMAND}`,
+   `{BUILD_COMMAND}`, `{LINT_COMMAND}` values come from the brief's
+   `## Commands` section. Do not invent values.
+
+4. **Name vocabulary** — all persona names, template names, architecture doc
+   names, and entity names MUST appear in the brief. Do not invent or rename
+   anything not listed there.
+
+5. **Required steps** — follow the meta-workflow's Generation Instructions.
+   Include the Knowledge Writeback step and the Event Emission step as defined
+   in the meta-workflow (unless the meta explicitly omits them, e.g. quiz_agent).
+
+6. **Enforcement quality** — for review workflows, include:
+   - A Rationalization Table of common agent excuses and factual rebuttals
+   - "YOU MUST" / "No exceptions" gate language at critical checks
+   - An announcement pattern: the agent declares intent at workflow start
+
+7. **No free-form additions** — do not add sections, steps, or notes beyond
+   what the meta-workflow and project brief prescribe.
+
+---
+
+## Self-check (mandatory last step)
+
+After writing the file, verify before returning:
+
+1. Read back `.forge/workflows/{id}.md`
+2. Confirm the persona symbol appears as the **first non-blank line after the
+   closing `---`** of the frontmatter block (or as the absolute first non-blank
+   line if the meta-workflow had no frontmatter). The symbol is listed in the
+   brief's `## Personas` section for this workflow's role.
+3. Confirm **no unsubstituted placeholders** remain (no literal `{TEST_COMMAND}`,
+   `{BUILD_COMMAND}`, `{SYNTAX_CHECK}`, or `{LINT_COMMAND}` in the file)
+4. Record in the manifest:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record ".forge/workflows/{id}.md"
+   ```
+   (If generation-manifest.cjs is not yet installed, skip silently.)
+
+5. Return **exactly one line**:
+   - `done: <first 80 chars of the written file>` — on success
+   - `FAILED: <reason>` — if any step above failed or the file could not be written
+
+Do not output anything else after the status line.

package/dist/forge-payload/init/phases/phase-1-collect.md

@@ -9,6 +9,10 @@ parent directory — the folder containing `meta/` and `init/`).
 
 ## Pre-flight — Knowledge Base Folder
 
+> **Orchestrator note:** If your orchestrator (e.g. the `wfl:init` driver or the CLI-first
+> wrapper) has already supplied a `kbFolder` value, use it directly — skip this prompt.
+> This interactive block applies only to unmediated orchestrator-free execution.
+
 Before Phase 1 begins, ask the user where to create the knowledge base folder:
 
 ```
@@ -74,13 +78,13 @@ Using your discovery findings, write `.forge/config.json` with this structure:
     "engineering": "engineering",
     "store": ".forge/store",
     "workflows": ".forge/workflows",
-    "commands": ".claude/commands/<prefix-lowercased>",
+    "commands": ".claude/commands/forge",
     "templates": ".forge/templates"
   }
 }
 ```
 
-`<prefix-lowercased>` = the `project.prefix` value you chose, lowercased. For example, if prefix is `HELLO`, write `".claude/commands/hello"`.
+`paths.commands` is ALWAYS `".claude/commands/forge"` — the command namespace is fixed (CLI-first redesign); it does NOT derive from the project prefix.
 
 Write using:
 ```sh
@@ -103,6 +107,10 @@ If any key is missing or empty, fix it now before proceeding.
 
 ### Step 5 — Marketplace Skills
 
+> **Orchestrator note:** If your orchestrator handles the skills install offer post-workflow
+> (e.g. the `init.md` wrapper does this after `wfl:init` returns), skip this step. Return
+> `{ matches, alreadyInstalled }` from the config-writer agent instead.
+
 Read `$FORGE_ROOT/meta/skill-recommendations.md` for the full mapping.
 
 Using the stack discovered above, look up matching skills from the recommendation

package/dist/forge-payload/init/phases/phase-3-materialize.md

@@ -63,7 +63,7 @@ node "$FORGE_ROOT/tools/substitute-placeholders.cjs" \
 ```
 
 Output directories (managed by the tool's `SUBDIR_OUTPUT_MAP`):
-- `base-pack/commands/`     → `.claude/commands/<prefix-lowercased>/`
+- `base-pack/commands/`     → `.claude/commands/forge/`  (fixed namespace — CLI-first redesign)
 - `base-pack/personas/`     → `.forge/personas/`
 - `base-pack/skills/`       → `.forge/skills/`
 - `base-pack/workflows/`    → `.forge/workflows/`

package/dist/forge-payload/init/phases/phase-4-register.md

@@ -102,6 +102,10 @@ console.log('ノ update-check-cache.json written');
 
 ### Step 11 — Tomoshibi (refresh-kb-links)
 
+> **Orchestrator note:** This step is orchestrator-owned. When running under `wfl:init`, the
+> register agent returns `pendingActions: ["refresh-kb-links"]` and the command wrapper
+> invokes the Skill. Do NOT execute this step if your orchestrator owns it.
+
 Use the Skill tool:
 ```
 skill: "forge:refresh-kb-links"
@@ -134,6 +138,10 @@ Fallback if unavailable:
 
 ### Step 13 — Agent instruction file linking
 
+> **Orchestrator note:** If your orchestrator pre-answered the CLAUDE.md creation prompt
+> (via `args.createClaudeMd`), use that value directly — skip the interactive prompt.
+> Execute the file creation only if `createClaudeMd === true`.
+
 Check whether any agent instruction file exists at the project root:
 ```sh
 ls CLAUDE.md AGENTS.md CLAUDE.local.md .cursorrules 2>/dev/null