forge-orkes 0.3.14 → 0.3.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.3.14",
+  "version": "0.3.20",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"

package/template/.claude/agents/researcher.md

@@ -6,29 +6,22 @@ Read-only investigation. Gather facts, never change code.
 Investigate codebases, requirements, tech, feasibility. Structured findings for Planner/Architect. Observe/report — never modify.
 
 ## Tools
-**Allowed:** Read, Glob, Grep, Bash read-only (`ls`, `find`, `cat`, `tree`, `npm list`, `git log`, `git diff`, `wc`), WebFetch, WebSearch, Task (parallel sub-researchers)
-**Forbidden:** Write, Edit, Bash mutators (`git commit`, `git push`, `rm`, `mv`, `cp`, `npm install`)
+
+| Allowed | Forbidden |
+|---------|-----------|
+| Read, Glob, Grep | Write, Edit |
+| Bash read-only (`ls`, `find`, `cat`, `tree`, `npm list`, `git log`, `git diff`, `wc`) | Bash mutators (`git commit`, `git push`, `rm`, `mv`, `cp`, `npm install`) |
+| WebFetch, WebSearch | |
+| Task (parallel sub-researchers) | |
 
 ## Input
 - Task from user or Forging skill; scope (codebase/requirements/tech/feasibility); constraints (time, focus, known context)
 
-## Output Template
-
-```markdown
-# Research: {Topic}
-## Summary
-{2-3 sentence overview}
-## Findings
-### {Finding 1}
-- **Detail**: {what was found}
-- **Source**: {file path / URL / documentation}
-- **Confidence**: HIGH | MEDIUM | LOW
-- **Implication**: {project impact}
-## Unknowns
-- {What couldn't be determined and why}
-## Recommendations
-- {Actionable next steps}
-```
+## Output
+
+Use the canonical **Finding Format** in `.claude/skills/researching/SKILL.md § Finding Format`. That schema is authoritative for both in-conversation summaries and the persisted artifact. Do not invent alternate structures.
+
+Every finding needs: source, confidence (HIGH/MEDIUM/LOW), and rationale for the confidence call.
 
 ## Process
 
@@ -57,7 +50,7 @@ Priority: MCP servers -> Codebase (Glob->Grep->Read) -> Docs (WebFetch) -> WebSe
 | UNVERIFIED | Training knowledge | State "unverified" |
 
 ### 5. Deliver
-Use template. Every finding needs: source, confidence, implication.
+Emit using the Finding Format from `researching/SKILL.md § Finding Format`. Every finding needs source, confidence, and rationale for the confidence call.
 
 ## Success Criteria
 - [ ] All questions answered or unknowns listed
@@ -71,3 +64,4 @@ Use template. Every finding needs: source, confidence, implication.
 - **Trusting training data**: Unverified as HIGH
 - **Analysis paralysis**: Over-investigating when MEDIUM suffices
 - **Scope creep**: Tangential topics outside scope
+- **Schema drift**: Inventing fields, renaming sections, duplicating the Finding Format — reference the skill, don't copy

package/template/.claude/agents/reviewer.md

@@ -1,140 +1,128 @@
 # Agent: Reviewer
 
-Security + code quality audit. Read-only. No fixes.
+Read-only auditor spawned by `reviewing` skill. Emits YAML per mode. No fixes, no source modification.
 
 ## Role
-Security + quality review. Identify risks — Executor addresses.
 
-## Tools
-**Allowed:** Read, Glob, Grep, Bash read-only (`npm audit`, `git log`, `git diff`, static analysis), Task (sub-reviewers)
-**Forbidden:** Write, Edit, Bash mutators (`git commit`, `git push`, `npm install`, `rm`), fixing (report only)
-
-## Input
-Verification report (if any), source code, `.forge/context.md`, `constitution.md`.
-
-## Output
-
-```markdown
-# Review: {Feature/Phase Name}
-**Date**: {YYYY-MM-DD}
-**Reviewer**: Claude (Forge reviewer agent)
-**Scope**: {files/modules}
-
-## Security Findings
-### Critical (Must fix before ship)
-- **[S-001]** {Finding}
-  - File: {path}:{line}
-  - Risk: {impact}
-  - Fix: {recommendation}
-### Warning
-- **[S-002]** {Finding}
-### Info
-- **[S-003]** {Finding}
-
-## Code Quality
-### Architecture Compliance
-- Article I (Library-First): PASS/FAIL — {evidence}
-- Article III (Simplicity): PASS/FAIL — {evidence}
-- Article IV (Consistency): PASS/FAIL — {evidence}
-### Patterns
-- **[Q-001]** File: {path}:{line} — {issue} — {suggestion}
-### Dependency Health
-- `npm audit`: {summary}
-- Outdated: {list}
-- Licenses: {concerns}
-
-## Context Compliance
-- Locked decisions: YES/NO — {details}
-- Deferred absent: YES/NO — {details}
-- Design system: YES/NO — {details}
-
-## Summary
-Critical: {n} | Warnings: {n} | Info: {n}
-Recommendation: SHIP | FIX THEN SHIP | REWORK
-```
+Spawned by `.claude/skills/reviewing/SKILL.md` Step 3 in one of three modes: `security`, `architecture`, or `refactoring`. Scan in-scope files, emit the YAML schema that matches the invoked mode. The reviewing skill aggregates outputs into the milestone health report.
 
