docs: implement spec — L1 reframing, new patterns, Playwright, adoption guide

- Reframe L1 as "Closed Loop Design and Verification" with context harvesting
  and REPL fractal loop concept; split into overview + 7 sub-docs in L1-patterns/
- Add Pattern 2.6 (Enforcement Pipeline Composition), 2.7 (Phase Transition
  Validation), 3.8 (Session Lifecycle), 4.5 (CI Guardrails)
- Extend TS stack-test example with Playwright browser tests (2 test files)
- Slim migration-guide (1500 lines) to adoption-guide (145 lines)
- Add L4 scope note disclaimer; reference implementations point to rig
- Rename all claude-stack-utils references to rig
- Fix all markdownlint errors (36 files, 0 errors including specs/)
- Fix broken links in L0, L3, examples (guardrails, TS README)
- Add specs/, glossary entries, FAQ, .claude/skills/

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: franklywatson

.claude/skills/brain-plus/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: brain+
+description: "Invoke BEFORE any design or feature work. Wraps superpowers:brainstorming with scout agent context harvesting, stack-first design considerations, and constitutional rule awareness. Asks questions one at a time to refine the design."
+argument-hint: "[feature description]"
+user-invocable: true
+---
+
+# brain+ — Context-Aware Design
+
+Wraps `superpowers:brainstorming`. Requires superpowers to be installed.
+
+## Before You Begin
+
+Invoke this skill BEFORE starting any design work. It adds three capabilities on top of the base brainstorming skill:
+
+1. **Scout context** — automatically harvests codebase context
+2. **Stack-first design** — considers Docker, test infrastructure, and full-loop verification
+3. **Constitutional awareness** — loads project rules from CLAUDE.md
+
+## Procedure
+
+### Phase A: Harvest Context
+
+1. Invoke the scout agent to map the current codebase:
+
+   ```
+   Agent(subagent_type="scout", prompt="Map the codebase structure for [feature area]. Focus on: existing patterns, related modules, test infrastructure, and entry points relevant to [feature].")
+   ```
+
+2. Read the project's CLAUDE.md for constitutional rules.
+
+3. Identify:
+   - Existing patterns this feature should follow
+   - Test infrastructure available (vitest, pytest, stack tests)
+   - Modules that will be affected
+   - Components that must NOT be mocked (constitutional rules)
+
+### Phase B: Design (delegate to superpowers:brainstorming)
+
+1. Invoke `superpowers:brainstorming` with the enriched context.
+
+2. During brainstorming, add these stack-first considerations:
+   - What Docker services does this feature need?
+   - What are the full-loop assertions? (primary + second-order + third-order effects)
+   - What test utilities need to exist before implementation?
+   - Which components are protected from mocking?
+
+3. Use positive framing in all design guidance:
+   - "Use real database connections in tests" (not "don't mock the database")
+   - "Write assertions that verify observable behavior" (not "don't test implementation details")
+   - "Show command output before claiming done" (not "don't say tests pass without evidence")
+
+### Phase C: Validate
+
+1. Confirm the design addresses:
+   - [ ] Feature purpose and scope
+   - [ ] Affected modules identified
+   - [ ] Testing strategy defined
+   - [ ] Constitutional rules acknowledged
+   - [ ] No mocks for protected components
+   - [ ] Stack test user journey defined (if applicable)
+
+## Output
+
+Return the validated design with testing strategy to feed into `plan+`.
+
+## Skill Chain
+
+After completing brain+, the next step is:
+
+- Invoke `/plan+` to create the implementation plan from this design

