@entelligentsia/forgecli 1.0.25 → 1.0.36

package/dist/forge-payload/init/discovery/discover-processes.md

@@ -0,0 +1,31 @@
+# Discovery: Processes
+
+## Purpose
+
+Detect the project's service topology, build tools, and deployment configuration.
+
+## Scan Targets
+
+| File | What It Reveals |
+|------|----------------|
+| `docker-compose.yml` | Service topology, dependencies, ports |
+| `Procfile` | Process types (web, worker, etc.) |
+| `ecosystem.config.js` | PM2 process management |
+| `systemd/*.service` | System service definitions |
+| `.github/workflows/*.yml` | CI/CD pipeline |
+| `.gitlab-ci.yml` | CI/CD pipeline |
+| `Jenkinsfile` | CI/CD pipeline |
+| `vercel.json` / `netlify.toml` | Deployment platform |
+
+## Tools
+
+Use Glob to find these files, Read to parse them.
+
+## Output
+
+Structured report:
+- Services and their roles (web, worker, database, cache, etc.)
+- Build command(s)
+- Deploy command(s) or platform
+- CI/CD pipeline structure
+- Environment variables referenced (names only, not values)

package/dist/forge-payload/init/discovery/discover-routing.md

@@ -0,0 +1,31 @@
+# Discovery: Routing
+
+## Purpose
+
+Detect the project's API surface, authentication strategy, and middleware.
+
+## Scan Targets
+
+| Pattern | What It Reveals |
+|---------|----------------|
+| Django: `urls.py`, `views.py` | URL patterns, view functions/classes |
+| Express: `router.get/post/...` | Route definitions |
+| Rails: `routes.rb` | Route definitions |
+| FastAPI: `@app.get/post` | Endpoint decorators |
+| Go: `http.HandleFunc` / mux | Route handlers |
+| Auth decorators/middleware | `@login_required`, `authenticate`, `IsAuthenticated` |
+| API docs: `openapi.yaml` / `swagger.json` | API specification |
+
+## Tools
+
+Use Grep to find route definitions and auth patterns, Read to parse them.
+
+## Output
+
+Structured report:
+- Route count (approximate)
+- Auth strategy (decorator-based, middleware, JWT, session, etc.)
+- Public vs protected route ratio
+- URL namespace structure
+- API versioning (if any)
+- Middleware chain

package/dist/forge-payload/init/discovery/discover-stack.md

@@ -0,0 +1,33 @@
+# Discovery: Stack
+
+## Purpose
+
+Detect the project's programming languages, frameworks, versions, and runtime.
+
+## Scan Targets
+
+| File | What It Reveals |
+|------|----------------|
+| `package.json` | Node.js, npm dependencies, scripts |
+| `requirements.txt` / `Pipfile` / `pyproject.toml` | Python, pip dependencies |
+| `go.mod` | Go, module dependencies |
+| `Cargo.toml` | Rust, crate dependencies |
+| `Gemfile` | Ruby, gem dependencies |
+| `Dockerfile` | Runtime, base image, build steps |
+| `Makefile` | Build commands, task aliases |
+| `*.sln` / `*.csproj` | .NET, C# |
+
+## Tools
+
+Use Glob to find these files, Read to parse them.
+
+## Output
+
+Structured report:
+- Primary language(s)
+- Framework(s) with versions
+- Frontend framework (if any)
+- Database (if detectable from dependencies)
+- Task queue (if any)
+- Containerisation (if any)
+- Runtime version constraints

package/dist/forge-payload/init/discovery/discover-testing.md

@@ -0,0 +1,34 @@
+# Discovery: Testing
+
+## Purpose
+
+Detect the project's test framework, test commands, build commands,
+and lint configuration.
+
+## Scan Targets
+
+| Pattern | What It Reveals |
+|---------|----------------|
+| `test/` / `tests/` / `__tests__/` / `*_test.go` | Test directory structure |
+| `jest.config.*` / `vitest.config.*` | JS test framework config |
+| `pytest.ini` / `setup.cfg` / `pyproject.toml [tool.pytest]` | Python test config |
+| `package.json scripts.test` | Test command |
+| `.eslintrc*` / `ruff.toml` / `.golangci.yml` | Lint configuration |
+| `.github/workflows/*.yml` | CI test/build/lint commands |
+| `coverage/` / `.coveragerc` / `lcov.info` | Coverage configuration |
+
+## Tools
+
+Use Glob to find config files, Read to parse them. Use Bash to verify
+commands work (e.g., `npm test --help` or `pytest --co -q | head`).
+
+## Output
+
+Structured report:
+- Test framework(s) and version
+- Test command (exact command to run tests)
+- Build command (exact command to build)
+- Lint command (exact command to lint)
+- Syntax check command per language
+- Coverage tooling (if any)
+- Approximate test count

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

@@ -0,0 +1,171 @@
+# 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.

package/dist/forge-payload/init/generation/generate-kb-doc.md

@@ -0,0 +1,60 @@
+# Knowledge Base Doc Generation — Per-Subagent Instructions
+
+You are generating **ONE** knowledge base document. You have been given:
+
+1. A **discovery context** — the raw findings from Phase 1 discovery scans,
+   passed inline in your prompt
+2. A **doc spec** — which file to write and what it should contain
+3. A **project brief** (`.forge/init-context.md`) — for names and paths
+
+Your job is to produce exactly one file and return a one-line status.
+
+---
+
+## Rules
+
+1. **Write EXACTLY ONE file** at the path specified in your doc spec.
+
+2. **Confidence header** — every generated doc must open with:
+   ```
+   <!-- AUTO-GENERATED by /forge:init — confidence: N% -->
+   ```
+   Set N% based on how much evidence the discovery context provided:
+   - 90–100%: directly observed in code/config
+   - 70–89%: inferred from conventions or partial evidence
+   - below 70%: limited evidence, many `[?]` markers expected
+
+3. **Uncertainty markers** — any fact not directly observed in the discovery
+   context must be marked with `[?]`. Do not invent values.
+
+4. **Entity names** — use entity names exactly as they appear in the brief's
+   `## Domain Entities` section. Do not rename or abbreviate.
+
+5. **Scope discipline** — generate only what the doc spec prescribes.
+   Do not add sections not listed in the spec. Do not cross-reference
+   other KB docs that do not yet exist.
+
+6. **`architecture/INDEX.md` and `business-domain/INDEX.md`** — if your
+   assigned doc is an INDEX file, link only to docs that exist on disk at
+   the time you write. Do not anticipate files that may not have been written.
+
+---
+
+## Self-check (mandatory last step)
+
+After writing the file, verify before returning:
+
+1. Read back the written file
+2. Confirm the confidence header is present on the first line
+3. Confirm no `{placeholder}` tokens remain
+4. Record in the manifest:
+   ```sh
+   node "$FORGE_ROOT/tools/generation-manifest.cjs" record "{output_path}"
+   ```
+   (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-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.