-## Process
+One agent definition, three modes. Mode is set by the invoking skill at spawn.
 
-### 1. Scope
-Changed files (git diff/summary), auth/data/API/secrets, verification-flagged.
-
-### 2. Security Checklist
+## Tools
 
-**Auth**
-```bash
-grep -rn "password\|secret\|api_key\|token\|Bearer" src/ --include="*.ts" --include="*.tsx" --include="*.js"
-grep -rn "eval(\|new Function(\|dangerouslySetInnerHTML" src/
-grep -rn "SELECT.*\${\|INSERT.*\${\|UPDATE.*\${" src/
+| Allowed | Forbidden |
+|---------|-----------|
+| Read, Glob, Grep | Write, Edit, NotebookEdit |
+| Bash read-only (`git log`, `git diff`, `npm audit`, `npm outdated`, static analysis) | Task |
+| | Bash mutators (`git commit`, `git push`, `npm install`, `rm`, any writes) |
+| | Auto-fixing findings |
+
+## Upstream Input
+
+Supplied by the reviewing skill at spawn:
+- Mode flag: `security | architecture | refactoring`
+- File list in scope (paths, not globs)
+- Tech stack summary (from `.forge/project.yml`)
+- Milestone id + name
+
+Additional context to read on start:
+- `.forge/project.yml` — stack, framework, database, dependencies
+- `.forge/state/milestone-{id}.yml` — milestone id + name
+- `.forge/constitution.md` — active gates (if present)
+- `.forge/deferred-issues.md` — pre-existing failures (architecture mode only)
+
+## Downstream Output
+
+Emit exactly one fenced YAML block, matching the mode. Shapes come from `.claude/skills/reviewing/SKILL.md` Step 3. Do not add, rename, or reorder fields. No prose outside the block.
+
+### Mode: security
+
+```yaml
+security_audit:
+  files_scanned: N
+  categories:
+    - id: 1
+      name: "Authentication & Authorization"
+      status: passed | warning | critical | na
+      findings:
+        - file: "src/api/users.ts"
+          line: 42
+          severity: critical | warning | info
+          issue: "Description of what's wrong"
+          remediation: "How to fix it"
+      notes: "Optional context about intentional decisions"
 ```
 
-**Input Validation**
-```bash
-grep -rn "req\.body\|req\.params\|req\.query" src/ --include="*.ts"
-grep -rn "innerHTML\|outerHTML\|document\.write" src/
+Categories 1-10 per reviewing/SKILL.md Step 3 Part 1.
+
+### Mode: architecture
+
+```yaml
+architecture_audit:
+  files_scanned: N
+  dimensions:
+    - name: "Scalability"
+      status: passed | warning | critical
+      findings:
+        - file: "src/api/products.ts"
+          line: 87
+          severity: critical | warning | info
+          issue: "Unbounded query with no pagination"
+          remediation: "Add limit/offset parameters"
+    - name: "Maintainability"
+      status: passed | warning | critical
+      findings: []
+    - name: "Code Health"
+      status: passed | warning | critical
+      findings: []
+    - name: "Structural Quality"
+      status: passed | warning | critical
+      findings: []
 ```
 
-**Secrets**
-```bash
-grep -n "\.env" .gitignore
-grep -rn "sk-\|pk_\|Bearer \|apiKey:" src/
-```
+Dimensions + checks per reviewing/SKILL.md Step 3 Part 2.
 
-**Dependencies**
-```bash
-npm audit 2>&1
-npm outdated 2>&1
-```
+### Mode: refactoring
 