.claude/skills/plan-plus/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: plan+
+description: "Invoke AFTER brain+ design is approved. Wraps superpowers:writing-plans with constitutional rules, testing strategy per task, and mock policy. Creates bite-sized implementation plans."
+argument-hint: "[plan description]"
+user-invocable: true
+---
+
+# plan+ — Disciplined Planning
+
+Wraps `superpowers:writing-plans`. Requires superpowers to be installed.
+
+## Before You Begin
+
+This skill runs after `brain+` has produced a validated design. It creates the implementation plan with testing discipline baked into every task.
+
+## Procedure
+
+### Phase A: Load Context
+
+1. Read the design output from `brain+` (from the current session or saved spec).
+
+2. Load constitutional rules from CLAUDE.md. Add a **Constitutional Compliance** section to the plan:
+
+   ```
+   ## Constitutional Rules for This Plan
+   - Use real [database/payment/logger] connections — never mock protected components
+   - Show command output before claiming done
+   - Every source file change requires corresponding test changes
+   - Full-loop assertions: verify primary + second-order + third-order effects
+   ```
+
+3. Identify the mock policy for this plan:
+
+   ```
+   ## Mock Policy
+   Protected (never mock): [list from constitutional rules]
+   Allowed: [external third-party services not yet containerized]
+   ```
+
+### Phase B: Create Plan (delegate to superpowers:writing-plans)
+
+1. Invoke `superpowers:writing-plans` with the enriched context.
+
+2. For each task in the plan, ensure it includes:
+   - **Test strategy**: which tests cover this task's requirements
+   - **Mock check**: does this task need to interact with protected components?
+   - **Evidence criteria**: what output proves this task is done
+
+3. Every task must follow the pattern:
+
+   ```
+   ### Task N: [Name]
+   **Files:** [exact paths]
+   **Test strategy:** [which tests, scoped to this task]
+   **Mock check:** [are protected components involved?]
+   - [ ] Step 1: Write failing test
+   - [ ] Step 2: Verify it fails
+   - [ ] Step 3: Write minimal implementation
+   - [ ] Step 4: Verify it passes
+   - [ ] Step 5: Commit
+   ```
+
+### Phase C: Validate Plan
+
+1. Confirm the plan:
+   - [ ] Every task has a test strategy
+   - [ ] No task mocks a protected component
+   - [ ] Plan references exact file paths (no TBDs)
+   - [ ] Evidence criteria defined for each task
+   - [ ] Constitutional rules section present
+
+## Output
+
+Save the plan to `docs/plans/` and feed into `tdd+` for implementation.
+
+## Skill Chain
+
+After completing plan+, the next step is:
+
+- Invoke `/tdd+` to implement the plan task-by-task with RED-GREEN-REFACTOR

.claude/skills/review-plus/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: review+
+description: "Invoke AFTER verify+ passes. Wraps superpowers:requesting-code-review with constitutional compliance checklist, stale test validation, and reviewer agent invocation. Two-stage review: spec compliance + code quality."
+argument-hint: "[plan file path]"
+user-invocable: true
+---
+
+# review+ — Compliance Review
+
+Wraps `superpowers:requesting-code-review`. Requires superpowers to be installed.
+
+## Procedure
+
+### Phase A: Gather Review Context
+
+1. Load the plan from `docs/plans/`.
+
+2. Get the list of files changed since the plan was created:
+
+   ```
+   git diff --name-only [plan-commit]..HEAD
+   ```
+
+3. Invoke the scout agent to get current codebase state for comparison:
+
+   ```
+   Agent(subagent_type="scout", prompt="Get current state of these files: [changed files list]. For each file, report: symbol count, key exports, test coverage status.")
+   ```
+
+### Phase B: Spec Compliance Review
+
+1. For each task in the plan:
+   - Check: was the task implemented? (file exists, code present)
+   - Check: does the implementation match the plan's specification?
+   - Check: are the specified tests present and passing?
+   - Check: were any plan tasks skipped or significantly changed?
+
+2. Check stale test status:
+   - For each changed source file, verify a corresponding test file was also changed
+   - Flag any source edits without test updates as stale test violations
+
+3. Check constitutional compliance:
+   - [ ] No protected components are mocked in any test file
+   - [ ] All claims of success are backed by command output
+   - [ ] Full-loop assertions present where applicable
+   - [ ] No conditional test assertions (`if (condition) assert(...)`)
+   - [ ] No empty test bodies
+   - No `.skip` without documented reason
+
+### Phase C: Code Quality Review (delegate to superpowers:requesting-code-review)
+
+1. Invoke `superpowers:requesting-code-review` with the gathered context.
+
+2. Check code quality:
+   - Files are focused (one clear responsibility per file)
+   - Interfaces are well-defined
+   - No unnecessary abstractions
+   - No speculative generalization
+   - Positive framing in code comments and error messages
+
+### Phase D: Review Report
+
+1. Produce a two-stage review report:
+
+   ```
+   ## Review Report
+
+   ### Stage 1: Spec Compliance
+   - [ ] All plan tasks implemented
+   - [ ] Implementation matches plan specification
+   - [ ] No stale test violations
+   - [ ] Constitutional rules followed
+
+   ### Stage 2: Code Quality
+   - [ ] Files are focused and well-structured
+   - [ ] Interfaces are clean
+   - [ ] No unnecessary complexity
+   - [ ] Positive framing throughout
+
+   ### Verdict
+   PASS / FAIL with specific items to address
+   ```
+
+2. If PASS: the implementation is complete. Proceed to integration.
+    If FAIL: list specific items, return to tdd+ to fix, then re-run verify+ and review+.
+
+## Skill Chain
+
+After review+ passes:
+
+- The implementation is complete
+- Proceed to merge/PR decision (superpowers:finishing-a-development-branch)

