@garygentry/feature-forge 0.1.4 → 0.1.5

package/adapters/gemini/skills/forge-5-loop/references/runner-contract.md

@@ -70,6 +70,38 @@ The default / `claude-cli` path runs **no** probe (zero extra cost). See
 `04-availability-precheck.md` for the full pre-check, classification, and allow-list,
 and `02-config-schema-and-gating.md` for the capability gate.
 
+> **Probe false-negative for Claude Code installs (advisory).** `rauf agents` may
+> report `claude-cli` **unavailable** (e.g. *"credentials file not found:
+> ~/.config/claude-code/credentials.json"*) even when a working `claude` CLI
+> authenticates elsewhere — the probe's credential heuristic doesn't cover every
+> install. This is a rauf probe concern, not something forge-5-loop fixes. The
+> **default-agent path skips the probe entirely**, so an ordinary default run is
+> unaffected; only an **explicit** `--agent claude-cli` would be flagged UNAVAILABLE,
+> and the existing **proceed-anyway** path (above) covers it. Do not attempt to
+> patch rauf's probe from here.
+
+### Claude-only model-alias guard (Step 2d, sub-step d-model)
+
+When the resolved agent is **non-default** (not the default / `claude-cli` path),
+forge must guard against a backlog whose items pin **Claude-specific** model aliases.
+forge-4-backlog (via the rauf author-backlog skill) writes Claude tier aliases
+(`opus` / `sonnet`) into each item's `model`. Because rauf's precedence puts
+`item.model` **above** `--agent`, the alias is forwarded verbatim to the selected
+agent; a non-Claude agent (e.g. codex) then 400s — *"The 'sonnet' model is not
+supported when using Codex with a ChatGPT account."* — so **every** spawn exits 1 and
+rauf reports *"Circuit breaker: 3 consecutive infra failures — halting"* with no hint
+of the real cause. forge-5-loop therefore detects Claude-specific `model` aliases in
+the backlog (tier aliases `opus`/`sonnet`/`haiku` or `claude-*` ids) and, before
+launch, **warns** and offers (via `AskUserQuestion`) to **strip `model` for this run**
+(remove the key from each affected item so each spawn uses the agent's own default) or
+**proceed as-is**. forge only ever touches the `model` field — never `provider`. The
+default / `claude-cli` path skips this guard (the aliases are valid there).
+
+> **Follow-up (out of scope here — rauf repo).** The durable fix would be for the
+> rauf `author-backlog` skill to keep `model` **provider-neutral** by default (or to
+> document that writing a tier alias binds the backlog to Claude agents). That lives
+> in the separate rauf plugin/repo, not feature-forge; tracked as a follow-up.
+
 ## Optional flags catalog (Step 2d, rauf)
 
 These are the optional flags the user may add to the rendered run command. If the
@@ -92,6 +124,14 @@ Launch the loop **backgrounded** so it survives session end and does not block t
 session, and prefer the machine-readable event stream so the session can supervise
 it live.
 
+> **Clean-tree precondition.** rauf refuses to run with uncommitted changes
+> (*"Refusing to run the loop with uncommitted changes… pass --force"*). Step 3a's
+> in-progress `.pipeline-state.json` write is itself an uncommitted change, so it
+> **must be committed before launch** (Step 3a) — otherwise the first launch on an
+> otherwise-clean repo always fails. If the tree still has unrelated uncommitted
+> changes after that commit, surface it and let the user commit/stash or pass
+> `--force`; never auto-pass `--force`.
+
 - **If `loopRunner.eventStreamCommand` is configured (default for rauf):** render it
   (it appends `--ndjson` to the run) and launch via the Bash tool with
   `run_in_background: true`, redirecting stdout to a stable events file:

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

@@ -34,6 +34,10 @@ Check `{resolvedFeatureDir}/backlog.json` (or `{backlogDir}/{feature}/backlog.js
 
 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 `AskUserQuestion` to warn: "Implementation hasn't been verified yet. It's recommended to run `/feature-forge:forge-verify {feature} impl` first to audit the loop's output. 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:
@@ -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
@@ -172,6 +181,7 @@ 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.

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

@@ -0,0 +1,239 @@
+---
+# 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 `AskUserQuestion` tool 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 `AskUserQuestion` (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; 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. `AskUserQuestion` 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; 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; 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; 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.

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)._

package/adapters/gemini/skills/forge-bootstrap/references/templates/licenses/Apache-2.0/LICENSE

@@ -0,0 +1,198 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any patent
+      claims embodied in the Work constitute direct or indirect patent
+      infringement, then any patent licenses granted to You under this
+      License for that Work shall terminate as of the date such litigation
+      is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the
+          License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Contribution, and to permit persons to whom the Contribution is
+      furnished to do so, provided that Your use, reproduction, and
+      distribution of the Work otherwise complies with the conditions
+      stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any conditions of
+      TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining
+      the appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer only
+      conditions consistent on your own behalf and on Your sole
+      responsibility, not on behalf of any other Contributor, and only if
+      You agree to indemnify, defend, and hold each Contributor harmless
+      for any liability incurred by, or claims asserted against, such
+      Contributor by reason of your accepting any such warranty or
+      additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format in use. We also recommend that
+      a file or directory name be included, with the "full path" if
+      practical.
+
+   Copyright {{YEAR}} {{AUTHOR}}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.