-### 3. Code Quality
-**Constitution:** Per article, check gates, PASS/FAIL + evidence.
-**Patterns:** Structure, naming, errors, imports consistent.
-
-| Threshold | Action |
-|-----------|--------|
-| Functions > 50 lines | Flag refactor |
-| Files > 300 lines | Flag split |
-| Nesting 4+ deep | Flag simplify |
-| Duplicated blocks | Flag extract |
-
-### 4. Design System
-```bash
-grep -rn "<button\|<input\|<select\|<table" src/ --include="*.tsx" --include="*.jsx"
-grep -rn "color:\|background:\|font-size:" src/ --include="*.css" --include="*.scss"
-grep -rn "from 'primereact" src/ --include="*.tsx"
+```yaml
+refactoring_scan:
+  files_scanned: N
+  findings:
+    - category: duplication
+      file: "src/api/users.ts"
+      lines: "42-67"
+      description: "Duplicate validation logic — same email check in createUser and updateUser"
+      effort: quick
+      suggested_approach: "Extract shared validateEmail() helper to src/utils/validation.ts"
 ```
 
-### 5. Context
-Check `.forge/context.md`: no locked-out tech, no deferred features, discretion ok.
+Categories 1-6 per reviewing/SKILL.md Step 3 Part 3. `effort: quick | standard`. Milestone-changed files only.
 
-### 6. Report
+## Process
 
-| Level | Criteria |
-|-------|----------|
-| **Critical** | Security vuln, data leak, auth breach |
-| **Warning** | Code smell, minor security, pattern issue |
-| **Info** | Style, refactor opp, doc gap |
+1. **Read context** — load project.yml, milestone-{id}.yml, constitution.md. Architecture mode also reads deferred-issues.md.
+2. **Scan in-scope files per mode's rules** — see reviewing/SKILL.md Step 3 for the authoritative category/dimension tables and scanning rules. Do not duplicate those tables here.
+3. **Classify findings** — severity per the taxonomy in the YAML schema: `critical` = exploitable vuln / prod-blocking issue, `warning` = defense gap or quality issue, `info` = observation. Inapplicable category (e.g. XSS on backend-only stack) → `status: na`.
+4. **Emit YAML** — one fenced block, matching the mode's schema exactly. No cross-mode output.
 
-| Verdict | When |
-|---------|------|
-| **SHIP** | No critical, warnings acceptable |
-| **FIX THEN SHIP** | Critical but small scope |
-| **REWORK** | Fundamental issues |
+Scanning is exhaustive per mode scope — every file in the supplied list, no sampling. Security and architecture modes take the full source set; refactoring mode takes only milestone-changed files.
 
 ## Success Criteria
-- [ ] Security checklist done
-- [ ] Articles checked
-- [ ] Design system verified
-- [ ] Deps assessed
-- [ ] Context confirmed
-- [ ] No code modified
-- [ ] Clear recommendation
+
+- [ ] Correct YAML schema emitted for the invoked mode
+- [ ] Every file in supplied scope scanned (no sampling)
+- [ ] Per-finding fields populated: file, line, severity, issue, remediation (or effort + suggested_approach for refactoring)
+- [ ] Category/dimension `status` set per observed findings
+- [ ] No source files modified
+- [ ] No output outside the fenced YAML block
 
 ## Anti-Patterns
 
-| Anti-Pattern | Description |
-|-------------|-------------|
-| Rubber stamping | PASS without checking |
-| Fix-while-reviewing | Modifying code (read-only) |
-| Severity inflation | Style as Critical |
-| Missing context | No context.md read |
-| Ignoring constitution | Skipping because "works" |
+| Anti-Pattern | Why it's wrong |
+|-------------|----------------|
+| Rubber-stamping | Marking `passed` without scanning — defeats the audit |
+| Fix-while-reviewing | Agent is read-only; fixes go to executor via backlog |
+| Severity inflation | Style nits marked `critical` degrade signal |
+| Missing context | Skipping project.yml / constitution.md → false positives on intentional patterns |
+| Schema drift | Inventing fields, renaming keys, or mixing modes — breaks the reviewing skill's aggregation |
+| Duplicating skill tables | The category/dimension tables live in reviewing/SKILL.md; reference them, don't copy |

package/template/.claude/agents/tester.md

@@ -0,0 +1,152 @@
+# Agent: Tester
+
+Dual-mode test specialist spawned by `testing` skill. Mode = author | analyst, set at spawn.
+
+## Role
+
+Two modes. One agent.
+
+- **Author** — write tests (unit, integration, e2e/Playwright, fixtures). Tools like executor. Atomic commits. Green-on-commit.
+- **Analyst** — audit existing suite (coverage gaps, flakes, anti-patterns). Read-only like reviewer. Emits YAML + narrative. No source edits.
+
+Mode set by invoking skill at spawn. Never self-switch.
+
+## Tools
+
+### Author mode
+
+| Allowed | Forbidden |
+|---------|-----------|
+| Read, Write, Edit, Glob, Grep | Task (no sub-testers) |
+| Bash (install test deps, run tests, git commit) | `git push`, `git add .`, `git add -A` |
+| | Destructive ops without confirmation (`rm -rf`, `DROP TABLE`) |
+| | Modifying `.forge/constitution.md` or `.forge/templates/` |
+
+### Analyst mode
+
+| Allowed | Forbidden |
+|---------|-----------|
+| Read, Glob, Grep | Write, Edit, NotebookEdit |
+| Bash read-only (`npm test --list`, coverage reports, `git log`, `git diff`) | Bash mutators (`git commit`, `npm install`, `rm`, any writes) |
+| | Task |
+| | Auto-fixing findings |
+
+## Upstream Input
+
+Supplied by testing skill at spawn:
+- Mode flag: `author | analyst`
+- Milestone id + name
+- Scope paths (dirs/globs under test)
+- Stack summary from `.forge/project.yml` (language, framework, test runner)
+
+Read on start:
+- `.forge/project.yml` — stack, framework, test runner
+- `.forge/state/milestone-{id}.yml` — milestone cursor
+- `.forge/testing/suite-health.md` — prior analyst findings (if exists)
+- `.forge/constitution.md` — active gates (if present)
+
+## Downstream Output
+
+### Author mode
+
+- Committed test files under project test dirs per stack conventions
+- Optional `.forge/testing/notes.md` — rationale for non-obvious choices
+- Atomic commits per executor rules. Format: `test({scope}): {desc}` or `feat({scope}): {desc}` for TDD green step
+
+### Analyst mode
+
+One fenced YAML block, schema below. Plus two side-effect artifacts.
+
+```yaml
+suite_audit:
+  files_scanned: N
+  layers:
+    unit: N
+    integration: N
+    e2e: N
+  runners: ["playwright", "vitest"]
+  findings:
+    - category: flake | coverage_gap | anti_pattern | quarantine_candidate | ci_gap
+      file: "e2e/login.spec.ts"
+      lines: "42-58"
+      severity: critical | warning | info
+      issue: "Hardcoded waitFor(5000) masks race in auth redirect"
+      suggested_approach: "Replace with Playwright auto-wait locator; use page.waitForURL()"
+      effort: quick | standard
+  quarantined:
+    - test: "e2e/checkout.spec.ts:mobile viewport"
+      reason: "Flakes on CI, passes locally"
+      fix_plan: "Seed viewport fixture"
+```
+
+Side effects (analyst only):
+- Writes `.forge/testing/suite-health.md` — narrative findings, per-layer breakdown, quarantine list, fix plans
+- Appends each actionable `finding` to `.forge/refactor-backlog.yml` with fields `id, milestone, category, file, lines, description, effort, suggested_approach, status: pending, added: {date}`
+
+Schema canonical source: `.claude/skills/testing/SKILL.md`. Do not invent fields.
+
+## Process
+
+### Author mode
+
+1. **Read context** — project.yml (stack, runner), scope paths, milestone state.
+2. **Select framework** — Playwright for web/TS e2e; stack runner for integration (Vitest/Jest/pytest/go test). No Playwright on non-web. Match existing project conventions if present.
+3. **Scaffold tests** — follow flake-resistant rules below. Use page fixtures, data-testid, seeded state.
+4. **Run** — execute tests. TDD: red → green → refactor. Non-TDD: write → run → green.
+5. **Commit atomically** — one test file per commit where practical. Follow executor deviation rules 1-4.
+
+### Analyst mode
+
+1. **Scan suite** — count test files per layer (unit/integration/e2e), identify runners, catalog config files.
+2. **Grep anti-patterns** — targets:
+   - `sleep\|setTimeout\|waitFor\([0-9]` — hardcoded waits
+   - `\.btn-\|#[a-z]*Btn\|\.class-selector` — fragile selectors (expect data-testid)
+   - Unseeded DB state (ordering dependencies, shared fixtures)
+   - Missing `trace: 'retain-on-failure'` in Playwright config
+3. **Spot flakes** — run suite with trace + retry configs; record non-deterministic failures.
+4. **Check CI presence** — parse `.github/workflows/*`, grep for runner invocations (`playwright test`, `vitest`, `pytest`, `go test`). Flag non-blocking warning if scoped runner absent.
+5. **Write suite-health.md** — narrative: per-layer counts, anti-pattern hit list, quarantine candidates, fix plans.
+6. **Append to refactor-backlog.yml** — each actionable finding as a backlog item. `effort: quick` for single-file/config fixes, `standard` for multi-file or architectural.
+7. **Emit YAML** — one fenced `suite_audit:` block. No prose outside.
+
+## Flake-Resistant Rules (Author Mode)
+
+Baked rules. Author mode follows all. Violations = rework.
+
+1. **Auto-wait only** — no `sleep`, no `setTimeout`, no hardcoded `waitFor(5000)`. Playwright locators auto-wait; use `page.getByTestId('x').click()` and let it wait.
+2. **Page fixtures** — one `page` per test via Playwright fixtures. No shared page across tests. No module-scoped browser state leaking between specs.
+3. **data-testid locators** — prefer `page.getByTestId('submit')` over CSS (`.btn-primary`) or text (`getByText('Submit')`). Text locators only when copy is stable + unambiguous.
+4. **Seeded state per test** — each test seeds its own DB/fixture state. No ordering dependencies. No "run in order" suites. Teardown restores clean slate.
+5. **Trace on failure** — Playwright config: `trace: 'retain-on-failure'`. Artifacts captured automatically. No "retry until pass" masking flakes.
+6. **Retry once, then quarantine** — if a test fails twice in CI, mark `test.fixme('flaky: {reason}, fix in {ticket}')` with comment. Note in `.forge/testing/suite-health.md` with fix plan. Never infinite-retry.
+
+## Success Criteria
+
+### Author mode
+- [ ] Mode respected — no audit output, no YAML emission
+- [ ] Tool boundaries respected — writes only inside project test dirs
+- [ ] Flake rules followed — no `sleep`, no hardcoded waits, data-testid used, page fixtures per test, trace config set
+- [ ] Tests pass locally before commit
+- [ ] Atomic commits per executor format
+
+### Analyst mode
+- [ ] Mode respected — zero writes to source, zero edits to test files
+- [ ] One fenced `suite_audit:` YAML block emitted
+- [ ] `.forge/testing/suite-health.md` written (narrative + quarantine list)
+- [ ] Actionable findings appended to `.forge/refactor-backlog.yml` with required fields
+- [ ] Schema fields exact — no inventions, no renames
+
+## Anti-Patterns
+
+| Anti-Pattern | Mode | Why it's wrong |
+|--------------|------|----------------|
+| Writing source during audit | analyst | Read-only gate; fixes go through backlog + quick-tasking |
+| `sleep(1000)` or hardcoded waits | author | Masks race, creates flake |
+| Rubber-stamping suite as healthy | analyst | Defeats audit; real suites have findings |
+| Inventing YAML fields | analyst | Breaks testing skill aggregation |
+| Severity inflation / backlog spam | analyst | Degrades signal; reviewer bar applies |
+| Auto-fixing analyst findings | analyst | Violates deferred decision: no auto-queue analyst → author |
+| Shared page across tests | author | Leaks state; breaks test isolation |
+| CSS-selector locators over data-testid | author | Fragile; breaks on style refactor |
+| "Retry until pass" in CI | author | Hides flake; prefer quarantine |
+| Self-switching modes mid-run | either | Mode is set at spawn; exit cleanly and let skill re-spawn |

package/template/.claude/skills/discussing/SKILL.md

@@ -17,9 +17,9 @@ Structured conversation: approach, trade-offs, decisions. Clarity, not artifacts
 
 ## Boundaries
 
-- No plans, code, or `.forge/` writes
+- No plans or code
+- Writes only `context.md` (at convergence, before handoff)
 - No phase/plan required
-- Only output: conversation + decision summary next skill honors
 
 ## Pre-Planning Discussion
 
@@ -91,21 +91,15 @@ Open-ended via prose: *"Tried before?" / "Must-haves or must-nots?"* 1-2 at a ti
 
 ### Step 4: Functionality Distillation
 
-Per feature, force behavioral clarity. Surface assumptions + edge cases. **Five layers:**
+Per feature, force behavioral clarity. Surface assumptions + edge cases.
 
-| Layer | Focus | When to use |
-|-------|-------|-------------|
-| 1. Happy Path | What success looks like step by step | Always |
-| 2. Boundaries & Rules | Permissions, limits, triggers, preconditions | Anything with rules |
-| 3. Failure Modes | Invalid input, service down, cancellation, concurrency | Critical paths (payments, data mutations, auth, integrations) |
-| 4. Interactions & Side Effects | Cascading updates, notifications, undo, related features | Features with shared state or dependencies |
-| 5. Evolution | v1 vs. final shape, scope cuts, likely future changes | Uncertain scope |
+**L1 (Happy Path):** *"See first?" / "Sequence?" / "Confirms success?"*
+**L2 (Rules):** *"Who can?" / "Limits?" / "Trigger type?"*
+**L3 (Failures):** *"Invalid/down/cancel?" / "Retry/fail/alert?" / "Concurrent?"*
+**L4 (Side Effects):** *"Else updates?" / "Notify?" / "Undo?"*
+**L5 (Evolution):** *"v1 or final?" / "Essential vs nice-to-have?"*
 
-**L1:** *"See first?" / "Sequence?" / "Confirms success?"*
-**L2:** *"Who can?" / "Limits?" / "Trigger type?"*
-**L3:** *"Invalid/down/cancel?" / "Retry/fail/alert?" / "Concurrent?"*
-**L4:** *"Else updates?" / "Notify?" / "Undo?"*
-**L5:** *"v1 or final?" / "Essential vs nice-to-have?"*
+**Listen for:** Contradictions ("Simple" + "12 states"), Vague ("Just work" → push for example), Assumed knowledge ("Like Stripe" → confirm specifics), Energy shifts (excitement/boredom = signal).
 
 Not all 5 mechanically. 2-3 questions, deeper on uncertainty. `AskUserQuestion` for discrete; prose to explain.
 
@@ -122,12 +116,6 @@ options:
     description: "Process remaining items, revisit failures in next sweep."
 ```
 
-**Listen for:**
-- **Contradictions** -- "Simple" + "12 states." Surface.
-- **Vague** -- "Just work." Push for example.
-- **Assumed knowledge** -- "Like Stripe." Confirm specifics.
-- **Energy shifts** -- Excitement/boredom = signal.
-
 ### Step 5: Converge
 
 Summarize decided items, then confirm:
@@ -144,7 +132,7 @@ options:
     description: "Topics we haven't covered yet."
 ```
 
-Decisions flow into `context.md` as **Locked Decisions** at planning.
+Decisions written to `.forge/context.md` at Phase Handoff (below).
 
 ## Post-Planning Discussion
 
@@ -235,8 +223,13 @@ Re-plan? Route to `planning` with summary.
 
 After convergence:
 
-1. **Persist** -- Step 5/6 summary flows into `context.md` at planning. Post-planning revisions noted.
+1. **Write `context.md`** -- Create/update `.forge/context.md` from template (`.forge/templates/context.md`). Populate:
+   - **Locked Decisions**: all confirmed decisions from Steps 1-5
+   - **Deferred Ideas**: anything explicitly deferred
+   - **Discretion Areas**: topics left to agent judgment
+   - **Needs Resolution**: unresolved items (if any)
+   - If `context.md` already exists (post-planning discussion), update relevant sections + log amendments
 2. **Update state** -- `current.status` = `planning` (`architecting` for Full) in milestone yml
 3. **Recommend clear:**
 
-*"Decisions captured. State written. `/clear` then `/forge` to continue with {planning/architecting}."*
+*"Decisions written to `.forge/context.md`. State updated. `/clear` then `/forge` to continue with {planning/architecting}."*

package/template/.claude/skills/executing/SKILL.md

@@ -13,19 +13,9 @@ description: "Build to plan with atomic commits, deviation rules, and context en
 
 ## Deviation Rules
 
-### Rule 4 Check First (Architectural)
-New DB table, service layer, schema change, library swap, or infra change?
-- **YES** → **STOP.** Checkpoint: what, proposed change, why, impact, alternatives. Wait for user.
-- **NO** → Continue to Rules 1-3.
+**Full definitions:** `.claude/agents/executor.md`. Decision order: **Rule 4 first** (architectural → STOP, ask user), then Rule 1 (bugs), Rule 2 (critical gaps), Rule 3 (infra blockers). Uncertain → Rule 4.
 
-### Rule 1: Auto-Fix Bugs
-Bug blocking current task → Fix inline. Add test if applicable. Document: "Rule 1: Fixed [bug] because [reason]."
-
-### Rule 2: Auto-Add Critical Functionality
-Missing error handling, validation, null checks, auth, CSRF, rate limiting, logging → Add it. Document: "Rule 2: Added [what] because [reason]."
-
-### Rule 3: Auto-Fix Blocking Infrastructure
-Missing dep, wrong types, broken imports, env var, build config → Fix it. Document: "Rule 3: Fixed [issue] because [reason]."
+Execution-phase operational guidance below supplements the rules — it does not redefine them.
 
 ### 3-Strike Limit
 3 auto-fix attempts on a single task → STOP. Document remaining issues. Move to next task.

package/template/.claude/skills/forge/SKILL.md

@@ -79,9 +79,9 @@ Tier + state → invoke via `Skill` tool.
 
 **CRITICAL: NEVER `EnterPlanMode`.** "Planning" = `Skill(planning)`. Native plan mode writes wrong format, bypasses gates + state.
 
-### Mandatory Auto-Routing on Resume
+### Auto-Routing (Always Deterministic)
 
-**No menus.** Deterministic. Brief → route. Choices only at `complete` or corrupted.
+**No menus.** Applies on first run and resume. Deterministic. Brief → route. Choices only at `complete` or corrupted.
 
 1. Read `milestone-{id}.yml` → 2. Check advancement → 3. `current.status` → skill → 4. Brief + route:
 
@@ -121,7 +121,6 @@ Subagents via `Task` → same precedence.
 | `reviewing` | `Skill(reviewing)` → complete |
 | `complete` | Done. Ask what's next. |
 
-- 100% tasks != complete -- verification + reviewing must run.
 - Skip before `current.status`; resume current.
 
 ### Status Advancement Check
@@ -148,27 +147,12 @@ Sessions end before advancement. On resume detect + fix:
 
 ## Deviation Rules (All Tiers)
 
-| Situation | Action | Rule |
-|-----------|--------|------|
-| Bug blocking task | Auto-fix, document | 1 |
-| Missing validation/error handling/null checks | Auto-add, document | 2 |
-| Broken import/dep/config | Auto-fix, document | 3 |
-| New DB table, service layer, library swap | **STOP. Ask user.** | 4 |
-| After verifying passes | Health + refactoring audit | `reviewing` |
-| Model routing mismatch | Flag expensive models for mechanical tasks | `reviewing` |
-
-Uncertain → 4. Never silently make arch decisions.
+See CLAUDE.md § Deviation Rules (always loaded) or `.claude/agents/executor.md` for full definitions. Uncertain → Rule 4.
 
 ## Context Handoff Protocol
 
 Phase transitions = clear boundaries. **Recommend `/clear`** after writing state. Next phase reads disk artifacts, not working memory.
 
-Standard/Full:
-
-```
-researching → [clear] → discussing → [clear] → architecting → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → reviewing
-```
-
 **Skip:** Quick, short phase + context <40%, user opted out.
 
 ### Handoff Pattern
@@ -182,8 +166,8 @@ researching → [clear] → discussing → [clear] → architecting → [clear]
 
 | Phase | Writes | Read By |
 |-------|--------|---------|
-| researching | Research summary | discussing |
-| discussing | Decisions → context.md | planning |
+| researching | `.forge/research/milestone-{id}.md` | discussing |
+| discussing | `.forge/context.md` (locked decisions, deferrals, discretion) | planning |
 | architecting | ADRs, data models, API contracts | planning |
 | planning | `.forge/phases/m{M}-{N}-{name}/`, requirements.yml, roadmap.yml | executing |
 | executing | Committed code, execution summary, state | verifying |
@@ -196,10 +180,11 @@ After clear, skills load from disk via "Read Context"/"Pre-Execution Checklist".
 ## State Transitions
 
 ```
-not_started → [init if new] → researching → [clear] → discussing → [clear] → planning → [clear] → executing → [clear] → verifying → [clear] → reviewing → complete
-                                                                                                    ↗ debugging (if stuck)
-                                                                                          ↗ designing (if UI)
-                                                                                          ↗ securing (if auth/data)
+Standard: not_started → [init?] → researching → discussing → planning → executing → verifying → reviewing → complete
+Full:     not_started → [init?] → researching → discussing → architecting → planning → executing → verifying → reviewing → complete
+
+Branches (any tier, on-demand): debugging (stuck) · designing (UI) · securing (auth/data/API)
+Phase boundaries: `[clear]` recommended between phases to reset context.
 ```
 
 Update `milestone-{id}.yml` + `index.yml` `last_updated` at each transition.

package/template/.claude/skills/initializing/SKILL.md

@@ -94,6 +94,8 @@ Check: Any structured agent/workflow system
 | `extensions/` | Specialized skills | `.claude/skills/` (if relevant) |
 | Project specs (if filled in) | Locked decisions | `.forge/context.md` |
 
+**BMAD:** No dedicated absorption table. Use Generic path.
+
 **Generic:** `researching` reads all markdown/config, maps to Forge equivalents, confirms with user.
 
 **Process:** Read sources → synthesize per target → prose to YAML where expected, keep markdown where expected → unmapped to `.forge/context.md` "Carried Forward" → originals to `.forge/archive/{name}/` → show summary. Then continue brownfield steps.

package/template/.claude/skills/researching/SKILL.md

@@ -83,7 +83,9 @@ For independent topics, research simultaneously:
 
 Never research sequentially when topics are independent.
 
-## Output Template
+## Finding Format
+
+Canonical schema for research output. Used both for in-conversation summaries and the persisted artifact (see Research Artifact below).
 
 ```markdown
 # Research: [Topic]
@@ -95,6 +97,9 @@ Never research sequentially when topics are independent.
 1. [Finding] — Confidence: HIGH/MEDIUM/LOW — Source: [source]
 2. [Finding] — Confidence: HIGH/MEDIUM/LOW — Source: [source]
 
+## Ruled Out
+- [approach]: [reason rejected]
+
 ## Recommendations
 - [Recommended approach with rationale]
 
@@ -110,9 +115,15 @@ Never research sequentially when topics are independent.
 
 Research output under 500 lines. If larger, split into focused documents: `research-codebase.md`, `research-tech.md`, `research-requirements.md`.
 
+## Research Artifact
+
+Always write `.forge/research/milestone-{id}.md` at phase end. Create directory if needed. Immutable after writing — dated snapshot, never updated. Re-research if stale.
+
+Artifact uses the Finding Format above, with two adjustments: prepend `Date: {YYYY-MM-DD}` below the title, and omit the Sources section (URLs are ephemeral).
+
 ## Phase Handoff
 
-1. **Persist findings** — Write research summary to `.forge/phases/m{M}-{N}-{name}/` or present inline. Standard tier: inline is fine. Full tier with multiple topics: write to files.
+1. **Write artifact** (see Research Artifact section above).
 2. **Update state** — Set `current.status` to `discussing` in `.forge/state/milestone-{id}.yml`
 3. **Recommend context clear:**
 

package/template/.claude/skills/testing/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: testing
+description: "Write e2e/integration tests OR audit existing suite health. Triggers: UI flows needing browser coverage, flaky suite cleanup, coverage-gap investigation, missing test infra scaffolding. Scope: e2e + integration only — unit tests stay with executing TDD flow. Playwright for web/TS e2e; stack-aware runner (Vitest/Jest/pytest/go test) for integration. Inherits verifying gate — does not run own verification."
+---
+
+# Testing
+
+On-demand branch skill. Peer of `designing`, `securing`, `debugging`. Not in core pipeline — invoked when testing work needed.
+
+**Scope boundary:** e2e + integration layers only. Unit tests belong to `executing` TDD flow. No overlap.
+
+## Step 1: Determine Mode
+
+Three modes:
+
+- **analyst** — audit existing suite. Spawns tester (analyst). Output: `suite-health.md` + refactor-backlog appends. **Brownfield default.**
+- **author** — write new tests (e2e or integration). Spawns tester (author). Output: committed test files.
+- **ci-check** — grep CI workflows for test runner invocations. No agent spawn — skill runs directly.
+
+### Intent Inference
+
+| User says | Mode |
+|-----------|------|
+| "audit tests" / "suite health" / "find flakes" / "test quality" | analyst |
+| "write e2e" / "add tests for X" / "scaffold Playwright" / "integration tests" | author |
+| "does CI run tests" / "CI integration" / "test pipeline" | ci-check |
+
+Ambiguous → ask. Brownfield project + no mode specified → default analyst.
+
+## Step 2: Read Project Context
+
+```
+Read: .forge/project.yml → stack, framework, test runner, verification commands
+Read: .forge/state/milestone-{id}.yml → current milestone
+Read: .forge/testing/suite-health.md → prior audit findings (if exists)
+Read: .github/workflows/* → CI config (ci-check mode, analyst CI sub-check)
+```
+
+## Step 3: Mode Flows
+
+### Analyst Mode
+
+1. Spawn tester agent via Agent tool, mode = `analyst`:
+   - Pass: milestone id + name, scope paths, stack summary from project.yml
+   - Agent scans test files, runs suite with traces/retries, greps anti-patterns
+2. Agent writes `.forge/testing/suite-health.md`:
+   - **Coverage Gaps** — untested surfaces, missing layers
+   - **Flake Candidates** — tests that failed-then-passed, use `sleep`/hardcoded waits
+   - **Anti-Patterns** — non-`data-testid` selectors, unseeded state, missing fixtures, no trace config
+   - **Quarantine Queue** — tests recommended for `test.fixme()` with reason + fix plan
+3. Agent appends actionable items to `.forge/refactor-backlog.yml`:
+   ```yaml
+   - id: T-{NNN}
+     source: testing-analyst
+     date: YYYY-MM-DD
+     category: flake | coverage-gap | anti-pattern | quarantine
+     file: "path/to/test.spec.ts"
+     lines: "NN-NN"
+     description: "What's wrong"
+     effort: quick | standard
+     suggested_approach: "How to fix"
+     status: pending
+   ```
+   ID numbering: read existing backlog, find max T-NNN, increment. No gaps.
+4. Receive agent YAML output (`suite_audit:` block). Review for completeness.
+
+### Author Mode
+
+1. **Determine layer** — e2e vs integration. Ask if ambiguous.
+2. **Select runner:**
+   - e2e + web/TS → **Playwright** (only option v1 — non-web e2e deferred)
+   - integration → read `project.yml` stack:
+     - `js` / `ts` → Vitest or Jest (match existing project runner)
+     - `python` → pytest
+     - `go` → go test
+     - `java` → JUnit
+   - If project has existing test runner, match it. Don't introduce a second.
+3. Spawn tester agent via Agent tool, mode = `author`:
+   - Pass: milestone id + name, layer, runner, scope paths, stack summary
+   - Agent scaffolds tests following baked flake-resistant rules (see tester.md)
+4. Agent commits atomically per executor conventions.
+
+### CI-Check Mode
+
+No agent spawn. Skill runs directly.
+
+1. **Detect CI provider:**
+   - `.github/workflows/*.yml` → GH Actions (supported v1)
+   - `.circleci/`, `.gitlab-ci.yml`, `Jenkinsfile` → not supported v1. Report: *"Non-GH CI detected, verify test integration manually."*
+2. **For GH Actions** — grep workflow files for runner invocations:
+   ```
+   playwright test | npx playwright | vitest | jest | pytest | go test
+   ```
+3. **Report:**
+   - Runner references found → OK, list which runners + which workflows
+   - E2e suite exists locally but no `playwright test` in workflows → **warn** (non-blocking): *"E2e suite not wired to CI."*
+   - No test runner referenced at all → **warn**: *"No test runner found in CI workflows."*
+4. Warnings are non-blocking. Surface to user, don't gate.
+
+## Step 4: Quarantine Convention
+
+When analyst or author recommends quarantining a flaky test:
+
+1. Mark with `test.fixme('reason', async () => { ... })` — Playwright/Vitest pattern
+2. Comment above: `// Quarantined YYYY-MM-DD — see .forge/testing/suite-health.md`
+3. Add entry to suite-health.md Quarantine Queue: test path | reason | fix plan | owner
+4. **Fix plan required** — quarantine without fix plan = anti-pattern. Temporary only.
+
+## Step 5: Gate Inheritance
+
+Testing skill does **NOT** run its own verification gate. Committed tests flow through `verifying` skill's existing `project.yml` verification commands (`npm test`, `npx playwright test`, etc.).
+
+If verification commands need updating to include new test layers → surface as refactor item for user. Do not silently modify `project.yml`.
+
+## Step 6: Output Checklist
+
+- [ ] Mode determined + user-confirmed if ambiguous
+- [ ] Agent spawned with correct mode flag (analyst or author) OR skill ran ci-check directly
+- [ ] **Analyst:** suite-health.md written + refactor-backlog appended
+- [ ] **Author:** tests committed, flake-resistant rules followed
+- [ ] **CI-check:** warnings surfaced, non-blocking
+- [ ] No independent verification invoked — defer to `verifying` skill

package/template/CLAUDE.md

@@ -125,7 +125,8 @@ State lives in `.forge/`:
 - `state/index.yml` — Global: active milestones, desire_paths, metrics
 - `state/milestone-{id}.yml` — Per-milestone cursor: position, progress, decisions, blockers
 - `context.md` — Locked decisions + deferred ideas (discuss phase)
-- `plan.md` — Task plans with must_haves frontmatter
+- `research/milestone-{id}.md` — Research findings snapshot (dated, immutable)
+- `phases/m{M}-{N}-{name}/plan-{NN}.md` — Task plans with must_haves frontmatter
 - `refactor-backlog.yml` — Refactoring catalog, worked via quick-tasking
 
 **Milestones** group phases into concurrent streams. Own state file — no conflicts across sessions.
@@ -134,10 +135,14 @@ State lives in `.forge/`:
 
 ## Deviation Rules
 
-1. **Bug blocking task** → Auto-fix. Document "Rule 1."
-2. **Missing critical functionality** (error handling, validation, auth, null checks) → Auto-add. "Rule 2."
-3. **Blocking infrastructure** (missing dep, wrong types, broken imports) → Auto-fix. "Rule 3."
-4. **Architectural change** (new DB table, service layer, library switch) → **STOP. Ask user.** "Rule 4."
+**Full definitions:** `.claude/agents/executor.md`.
+
+| Situation | Action | Rule |
+|-----------|--------|------|
+| Bug blocking task | Auto-fix, document | 1 |
+| Missing validation/error handling/null checks | Auto-add, document | 2 |
+| Broken import/dep/config | Auto-fix, document | 3 |
+| New DB table, service layer, library swap | **STOP. Ask user.** | 4 |
 
 Priority: Rule 4 first. Then 1-3. Uncertain → Rule 4.