.claude/skills/savings/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: savings
+description: "Report rtk and jcodemunch token savings for the current session."
+argument-hint: ""
+user-invocable: true
+---
+
+# savings — Session Savings Report
+
+Report token savings from rtk and jcodemunch usage during this session.
+
+## Procedure
+
+1. Run `rtk gain --format json` to get current savings data. If rtk is not
+   available, skip rtk reporting.
+2. Run `cat .rig-session.json 2>/dev/null` to read the session baseline and
+   counters written by the hooks. If the file does not exist, report all-time
+   totals instead of session deltas.
+3. Compute the session delta: `current total_saved - baseline totalSaved`.
+4. Format and print the report (see Output Format below). Do NOT write any
+   explanatory text before or after the report — output ONLY the report lines.
+
+## Output Format
+
+With session data (baseline + delta available):
+
+```
+[rig] Session Savings
+  rtk: 6.4M saved (42 calls, +340K this session)
+  jcodemunch: 28 queries
+```
+
+Without session data (all-time totals only):
+
+```
+[rig] Session Savings (all-time)
+  rtk: 6.4M saved (3114 commands, 9.0% avg savings)
+```
+
+If rtk is not installed:
+
+```
+[rig] Session Savings
+  rtk: not installed
+```
+
+## Formatting Rules
+
+- Format token counts: >=1M as `X.XM`, >=1K as `XK`, else raw number.
+- Round percentages to 1 decimal.
+- Output the report and nothing else.

.claude/skills/tdd-plus/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: tdd+
+description: "Invoke AFTER plan+ is approved. Wraps superpowers:test-driven-development with full-loop assertions, no-mock enforcement, zero-defect, stale test detection, and scoped test runs. Implements plan tasks with RED-GREEN-REFACTOR discipline."
+argument-hint: "[plan file path or task range]"
+user-invocable: true
+---
+
+# tdd+ — Disciplined Implementation
+
+Wraps `superpowers:test-driven-development`. Requires superpowers to be installed.
+
+**This skill activates tdd+ phase in the enforcement layer.** During this phase:
+
+- Full test suite runs are redirected (use scoped tests only)
+- Stale test warnings fire when source edits lack test updates
+- Constitutional no-mock rules are enforced
+
+## Procedure
+
+### Phase A: Setup
+
+1. Announce phase entry:
+
+   ```
+   Now using tdd+ skill. Enforcement layer active:
+   - Test scope: scoped runs only (full suite reserved for verify+)
+   - Stale tests: warnings when source edited without test updates
+   - Zero-defect: every failure must be fixed before proceeding
+   ```
+
+2. Load the plan from `docs/plans/`.
+
+3. Identify the task(s) to implement.
+
+### Phase B: Implement Each Task (delegate to superpowers:test-driven-development)
+
+1. For each task in the plan, follow RED-GREEN-REFACTOR:
+
+   **RED — Write the failing test first:**
+   - Write a test that captures the task's requirement
+   - Use full-loop assertions where applicable:
+     - Primary: does the function return the expected value?
+     - Second-order: did the side effect occur? (state change, log entry, event)
+     - Third-order: is the system still consistent? (no orphan records, no leaked connections)
+   - Run the test: it MUST fail (if it passes immediately, the test is wrong)
+   - Show the failure output
+
+   **GREEN — Write minimal code to make the test pass:**
+   - Write the smallest possible implementation
+   - Do not add features not in the plan
+   - Run the scoped test: `npx vitest run tests/path/to/specific.test.ts`
+   - Show the passing output
+
+   **REFACTOR — Clean up while tests pass:**
+   - Improve code structure without changing behavior
+   - Run scoped tests after each refactoring step
+   - Commit after each completed task
+
+2. After each source file edit, check:
+   - Was the corresponding test file also updated?
+   - If not, the enforcement layer will emit a stale test warning
+   - Address it before proceeding to the next task
+
+### Phase C: Task Completion
+
+1. After each task, verify:
+   - [ ] Test was written first and shown to fail
+   - [ ] Implementation makes the test pass
+   - [ ] Scoped test run passes (not full suite)
+   - [ ] No constitutional rules violated
+   - [ ] Commit made with descriptive message
+
+2. Proceed to next task or exit tdd+ phase when all plan tasks complete.
+
+## Test Scope Rules
+
+During tdd+ phase, the enforcement layer redirects:
+
+- `npx vitest run` (full suite) → advise to run scoped tests only
+- `pytest` (full suite) → advise to run specific test file
+
+Use scoped commands:
+
+```
+npx vitest run tests/router/resolver.test.ts
+pytest tests/test_config.py::test_load_config
+```
+
+Full suite runs happen during `verify+` phase, not here.
+
+## Skill Chain
+
+After completing all plan tasks with tdd+:
+
+- Invoke `/verify+` to run full suite and verify against plan acceptance criteria