forge-orkes 0.3.19 → 0.3.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-orkes",
-  "version": "0.3.19",
+  "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/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
 
@@ -132,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
 
@@ -223,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/forge/SKILL.md

@@ -167,7 +167,7 @@ Phase transitions = clear boundaries. **Recommend `/clear`** after writing state
 | Phase | Writes | Read By |
 |-------|--------|---------|
 | researching | `.forge/research/milestone-{id}.md` | discussing |
-| discussing | Decisions → context.md | planning |
+| 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 |

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