@garygentry/feature-forge 0.1.4 → 0.2.0

package/adapters/gemini/skills/forge-6-docs/forge-6-docs.md

@@ -12,7 +12,7 @@ Generate developer-focused architecture documentation for a feature, suitable fo
 
 Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
 
-**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+**Turn structure reminder:** Output analysis/context as text, then route ALL questions through the host's question mechanism. Never embed questions in text output — the user will not be prompted and the session will stall.
 
 ## Step 1: Read Context
 
@@ -30,23 +30,27 @@ Load into context:
 
 ### Implementation Completeness Check
 
-Check `{resolvedFeatureDir}/backlog.json` (or `{backlogDir}/{feature}/backlog.json` if configured). Count items with status `complete` vs total. If implementation is less than 80% complete, use `AskUserQuestion` to warn: "Implementation is only N% complete. Documentation will be based primarily on specs and may need updates after implementation. Proceed?" If user proceeds, add a `PRE-IMPLEMENTATION` notice at the top of each generated doc.
+Check `{resolvedFeatureDir}/backlog.json` (or `{backlogDir}/{feature}/backlog.json` if configured). Count items with status `complete` vs total. If implementation is less than 80% complete, use the host's question mechanism to warn: "Implementation is only N% complete. Documentation will be based primarily on specs and may need updates after implementation. Proceed?" If user proceeds, add a `PRE-IMPLEMENTATION` notice at the top of each generated doc.
 
 Also check `.pipeline-state.json` for `stages.forge-5-loop`. If it exists and has status `in-progress` (some items incomplete), include this in the warning: "The rauf loop has not fully completed — {done}/{total} items done. Documentation may need updates after remaining items are implemented."
 
+### Impl-Verify Backstop
+
+Check `.pipeline-state.json` for `stages.forge-verify-impl`. If it is **absent** or has status `"skipped"`, use the host's question mechanism to warn with the cost of skipping: "Implementation hasn't been verified yet. Recommended: run `/feature-forge:forge-verify {feature} impl` first to audit the loop's output — docs generated over unverified code can document bugs or gaps as if they were intended behavior, and readers will trust them. Generate docs anyway?" Offer **Verify first (recommended)** · **Generate docs anyway**. This mirrors `forge-4-backlog`'s pre-stage verification check and backstops a skipped impl-verify regardless of how the loop ended. If `stages.forge-verify-impl` shows it already ran (`findings-applied`, `findings-reported`, or `passed`), proceed with no warning.
+
 ### Epic-Level Documentation (epic members only)
 
 If the resolved feature has an `epic` back-pointer in its `.pipeline-state.json`, run:
 
 ```bash
-R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
 [ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
 python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
 ```
 
 If `render-status` fails, skip the epic-level offer and proceed with the per-feature docs only; surface the error per the exit-1/exit-2 split in the **Feature Directory Resolution** block of `references/shared-conventions.md` (exit 1 → parse `{findings[]}` from stdout; exit 2 → surface the plain `Error:` stderr line verbatim).
 
-**Only if `rollup.total > 0 AND rollup.complete == rollup.total`** (every member is complete-for-orchestration; the `total > 0` guard excludes an empty epic), use `AskUserQuestion` to offer:
+**Only if `rollup.total > 0 AND rollup.complete == rollup.total`** (every member is complete-for-orchestration; the `total > 0` guard excludes an empty epic), use the host's question mechanism to offer:
 
 "All {total} features in the '{epic}' epic are complete. Generate an **epic-level architecture document** spanning the features, in addition to {feature}'s per-feature docs?"
 
@@ -92,7 +96,7 @@ Based on feature complexity and existing doc conventions, propose a doc plan:
     └── adr-001-*.md   — Architecture decision records (if significant decisions were made)
 ```
 
-Present the plan and use `AskUserQuestion` to get the user's confirmation.
+Present the plan and use the host's question mechanism to get the user's confirmation.
 
 ## Step 3: Write Documentation
 
@@ -109,6 +113,11 @@ Present the plan and use `AskUserQuestion` to get the user's confirmation.
 - Specs are the source of truth for design intent; code is the source of truth for behavior
 - Read the actual source code to verify your documentation is correct
 
+**Don't cite or link spec files in the generated docs.**
+- Read the specs freely for context, but the docs you write are shipped implementation artifacts — they must be self-contained
+- Never link or reference `PRD.md`, `tech-spec.md`, or the numbered implementation specs (`specs/{feature}/NN-*.md`); these are pre-implementation artifacts that may be archived or deleted
+- Reference only the code, runtime contracts/configuration, and other generated docs. If you need to convey design intent, write it directly into the doc rather than pointing at a spec
+
 **Match existing conventions.**
 - If other features' docs use a specific heading structure, follow it
 - If they include diagrams, include diagrams
@@ -154,7 +163,7 @@ Adapt export paths to match the project's module/package conventions.
 
 ## Step 4: Review with User
 
-Present the docs as text. Then use `AskUserQuestion` to collect feedback — do NOT include these questions in your text output:
+Present the docs as text. Then use the host's question mechanism to collect feedback — do NOT include these questions in your text output:
 
 "1. Does this accurately reflect the implementation? 2. Is the level of detail appropriate for your team? 3. Any areas that need more explanation?"
 
@@ -172,7 +181,18 @@ Write pipeline state conforming to `references/pipeline-state-schema.json`.
 ## Gotchas
 
 - Don't just rephrase the specs. Documentation should explain the implemented system, not the planned system. Read the actual code.
+- Don't cite spec files (PRD.md, tech-spec.md, numbered specs) as sources or "further reading" in the generated docs — specs are pre-implementation artifacts that may not survive. Keep the docs self-contained; link only to code, configuration, and other docs.
 - If the implementation doesn't exist yet (backlog hasn't been run), document based on specs but note prominently that docs are pre-implementation and may need updating.
 - API reference should include actual function signatures from the code, not from the spec (they may differ).
 - Don't generate docs that will immediately be stale. Focus on concepts, architecture, and patterns rather than line-by-line code walkthroughs.
 - Include "When to use" and "When NOT to use" sections — they save developers more time than any other documentation pattern.
+
+---
+
+## Host execution notes
+
+This skill was authored Claude-first; the body above refers to "the host's question mechanism", "the host's subagent mechanism", and "the host's background-execution mechanism". Use your runtime's equivalent for each — and if your runtime has no such tool:
+
+- **User input:** ask the question directly and wait for the answer before proceeding. Do not skip a required question or assume an answer.
+- **Subagents:** if your host cannot dispatch the named custom agent, run that step inline yourself.
+- **Background / monitoring:** run long-lived commands in the foreground (or your host's background facility) and report progress as it arrives.

package/adapters/gemini/skills/forge-bootstrap/forge-bootstrap.md

@@ -0,0 +1,249 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-bootstrap/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-bootstrap
+description: Scaffold a brand-new empty repository to a pipeline-ready, green baseline (structure, toolchain, passing lint+test, forge.config.json), then optionally chain into the pipeline. Use when the user runs /feature-forge:forge-bootstrap or asks to bootstrap/scaffold a new empty project for forge. Do NOT trigger on a non-empty repo (that is forge-init), or for general project setup outside the forge pipeline.
+---
+
+# Bootstrap a Greenfield Repo
+
+Take a **brand-new, empty** repository to a pipeline-ready, **green** baseline — a
+scaffolded stack, a valid `forge.config.json`, and a passing lint+test — then optionally
+chain into the pipeline (Mode B). You own the **conversation and decisions only**; every
+mechanic (the greenfield gate, `git init`, scaffolding, the config write, the toolchain
+probe, the commit) is delegated to the helper `scripts/forge-bootstrap.py`. Never inline
+file generation, template contents, the config field list, or the greenfield allow-list —
+they live in the helper and templates, referenced here, never duplicated.
+
+`<target-dir>` below is the project being bootstrapped (default `.`, or the argument) — it is
+**distinct from `$R`**, the plugin root. Drive control flow off the helper's exit codes and
+JSON: **0** = ok, **1** = actionable findings, **2** = usage/IO **or** verify
+toolchain-missing.
+
+## Host adaptation (conversational fallback)
+
+If the host's question mechanism is available, ask the interview questions through it. If it is
+**not** available (a non-Claude host such as Codex), emit the same questions as a single
+**numbered text list** — each line one question with its options in brackets and the default
+marked — then **stop and wait for a single text reply**. Parse the reply positionally
+(answer N → question N); re-prompt only the unparseable items. The question content (text,
+options, defaults) and the conditional gating (Q4 skipped for go/rust/generic; Q6a only for
+monorepo; Q8 only after a verified-green baseline) are **identical** across both paths — only
+the rendering changes. Never assume answers; always wait for the reply.
+
+Emit any context as plain text, then route **all** questions through the host's question mechanism (or the
+fallback) — never as inline prose questions, which stall the session.
+
+## Flow (Mode A — default)
+
+```
+1. Portable-root prelude            → locate $R
+2. check                            → gate + recovery detection
+     ├─ eligible:false   (exit 1)   → Greenfield refusal — STOP
+     └─ resumeMarker != null        → Resume / restart / cancel
+3. Interview                        → assemble the Answers payload
+4. scaffold --answers <json>        → git init if absent; compose templates; write config;
+                                       track artifacts into the sentinel
+5. verify                          → toolchain probe + lint/test per member
+     ├─ toolchainPresent:false (2)  → Missing toolchain: scaffold-anyway-unverified vs abort
+     ├─ green:false      (exit 1)   → Not-green: surface failures, offer fix/abort
+     └─ green:true       (exit 0)   → proceed
+6. commit  [--stage-only per Q9]    → stage exact tracked list; single baseline commit;
+                                       remove the sentinel before staging
+7. Completion summary / Mode B hand-off
+```
+
+### Step 1 — locate the helper
+
+Every bash invocation begins with the byte-identical portable-root prelude, then calls the
+helper. Pass `--specs-dir ./specs` (the default) so the gate allow-lists the specs directory.
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-bootstrap.py" check "<target-dir>" --json --specs-dir ./specs
+```
+
+Never hardcode a plugin path or a `~/.claude/...` path — always go through `$R`.
+
+### Step 2 — gate (`check`)
+
+Read `CheckResult{eligible, disqualifying[], resumeMarker}`.
+
+- **`eligible:false` (exit 1) → Greenfield refusal.** Name **every** path in `disqualifying[]`
+  verbatim, then direct the user to the right tool — run `forge-init`, then `forge-1-prd`.
+  **Touch no files** and STOP (the gate is read-only).
+
+  ```
+  This repo is not empty — forge-bootstrap only scaffolds a brand-new project.
+  Disqualifying files found:
+    - package.json
+    - src/index.ts
+  To set forge up on an existing project, run:  /feature-forge:forge-init
+  Then start the pipeline with:                 /feature-forge:forge-1-prd <feature>
+  ```
+
+- **`resumeMarker != null` → Partial-state detected.** A `.forge-bootstrap.json` sentinel
+  from this tool's own prior run exists — do **not** treat it as a refusal. Surface the prior
+  run's `startedAt` and `artifactsWritten[]`, then ask **resume / restart / cancel**:
+  - **Resume** — reuse the sentinel's mirrored `answers` (no re-interview), re-run `scaffold`
+    (idempotent — the helper skips already-recorded files), continue from step 5.
+  - **Restart** — discard the partial: delete the recorded `artifactsWritten[]` tree + the `.forge-bootstrap.json` sentinel (a skill-orchestration step — the helper has no clean subcommand), then run the interview and `scaffold` fresh.
+  - **Cancel** — stop without changes.
+
+  You perform no cleanup yourself; you only render the choice and dispatch the subcommand.
+
+### Step 3 — interview
+
+Ask exactly these, in order. Resolved answers become the `Answers` payload handed to
+`scaffold --answers`.
+
+| # | Question | Default / seed rule | Options |
+|---|----------|---------------------|---------|
+| Q1 | Project name? | default = target directory basename (confirm) | free-text, pre-filled |
+| Q2 | One-line purpose? | no default; seeds README + config | free-text |
+| Q3 | Language / stack? | required | `typescript` / `python` / `go` / `rust` / `generic` |
+| Q4 | Package manager? | **only when the stack has a choice** — TS: `npm`/`pnpm`/`yarn`, Python: `uv`/`poetry`/`pip`; **skipped** for go/rust/generic | the stack's options |
+| Q5 | License? | **detect & pre-select** from a pre-existing `LICENSE` (see gating); else default `MIT`. The helper keeps an existing `LICENSE` (REQ-SCAF-09) | `MIT` / `Apache-2.0` / `none` |
+| Q6 | Single package or monorepo? | default `single` | `single` / `monorepo` |
+| Q6a | (monorepo only) member count, then per-member name + stack | no default; one member each (mixed-language allowed) | loop |
+| Q7 | Chain into the pipeline now (Mode B)? | default `no` | `no, scaffold only` / `yes, chain in` |
+| Q8 | (Mode B only) First build: feature or epic? | asked **only after a verified-green baseline** | `feature` / `epic` |
+| Q9 | Commit the baseline, or leave it staged? | default `commit` | `commit` / `stage only` |
+
+Gating: Q4 is asked only when the chosen stack has a package-manager choice; Q6a only when
+Q6 = `monorepo` (each member gets a `path` like `packages/<name>`; a single package is one
+member with `path = "."`); Q7 may be asked up-front, but Q8 / Mode B launch are gated on a
+verified-green, committed baseline (see below). You may also offer an optional
+"generate a CI workflow (lint+test)?" question, setting `Answers.ci`.
+
+License detect-and-seed (Q5, REQ-SCAF-09): when a `LICENSE` already exists in the target
+(an allowed-meta file the gate let through), **read its first lines** and pre-select the
+matching Q5 default — "MIT License" → `MIT`, "Apache License" → `Apache-2.0`, otherwise
+keep the default and note the unrecognized license. The helper never overwrites the existing
+`LICENSE`; this only seeds the interview default. Also set `Answers.author` from
+`git config user.name` (fallback: the project name) and `Answers.host` to `claude` when
+running on a Claude host (so the helper emits `CLAUDE.md` alongside `AGENTS.md`), else leave
+it null.
+
+**Assemble the payload.** Build one `Answers` JSON object — `projectName`, `purpose`,
+`layout`, `license`, `members[]`, `modeB`, `modeBTarget`, `ci`, `commitStyle`, `author`,
+`host` — and pass it verbatim to `scaffold --answers '<json>'`. Invent no fields beyond that
+schema. Two fields come from your runtime, not the interview: `author` from `git config
+user.name` (else the project name; it is the LICENSE copyright holder), and `host` — `"claude"`
+when running under a Claude host (e.g. the host's question mechanism is available), else `"codex"`/`"other"`.
+`host` drives the host-conditional agent file: the helper always emits `AGENTS.md` and adds
+`CLAUDE.md` only when `host == "claude"`.
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-bootstrap.py" scaffold "<target-dir>" --json --answers '<Answers JSON>'
+```
+
+### Step 5 — verify
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-bootstrap.py" verify "<target-dir>" --json --answers '<Answers JSON>'
+```
+
+Read `VerifyResult{green, toolchainPresent, lint[], test[]}`.
+
+- **`toolchainPresent:false` (exit 2) → Missing toolchain.** Warn, naming which stack's
+  toolchain is missing. Ask **scaffold-anyway (unverified) vs abort**. If scaffold-anyway,
+  proceed to commit and mark the baseline **unverified** in the summary — never claim green
+  you could not verify. If abort, stop; the sentinel stays in-progress for a later resume. An
+  unverified baseline **disqualifies Mode B** (no override).
+- **`green:false` with `toolchainPresent:true` (exit 1) → Not-green.** Surface the failing
+  `CommandOutcome` entries (command + member) verbatim; offer abort or retry-after-investigation.
+  Do not silently proceed to a "green" summary.
+- **`green:true` (exit 0)** → proceed to commit.
+
+### Step 6 — commit
+
+Invoke `commit` (or `commit --stage-only`, per Q9). Helper-owned: it stages the **exact
+tracked list** (never `git add -A`/`--force`/`--no-verify`), makes a single baseline commit,
+and removes the sentinel before staging so it never enters history. Read
+`CommitResult{committed, commitHash, staged[]}`. On commit failure, surface the error and
+leave the sentinel in-progress (resumable) — do **not** declare success.
+
+```bash
+R="$(for d in "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done)"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/forge-bootstrap.py" commit "<target-dir>" --json --answers '<Answers JSON>' [--stage-only]
+```
+
+## Completion summary
+
+Render the human-facing summary from the helper's JSON (`VerifyResult` + `CommitResult`). State:
+created artifacts (from `CommitResult.staged[]`, including any kept pre-existing meta file);
+resolved stack(s) (single, or each monorepo member's name + stack); the **verification
+verdict** — `green` or `unverified` (never "green" for an unverified baseline); the commit
+state (with `commitHash`, or staged-only); and the exact next command. In Mode B, **launch**
+the next stage instead of printing the command.
+
+```
+Bootstrap complete — pipeline-ready baseline.
+  Stack:        python (uv)
+  Created:      pyproject.toml, src/acme_svc/..., tests/test_smoke.py, .gitignore,
+                README.md, LICENSE, AGENTS.md, CLAUDE.md, forge.config.json
+  Kept:         (none — README/LICENSE generated fresh)
+  Verification: green  (mypy ✓   pytest ✓)
+  Commit:       baseline committed (a1b2c3d)
+  Next step:    /feature-forge:forge-1-prd <feature>
+```
+
+Unverified variant:
+
+```
+  Verification: UNVERIFIED — toolchain not found on this machine; lint+test were not run.
+                Install the toolchain and re-run verify before relying on the baseline.
+```
+
+## Mode B hand-off (opt-in)
+
+Mode B is **opt-in** (Q7; default Mode A) and **agent-driven** — it hands skill-to-skill to
+the next pipeline stage, not through the helper.
+
+**Gate:** launch the next stage **only after both** a verified-green baseline
+(`VerifyResult.green == true`) **and** a successful commit (`CommitResult.committed == true`).
+If the baseline is unverified or not-green, you MUST NOT launch the next stage and MUST NOT
+even ask Q8 — fall back to the Mode A summary with the next command printed. There is no
+"launch anyway on red" path.
+
+When the gate passes:
+
+1. Ask Q8 — feature vs epic — if not already resolved.
+2. **Feature:** invoke `forge-1-prd <feature>` skill-to-skill, seeding `<feature>` from a
+   confirmed, kebab-cased name.
+3. **Epic:** invoke `forge-0-epic <epic>` skill-to-skill. Seed the epic name and initial
+   decomposition from the project name + purpose (Q1/Q2), **propose it, let the user
+   edit/approve**, then launch.
+4. **Launch** that stage instead of printing its command.
+
+Mode B auto-launches **only the immediate next stage**; every subsequent pipeline stage stays
+a normal, user-driven step. The hand-off is always skill-to-skill, never via the helper.
+
+## The four terminal outcomes
+
+Every run ends in exactly one explicit, actionable outcome — make it explicit in your output;
+no run ends silently:
+
+- **Success** — `commit` exit 0 + green (or unverified-but-proceeded) → completion summary, or
+  Mode B launch.
+- **Greenfield refusal** — `check` `eligible:false` → name `disqualifying[]`, point to
+  `forge-init` + `forge-1-prd`, touch nothing.
+- **Missing toolchain** — `verify` `toolchainPresent:false` (exit 2) → scaffold-anyway-unverified
+  vs abort; mark **unverified**.
+- **Partial-state detected** — `check` `resumeMarker != null` → resume / restart / cancel.
+
+---
+
+## Host execution notes
+
+This skill was authored Claude-first; the body above refers to "the host's question mechanism", "the host's subagent mechanism", and "the host's background-execution mechanism". Use your runtime's equivalent for each — and if your runtime has no such tool:
+
+- **User input:** ask the question directly and wait for the answer before proceeding. Do not skip a required question or assume an answer.
+- **Subagents:** if your host cannot dispatch the named custom agent, run that step inline yourself.
+- **Background / monitoring:** run long-lived commands in the foreground (or your host's background facility) and report progress as it arrives.

package/adapters/gemini/skills/forge-bootstrap/references/templates/ci/github-actions.yml

@@ -0,0 +1,12 @@
+name: ci
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # <<MEMBER_STEPS>>

package/adapters/gemini/skills/forge-bootstrap/references/templates/generic/run.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Entrypoint for the scaffolded baseline.
+echo "Hello from {{PROJECT_NAME}}"

package/adapters/gemini/skills/forge-bootstrap/references/templates/generic/test.sh

@@ -0,0 +1,13 @@
+#!/bin/sh
+# Behavioral test: run the entrypoint and assert its output.
+set -eu
+
+actual="$(./run.sh)"
+expected="Hello from {{PROJECT_NAME}}"
+
+if [ "$actual" != "$expected" ]; then
+  printf 'FAIL: expected %s but got %s\n' "$expected" "$actual" >&2
+  exit 1
+fi
+
+printf 'PASS: run.sh produced the expected greeting\n'

package/adapters/gemini/skills/forge-bootstrap/references/templates/go/go.mod

@@ -0,0 +1,3 @@
+module {{PKG}}
+
+go 1.21

package/adapters/gemini/skills/forge-bootstrap/references/templates/go/main.go

@@ -0,0 +1,12 @@
+package main
+
+import "fmt"
+
+// greet returns the project greeting for name.
+func greet(name string) string {
+	return "Hello from " + name
+}
+
+func main() {
+	fmt.Println(greet("{{PROJECT_NAME}}"))
+}

package/adapters/gemini/skills/forge-bootstrap/references/templates/go/main_test.go

@@ -0,0 +1,11 @@
+package main
+
+import "testing"
+
+func TestGreet(t *testing.T) {
+	got := greet("world")
+	want := "Hello from world"
+	if got != want {
+		t.Errorf("greet(\"world\") = %q, want %q", got, want)
+	}
+}

package/adapters/gemini/skills/forge-bootstrap/references/templates/hygiene/AGENTS.md

@@ -0,0 +1,24 @@
+# Agent Instructions — {{PROJECT_NAME}}
+
+## Project Purpose
+
+{{PURPOSE}}
+
+## Getting Started
+
+This project was scaffolded by forge-bootstrap. To continue development:
+
+1. Review `forge.config.json` for the project configuration.
+2. Run the forge pipeline (forge-1-prd → forge-0-epic → forge-3-specs → forge-4-backlog) to plan and implement features.
+3. Use `forge-5-loop` to drive autonomous implementation.
+
+## Conventions
+
+- Follow the patterns established in the existing codebase.
+- Keep `forge.config.json` up to date with any changes to stack or commands.
+
+## Specs are pre-implementation
+
+- Documents under `specs/` (PRDs, tech specs, numbered implementation specs) establish the backlog. They are **not** kept in sync with the code as it evolves.
+- Do not flag or "fix" divergence between a finalized spec and the implementation — code is the source of truth for behavior.
+- It's fine for `specs/` artifacts and `backlog.json` to reference specs for provenance, but implementation artifacts (source code, generated skills/agents, configs, docs) must not reference spec files, which may be archived or deleted after a feature ships.

package/adapters/gemini/skills/forge-bootstrap/references/templates/hygiene/CLAUDE.md

@@ -0,0 +1,25 @@
+# Claude Instructions — {{PROJECT_NAME}}
+
+## Project Purpose
+
+{{PURPOSE}}
+
+## Getting Started
+
+This project was scaffolded by forge-bootstrap. To continue development:
+
+1. Review `forge.config.json` for the project configuration.
+2. Run the forge pipeline (forge-1-prd → forge-0-epic → forge-3-specs → forge-4-backlog) to plan and implement features.
+3. Use `forge-5-loop` to drive autonomous implementation.
+
+## Working with Claude
+
+- Use `/feature-forge:forge` to enter the forge pipeline for new features.
+- The `forge.config.json` at the project root defines the stack, commands, and pipeline settings.
+- Follow the patterns established in the existing codebase.
+
+## Specs are pre-implementation
+
+- Documents under `specs/` (PRDs, tech specs, numbered implementation specs) establish the backlog. They are **not** kept in sync with the code as it evolves.
+- Don't flag or "fix" divergence between a finalized spec and the implementation — code is the source of truth for behavior.
+- It's fine for `specs/` artifacts and `backlog.json` to reference specs for provenance, but implementation artifacts (source code, generated skills/agents, configs, docs) must not reference spec files, which may be archived or deleted after a feature ships.

package/adapters/gemini/skills/forge-bootstrap/references/templates/hygiene/README.md

@@ -0,0 +1,11 @@
+# {{PROJECT_NAME}}
+
+{{PURPOSE}}
+
+## License
+
+This project is licensed under {{LICENSE}}.
+
+---
+
+_Scaffolded by [forge-bootstrap](https://github.com/feature-forge/feature-forge)._