bigpowers 2.92.0 → 2.93.0

package/.gemini/extensions/bigpowers/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.92.0",
+  "version": "2.93.0",
   "description": "80 skills — 73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "keywords": [
     "gemini-extension"

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.92.0",
+  "version": "2.93.0",
   "description": "80 skills — 73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "keywords": [
     "pi-package"

package/AGENTS.md

@@ -0,0 +1,98 @@
+# story: e38s08
+# story: e51s05
+# story: e45s22
+# story: e45s23
+# story: e55s03
+# story: e84s01
+
+# bigpowers — Agent Instructions
+
+Read CONVENTIONS.md before any GitHub or git operation.
+[`constitution.md`](constitution.md) synthesizes this project's doctrine (this file, CONVENTIONS.md, docs/PRINCIPLES.md, docs/references/*.md). This file remains fully authoritative.
+
+<!-- BEGIN bigpowers:context-routing -->
+## Context Routing
+
+Load subdirectory context by file glob — do not read the full doc tree up front.
+
+| Glob / trigger | Load first | Fallback |
+|----------------|------------|----------|
+| `skills/**` | Active skill `SKILL.md` + sibling `REFERENCE.md` | `SKILL-INDEX.md` |
+| `specs/epics/**` | Capsule `epic.yaml` + active story `-tasks.yaml` | `specs/release-plan.yaml` |
+| `specs/product/**` | `SCOPE_LATEST.yaml`, `VISION_LATEST.yaml` | `specs/README.md` |
+| `specs/tech-architecture/**` | `tech-stack.md` + epic `eNN-TEST_PLAN_LATEST.md` | `CONVENTIONS.md` |
+| `scripts/**` | `CONVENTIONS.md` § Generated targets | Commands table below |
+| `website/**` | `website/README.md` | Never edit generated docs in `website/src/content/docs/` |
+| `docs/**` | Matching doc under `docs/` | `docs/references/` |
+| Default / session start | This file → `CONVENTIONS.md` → `specs/state.yaml` | `survey-context` |
+<!-- END bigpowers:context-routing -->
+
+<!-- BEGIN bigpowers:learned-preferences -->
+## Learned User Preferences
+
+- Prefer `rtk`-prefixed shell commands for git, test, and build output (token savings).
+- Run Preflight before forward work; never dismiss red gates as pre-existing.
+- Edit `skills/*/SKILL.md` sources only — never `.cursor/rules/` or `.gemini/` artifacts.
+
+## Workspace Facts
+
+- Stack: Markdown / Bash documentation project; skills sync via `bash scripts/sync-skills.sh`.
+- Planning SoT: `specs/state.yaml`, `specs/release-plan.yaml`, `specs/execution-status.yaml`.
+- Story traceability: `# story: eNNsNN` tags in implementing files; `bash scripts/trace-stories.sh --strict` in CI.
+- Rule matrix: `bash scripts/compile-rule-matrix.sh` → `specs/rule-matrix.json` (P0–P3 tiers from CONVENTIONS.md).
+<!-- END bigpowers:learned-preferences -->
+
+## Project
+
+bigpowers — agent skills for spec-driven, test-first software development by solo developers (catalog in `SKILL-INDEX.md`).
+Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code, Cursor, Gemini CLI)
+
+## Commands
+
+| Action | Command |
+|--------|---------|
+| Install | `npm install -g bigpowers && bigpowers setup` |
+| Run / Lint | `bash scripts/sync-skills.sh` |
+| Test | `npm run compliance` |
+| Build | `bash scripts/install.sh` (from source) |
+| Validate specs YAML | `bash scripts/validate-specs-yaml.sh` |
+| Compliance | `npm run compliance` |
+| Verification Gates | `bash scripts/run-verification-gates.sh` |
+| Traceability | `bash scripts/trace-stories.sh --strict` |
+| Preflight | `npm run compliance && bash scripts/run-verification-gates.sh && bash scripts/sync-skills.sh && bash scripts/trace-stories.sh --strict` |
+| CI | `gh pr checks` |
+
+Pre-merge: `npm run compliance && bash scripts/run-verification-gates.sh`. If BCP Plus sized, see `docs/references/bcp-plus.md`.
+
+## Architecture & Conventions
+
+- Collection of verb-noun skills under `skills/`, each with a single `SKILL.md` source of truth.
+- Runtime specs in `specs/state.yaml`, `specs/release-plan.yaml`, and `specs/execution-status.yaml`; intent in `specs/product/`; epics in `specs/epics/`.
+- Generated targets: `.cursor/rules/`, `.gemini/extensions/bigpowers/`, `.pi/skills/`, and `website/src/content/docs/`. Run `bash scripts/sync-skills.sh` after any changes.
+- **Never** edit generated targets directly. Never create a skill without a `SKILL.md` file. Never push without running `sync-skills.sh`.
+
+## Token Management & Toolchain
+
+- Context discipline: Write (short functions 4-20 lines), Select (`bts map`, `survey-context`), Compress (`sqz compress`, `rtk`), Isolate (`kickoff-branch`, `dispatch-agents`). See `docs/references/context-engineering.md`.
+- Auto-Terse: Switch to `terse-mode` when session exceeds ~20 turns or context is heavy.
+- Context compaction: Summarize state every 10 turns into a short, high-density note.
+- Stream stability: Continuous output in chunks of ~200 lines without pausing.
+- Mechanical backstop (e45s03): `scripts/hooks/token-mgmt-pre-tool-use.sh` blocks oversized tool calls.
+- **Toolchain (bts, sqz, rtk):** Syntax tables, compression rules, MCP tools, and commands live in [docs/references/agent-tooling.md](docs/references/agent-tooling.md).
+  - Search: `bts find --print <pattern>` | Map: `bts map` | Docs: `bts docs <lib>`
+  - Compression: pipe through `sqz compress` (MCP: `sqz_read_file`, `sqz_grep`, `sqz_list_dir`)
+  - RTK: prefix commands with `rtk` (e.g. `rtk git status`, `rtk cargo test`, `rtk gh pr view`)
+
+## Session Start
+
+Before any task, run this sequence — not optional:
+1. Read `CLAUDE.md` (or `AGENTS.md`)
+2. Read `CONVENTIONS.md`
+3. Read `specs/state.yaml` if it exists — current session and active epic
+4. Read `specs/release-plan.yaml` if it exists — active release context
+
+## Agent Rules
+
+- **Workflow Mandate:** You MUST use the bigpowers skills (e.g., `plan-work`, `develop-tdd`, `craft-skill`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
+- **Always Green / fix-or-log:** Preflight and CI must be green before forward work. Any reproducible gate failure during unrelated work requires `quick-fix` or `fix-bug` (CONVENTIONS § Discovered Defects). Never dismiss failures as pre-existing or out of scope.
+- Read specs/ and CONVENTIONS.md before writing code. Write minimum code that solves the stated problem. Run tests after every change. All written output in specs/.

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [2.93.0](https://github.com/danielvm-git/bigpowers/compare/v2.92.0...v2.93.0) (2026-11-03)
+
+
+### Features
+
+* **context:** shave always-loaded context in AGENTS.md and CONVENTIONS.md to <=150 lines (e84s01) ([#197](https://github.com/danielvm-git/bigpowers/issues/197)) ([34f6366](https://github.com/danielvm-git/bigpowers/commit/34f6366d481fc582e7d556148870298811a5d0ff))
+
 # [2.92.0](https://github.com/danielvm-git/bigpowers/compare/v2.91.1...v2.92.0) (2026-11-03)
 
 

package/CONVENTIONS.md

@@ -12,475 +12,95 @@
 # story: e29s03
 # story: e54s03
 # story: e55s03
+# story: e84s01
 
 # Conventions
 
-[`constitution.md`](constitution.md) is a consolidated entry point synthesizing
-this project's doctrine (this file, CLAUDE.md, docs/PRINCIPLES.md,
-docs/references/*.md) into bigspec's B0-B10 + Capstone blocks, with citations
-back to the fuller text below. It's a starting point for a reader, not a
-replacement — this file remains fully authoritative for its own content today.
+[`constitution.md`](constitution.md) synthesizes this project's doctrine (this file, CLAUDE.md, docs/PRINCIPLES.md, docs/references/*.md) into B0-B10 + Capstone blocks. This file remains fully authoritative.
 
 ## Conventional Commits & Semantic Versioning
 
-All changes to this repository MUST follow the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification. Versioning MUST strictly adhere to [Semantic Versioning 2.0.0](https://semver.org/).
-
-### Commit Message Format
-`<type>(<scope>): <description>` (Space after colon is MANDATORY)
-
-### Types & Version Bumps
-- `feat`: Minor (x.Y.z) - New feature
-- `fix`: Patch (x.y.Z) - Bug fix
-- `perf`: Patch (x.y.Z) - Performance improvement
-- `docs`, `chore`, `style`, `refactor`, `test`: No bump (unless breaking)
-- `BREAKING CHANGE:` (or `!` after type): Major (X.y.z)
+All changes MUST follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) and [Semantic Versioning 2.0.0](https://semver.org/).
+- Format: `<type>(<scope>): <description>` (space after colon mandatory).
+- Types: `feat` (minor), `fix`/`perf` (patch), `docs`/`chore`/`style`/`refactor`/`test` (no bump). `BREAKING CHANGE:` or `!` triggers major.
 
 ## GitHub & Git Operations
 
 - No direct work on `main` or `master`. Every task MUST start with a feature branch or worktree via `kickoff-branch`.
-- **Integrate (team default):** Use `gh pr create` and `gh pr merge --squash` via `release-branch` (team-pr mode). Prefer `gh` over ad-hoc `git push` + manual PR UI.
-- **Integrate (solo profile):** When `profiles/solo-git.md` or `specs/WORKFLOW-solo-git.md` is active, ship with `bash scripts/land-branch.sh <branch> "<conventional message>"` after `release-branch` gates — local squash to `main`, then push. PR is optional (remote CI / branch protection only).
-- `git push origin <feature-branch>` is allowed for backup or CI; never push directly to `main`/`master` except via `land-branch.sh` (`GIT_BIGPOWERS_LAND=1`).
-- Use `gh repo clone` not `git clone` for GitHub repos
-- Use `gh run view` / `gh run watch` for CI status
-- Verify auth with `gh auth status` before operations
-- **Git Attribution:** NEVER include `Co-authored-by`, `Co-Authored-By`, or any other footer that attributes code to an AI agent (e.g., Claude, Gemini). All commits must appear as if they were authored solely by the human user.
-- **State Commit Policy:** To minimize git history noise, intermediate `chore(state):` commits (e.g., tracking build-epic step transitions) should either be squashed locally using the `--squash-state` flag on `release-branch` before merging, or kept out-of-band using local cycle-state files.
-- Never call GitHub REST API directly (curl, fetch, etc.)
-- Never create GitHub issues from automated workflows — produce local .md files in specs/ instead
-- **Post-land branch cleanup:** `land-branch.sh` squash-merges the feature branch, so `git branch -d <branch>` afterward always fails ("not fully merged" — expected, since a squash doesn't create an ancestor relationship). `git branch -D <branch>` is the correct next step, but `guard-git`'s hook blocks agents from running `-D` directly. Leave the orphaned local branch for the human to delete, or fix `land-branch.sh` to delete its own branch under the `GIT_BIGPOWERS_LAND=1` exemption it already sets — don't spend a turn fighting the hook.
-
-### Pre-Merge Verification Gates
-
-Before merging any branch, run the deterministic verification gates:
-
-```bash
-bash scripts/run-verification-gates.sh
-```
-
-This runs compliance → G-04 self-test. If any gate fails, the merge is blocked.
-Pin a fresh baseline with `--baseline` after major structure changes.
+- **Integrate:** Use `gh pr create` + `gh pr merge --squash` via `release-branch`. Solo profile: `bash scripts/land-branch.sh <branch> "<msg>"` after release gates.
+- Never push directly to `main`/`master` except via `land-branch.sh` (`GIT_BIGPOWERS_LAND=1`). Use `gh` over git/curl/fetch.
+- **Git Attribution:** NEVER include `Co-authored-by`, `Co-Authored-By`, or any AI attribution footer in git commits. All commits must appear solely authored by the human user.
+- **Pre-Merge Verification Gates:** Run `bash scripts/run-verification-gates.sh` (compliance → G-04 self-test) before any merge.
 
 ## Agent Workflow Mandates
 
 **AGENTS MUST NEVER BYPASS THE BIGPOWERS WORKFLOW.**
-You are operating within the `bigpowers` spec-driven development methodology.
-- **No Direct Coding:** When a user issues a directive like "build feature X" or "go epic 10", you MUST NOT execute the request by writing code directly.
-- **Required Skills:** You MUST route all work through the appropriate bigpowers skills.
-  - Start with `survey-context` if you lack context.
-  - Use `plan-work` to flesh out tasks in `specs/epics/eNN-*.yaml` (with `verify:` per task) before writing any feature code.
-  - Use `develop-tdd` or `execute-plan` to implement the plan.
-  - Use `investigate-bug` for bug reports before writing a fix.
-- **Verification Mandate:** Every story implementation MUST end with a step-by-step manual verification script provided to the user. You must wait for the user to confirm behavioral correctness (UAT) before declaring the story done or moving to the next.
-- **Verification:** You MUST verify every change with tests. Code generation without a corresponding plan in `specs/` is strictly forbidden.
-- **Traceability Mandate:** Every story MUST have at least one `story: eNNsNN` tag in its implementing code or test file. `trace-stories.sh --strict` runs in CI to enforce this. Untagged stories fail the CI traceability gate.
-- **Scenario ID Format (e46s04+):** When a `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` exists for the epic, critical-path scenarios use the format `SC-eNNsYY-P{0|1|2|3}-NN` (e.g. `SC-e46s04-P0-01`). These IDs are referenced inside test files as `// scenario: SC-eNNsYY-P0-NN` comments alongside the existing `// story: eNNsNN` tag. SC gaps detected via check-blind-spots.sh; no separate SC tracing script required. gate-trace treats a P0 story with zero `SC-*-P0-*` references in test files as a CONCERNS finding (waivable via `state.yaml`). P2/P3 epics may set `test_plan: waived` in `state.yaml` to skip the `plan-tests` skill.
-- **Stream Continuity:** When writing large files or long documents, you MUST output continuously in chunks of ~200 lines. Do not pause between sections. Continue immediately until complete. If you need time to process, emit a placeholder comment or heading rather than going silent to prevent stream idle timeouts.
-
-## Always Green / Shift Left
-
-Solo developers own the whole codebase. **Always Green** means Preflight and CI are green before any forward work — not "green enough for this task."
-
-**Shift Left (1-10-100):** Defects cost roughly 1× to fix in development, 10× in integration, 100× in production (IBM Systems Sciences Institute; CloudQA benchmarks). Fixing a red gate now is cheaper than shipping and debugging later.
-
-**Preflight** — the project's full local verification stack (chained from test, lint, typecheck, and build commands recorded in `CLAUDE.md`). Preflight MUST pass before kickoff, develop, or verify phases advance.
-
-**CI green** — when a PR exists or remote CI applies, `gh pr checks` (or equivalent) MUST show passing before merge or land.
-
-**Existing projects:** Projects seeded before e51 do not receive these sections automatically. Re-run `seed-conventions` and merge the Always Green blocks, or copy § Always Green and § Discovered Defects from bigpowers `CONVENTIONS.md` manually.
-
-## Discovered Defects
-
-Any **reproducible gate failure** encountered during unrelated work is a discovered defect — not optional background noise.
+- **No Direct Coding:** Never write code directly for directives like "build feature X". Route feature work through bigpowers skills (`survey-context`, `plan-work`, `develop-tdd`, `verify-work`).
+- **Verification Mandate:** Every story must include runnable `verify:` commands. Verify every change with tests. Provide step-by-step UAT to user.
+- **Traceability Mandate:** Every story MUST have ≥1 `story: eNNsNN` tag in implementing code or tests (`bash scripts/trace-stories.sh --strict`).
+- **Scenario ID Format (e46s04+):** Critical-path scenarios use format `SC-eNNsYY-P{0|1|2|3}-NN` in `eNN-TEST_PLAN_LATEST.md` and tests.
+- **Stream Continuity:** Output continuously in chunks of ~200 lines. Never pause or go silent.
 
-**fix-or-log ladder (mandatory):**
+## Always Green & Discovered Defects
 
-1. **quick-fix** — trivial, data-only, or single-file fixes within guardrails.
-2. **fix-bug** — when quick-fix guardrails abort, or the failure needs investigation (`specs/bugs/BUG-*.md` + TDD).
-3. **Log** — only when reproduction is blocked after good-faith attempt; write a BUG spec and stop forward work on the original task until triaged.
-
-Discovered fixes ship in the **same PR** as the original work but in **separate commits** (Conventional Commits). Never narrate a failure and continue.
-
-**Hard block:** Red Preflight or red CI blocks kickoff-branch, develop-tdd, and verify-work forward progress until fix-or-log produces green.
+- **Always Green (Shift Left):** Preflight (`npm run compliance && bash scripts/run-verification-gates.sh`) and CI (`gh pr checks`) must be green before forward work.
+- **Discovered Defects (fix-or-log):** Any reproducible gate failure requires `quick-fix` or `fix-bug` (separate commit). Banned dismissive phrases: "pre-existing", "unrelated to this session", "not introduced by my changes", "out of scope".
 
 ## Risk Tiers (Effective Rule Matrix)
 
-Human-readable source of truth for verification depth. Machine-readable compile:
-
-```bash
-bash scripts/compile-rule-matrix.sh   # → specs/rule-matrix.json
-```
-
-Diff `specs/rule-matrix.json` across git tags to audit rule drift. Schema version in JSON `matrix_version` field.
+Human-readable source of truth for verification depth. Compile: `bash scripts/compile-rule-matrix.sh` (→ `specs/rule-matrix.json`).
 
 ### P0 — Critical (never violate)
-
 - **[always-green]**: Preflight and CI must be green before forward work. (`verify-work`, `kickoff-branch`, `develop-tdd`)
 - **[no-direct-coding]**: Route feature work through bigpowers skills — no ad-hoc implementation without a plan in `specs/`. (`plan-work`, `orchestrate-project`)
 - **[traceability]**: Every story has ≥1 `story: eNNsNN` tag in implementing code or tests. (`trace-stories.sh --strict`)
 - **[no-generated-edits]**: Never edit `.cursor/rules/`, `.gemini/`, or `website/src/content/docs/` directly. (`sync-skills.sh`)
 
 ### P1 — High (fix before merge)
-
 - **[conventional-commits]**: All commits follow Conventional Commits; semantic-release owns version bumps. (`commit-message`, `release-branch`)
 - **[verify-per-story]**: Every story/task has runnable `verify:` commands; `verify-work` confirms before done. (`plan-work`, `verify-work`)
 - **[test-on-change]**: New functions and bug fixes include tests; regressions get regression tests. (`develop-tdd`, `validate-fix`)
 - **[branch-protection]**: No direct work on `main`/`master`; feature branches via `kickoff-branch`. (`guard-git`)
 
 ### P2 — Medium (address in same epic or next)
-
 - **[plan-tests-waiver]**: P2/P3-dominant epics may set `test_plan: waived` in `state.yaml`. (`plan-tests`)
 - **[file-size-cap]**: Source files under 300 lines unless listed in § File-Size Exceptions. (`audit-code`)
 - **[handoff-signaling]**: Critical-path skills write `handoff.next_skill` to `state.yaml`. (`session-state`)
 - **[delta-requirements]**: Behavior changes require `ADDED`/`MODIFIED`/`REMOVED`/`RENAMED` tags in requirement specs. (`plan-work`, `change-request`)
 
 ### P3 — Low (best effort)
-
 - **[boy-scout]**: Leave touched files at least as clean as found. (`audit-code`)
 - **[terse-when-heavy]**: Switch to `terse-mode` when context exceeds ~20 turns. (`terse-mode`)
 - **[skill-naming]**: Verb-noun kebab-case under `skills/`; documented exceptions only. (`craft-skill`)
 
-### Banned dismissive phrases
-
-Agents MUST NOT use these phrases (or close paraphrases) to ignore reproducible failures:
-
-| Banned phrase | Required behavior instead |
-|---------------|---------------------------|
-| Pre-existing / pre-existing issues | Run fix-or-log; if truly unrelated, prove with a passing repro after revert |
-| unrelated to this session | Same — session boundaries do not waive green gates |
-| not introduced by my changes | Bisect or fix anyway; solo-default owns the whole tree |
-| out of scope (ignoring a red gate) | Invoke quick-fix or fix-bug; scope-minimization never overrides Always Green |
-
 ## specs/ — All Planning Output Goes Here
 
-Every skill that produces written output writes to `specs/` at the project root.
-
-### YAML cockpit (runtime + delivery)
-
-| Layer | File | Answers |
-|-------|------|---------|
-| Session | `specs/state.yaml` | Active flow, epic/bug, ship-epic step, git, `handoff.next_skill`, `metrics.story_start` |
-| Release index | `specs/release-plan.yaml` | Target semver, WSJF epic list, BCP baseline per story |
-| Progress | `specs/execution-status.yaml` | Flat status keys (`e01`, `e01s01`) — sole SoT for story state |
-| Cycle-time ledger | `specs/metrics/cycle-times.yaml` | Per-story: BCPs, start, end, cycle minutes, BCP/hr **(v2.0.0)** |
-| Planning UI | `specs/planning-status.yaml` | Discover-phase workflow checklist (optional) |
-
-**Do not** put story status in `release-plan.yaml`. **Do not** duplicate the release plan inside `state.yaml`.
-
-### BCP accounting mandate (v2.0.0)
-
-**BCP = Business Complexity Points** — a pre-build story size, not a per-task annotation. Canonical method: [`docs/references/bcp.md`](docs/references/bcp.md) (sourced from `flow-ciandt/bcp-agent`).
-
-- **Sizing (plan-release):** Every story in `specs/release-plan.yaml` MUST have a `bcps:` field set via the 6-step BCP sizing method before implementation begins. No story enters the build queue without a BCP baseline.
-- **Session state:** `plan-work` confirms the BCP size and writes it to `specs/state.yaml` as `epic_cycle.story_bcps`.
-- **Velocity (release-branch):** After landing, `release-branch` appends a row to `specs/metrics/cycle-times.yaml` with `bcp_per_hour = story_bcps / cycle_minutes * 60`.
-
-BCP is a **story-level** size. Per-task `[BCP N]` annotations are not part of the canonical method.
-
-### Timestamp mandate (v2.0.0)
-
-- `survey-context` MUST write `metrics.story_start` (ISO 8601) to `specs/state.yaml` at the start of every story.
-- `release-branch` MUST write `metrics.story_end`, `metrics.cycle_minutes`, and `metrics.bcp_per_hour` to `specs/state.yaml` and append a row to `specs/metrics/cycle-times.yaml` when the story lands.
-
-Missing timestamps are a gate violation — do not advance past `release-branch` without them.
-
-### next_skill signaling mandate (v2.0.0)
-
-Every critical-path skill (survey-context, plan-tests, plan-work, kickoff-branch, develop-tdd, verify-work, audit-code, commit-message, release-branch) MUST write `handoff.next_skill` to `specs/state.yaml` as its last action. Agents MUST read `state.yaml` and follow `handoff.next_skill` before asking "what comes next?".
-
-`plan-tests` is an optional planning-spine step: after `slice-tasks`, before `plan-work`, for epics whose stories carry `risk: P0|P1`. It is skipped (set `test_plan: waived` in `state.yaml`) for P2/P3-dominant epics.
-
-### Intent vs delivery vs execution
-
-| Question | File | Format |
-|----------|------|--------|
-| What should the product do? | `specs/product/SCOPE_LATEST.yaml` | YAML |
-| North star / initiative | `specs/product/VISION_LATEST.yaml` | YAML |
-| Glossary | `specs/product/GLOSSARY_LATEST.yaml` | YAML |
-| What ships in this release, in what order? | `specs/release-plan.yaml` | YAML |
-| How to implement an epic/story? | `specs/epics/eNN-*.yaml` or `specs/epics/eNN-*/stories/` | YAML + MD |
-| Where are we in the session? | `specs/state.yaml` | YAML |
-
-Epic IDs: `e01`, `e30`. Story IDs: `e01s01`. One FR in SCOPE may span multiple epics or releases.
-
-### Frozen release (ex-baseline)
-
-When planning closes, copy to `specs/product/snapshots/release-<version>/` (`release-plan.yaml`, `SCOPE_LATEST.yaml`, `VISION_LATEST.yaml`). No separate `baselines/` folder.
-
-### Semantic-release — the real version is never hand-tracked
-
-> **The authority is `gh release view` / git tags.** semantic-release decides the version
-> at merge from Conventional Commits. Never hand-maintain a `target_version` to "predict" it —
-> that field drifts from reality every release. The specs only *mirror* the real tag for reference.
-
-1. **Planning intent (codename only)** — `specs/release-plan.yaml` → `release.version`, `release.bump_hint`.
-   Treat `version` as a non-authoritative label; if you write a number, mark it "mirror, not the authority".
-2. **Published version (authority)** — repo root `package.json`, git tag `vX.Y.Z`, `CHANGELOG.md` (CI semantic-release; not hand-edited in specs). Read with `gh release view`.
-3. **Dashboard mirror** — `specs/state.yaml` → `release.last_tag`, `release.last_publish` (copied from `gh release view`; `target_version` is `null` — not tracked manually).
-
-### Guardrails and other artifacts
-
-| Document | Path |
-|----------|------|
-| Stack / architecture | `specs/tech-architecture/TECH_STACK_LATEST.md` |
-| Security / test / design plans | `specs/tech-architecture/*_PLAN_LATEST.md` |
-| Epic test plan (P0/P1 epics) | `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` — produced by `plan-tests` skill (e46s04); one per epic. |
-| Domain context + ADRs | `specs/tech-architecture/TECH_STACK_LATEST.md` or legacy `specs/CONTEXT.md` + `specs/adr/` |
-| Bug investigation | `specs/bugs/BUG-*.md` + `specs/bugs/registry.yaml` (generated) |
-| Refactor / impact | `specs/tech-architecture/REFACTOR_LATEST.md`, `specs/tech-architecture/IMPACT_LATEST.md` |
-| Legacy markdown | `specs/archive/` after `bash scripts/convert-legado.sh` |
-
-Validate YAML layout: `bash scripts/validate-specs-yaml.sh`. Patch runtime keys: `bash scripts/bp-yaml-set.sh specs/state.yaml git.branch feat/foo`.
-
-### Documentation Responsibilities (e45s36)
-
-Each specs/ artifact owns specific facts. Update the owning file when the fact changes — do not duplicate across files.
-
-| File / directory | Owns | Update when |
-|------------------|------|-------------|
-| `specs/state.yaml` | Active session, handoff, story timing, workflow mode | Every skill handoff; branch switch; story start/end |
-| `specs/release-plan.yaml` | Epic ordering, WSJF, BCP baselines, release codename | New epic scoped; WSJF re-prioritized; BCP re-estimated |
-| `specs/execution-status.yaml` | Story/epic done/todo status (sole SoT) | Story completes; gate-trace runs; manual status change |
-| `specs/product/SCOPE_LATEST.yaml` | In/out of scope, initiative boundaries | scope-work; change-request Add mode |
-| `specs/product/VISION_LATEST.yaml` | North star, strategic intent | Major product pivot; scope-work |
-| `specs/product/GLOSSARY_LATEST.yaml` | Canonical domain terms | define-language; model-domain term crystallizes |
-| `specs/epics/eNN-*/epic.yaml` | Epic manifest, story list, BCPs | slice-tasks; plan-work adds stories |
-| `specs/epics/eNN-*/eNNsYY-*.md` | Story requirements (countable-story-format) | plan-work; section approval state changes |
-| `specs/epics/eNN-*/eNNsYY-tasks.yaml` | Runnable implementation tasks + verify | plan-work; develop-tdd task completion |
-| `specs/tech-architecture/tech-stack.md` | Stack, modules, gray areas | map-codebase; deepen-architecture; model-domain |
-| `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` | P0/P1 test scenarios per epic | plan-tests |
-| `specs/adr/ADR-*.md` | Architectural decisions | model-domain; deepen-architecture ADR offer accepted |
-| `specs/bugs/BUG-*.md` | Bug RCA + fix plan | investigate-bug |
-| `specs/bugs/registry.yaml` | Bug index (generated) | inspect-quality; sync-bugs-registry.sh |
-| `specs/verifications/*` | Verify evidence, audit reports, eval reports | verify-work; audit-code; run-evals |
-| `specs/security/REVIEW.md` | Latest security scan findings | security-review |
-| `specs/metrics/cycle-times.yaml` | Delivery velocity ledger | release-branch lands story |
-
-### Generated artifact targets
-
-Skill content is edited in `skills/*/SKILL.md` and auto-propagated to these targets by `bash scripts/sync-skills.sh`:
-- `.cursor/rules/` — Cursor IDE rules
-- `.gemini/extensions/bigpowers/` — Gemini CLI extensions
-- `.pi/skills/` + `.pi/prompts/` — pi agent
-- `website/src/content/docs/` — Docs website (Astro Starlight, deployed to GitHub Pages)
-
-**Never edit any of these targets directly.** Edit the SKILL.md sources and run rebuild scripts (`bash scripts/sync-skills.sh`, `npm run site:build`).
-
-### Packaging boundary — dev-repo tooling vs. end-user CLI
-
-bigpowers ships itself as an npm package (`bin/setup.js`) while also being a
-self-hosting monorepo that dogfoods its own skills. `.npmignore` excludes
-`specs/`, `docs/`, and `.git` from the published tarball — a real end-user
-install has none of them.
-
-**Any script invoked from `bin/*.js` (the end-user CLI surface) must not
-assume dev-only files exist.** `scripts/sync-skills.sh` conflates two
-concerns — skill distribution (render into `.cursor/rules/` etc., relevant
-to every user) and dev-repo maintenance (`sync_post_run`: regenerate
-`skills-lock.json`, `SKILL-INDEX.md`, `docs/references/model-profiles.md`,
-`specs/epics-wiki/`, `specs/adr-wiki/` — relevant only to bigpowers
-contributors). `bin/setup.js` calls it with `--distribute-only`, which skips
-`sync_post_run` entirely; the no-flag form remains the contributor
-dev-workflow. Before wiring any dev-maintenance script into an installer
-path, verify with `command npm pack --pack-destination <dir>` + extract
-what a real install actually contains, rather than assuming `specs/`/`docs/`
-are present (see `BUG-2026-07-24-installer-runs-dev-maintenance-pipeline`).
-
-### Legacy paths (migrate away)
-
-| Old | New |
-|-----|-----|
-| `specs/STATE.md` | `specs/state.yaml` |
-| `specs/RELEASE-PLAN.md` | `specs/release-plan.yaml` + `specs/epics/` |
-| `specs/SCOPE.md` | `specs/product/SCOPE_LATEST.yaml` |
-
-## Code Style
-
-- Functions: 4–20 lines. Split if longer.
-- Files: under 300 lines. Split by responsibility to ensure content fits within a single agent context window.
-- One thing per function, one responsibility per module (SRP).
-- Names: specific and unique. Avoid `data`, `handler`, `Manager`, `Service`. Prefer names whose grep returns < 5 hits in this codebase.
-- Types: explicit. No `any`, no untyped public functions.
-- No code duplication. Extract shared logic into a function/module.
-- Early returns over nested ifs. Max 2 levels of indentation.
-- Conditionals: expressed as positives (G29). Avoid negative flags or `unless` logic where possible.
-- The Stepdown Rule (G34): functions should descend exactly one level of abstraction.
-- Names describe side-effects (N7): if a function sends email, writes to disk, or mutates state, the name must say so (`sendWelcomeEmail`, not `processUser`).
-- No magic strings or numbers (G25): every bare string literal or numeric literal used in logic must be extracted to a named constant.
-- Boolean logic in named functions (G28): complex boolean expressions must be extracted into a named predicate function, not inlined.
-- Prefer exceptions over error codes: throw/raise an exception rather than returning a numeric or boolean error sentinel.
-- Remove dead code (G9/F4): unused functions, unreachable branches, and stale imports must be deleted — not commented out.
-- Boy Scout Rule: leave every file you touch at least as clean as you found it. Fix the first broken window you see.
-- **Law of Demeter:** A method should call only its immediate collaborators — not `a.getB().getC().doX()`. Chain violations need explicit justification in code review.
-- **Verification mandate:** Every story must include runnable `verify:` commands (in epic shards or story files). No story is done until `verify-work` confirms it (or user explicitly waives with documented reason in `specs/state.yaml` handoff).
-- Exception messages must include the offending value, expected shape, and an actionable remediation hint for the agent.
-- SOLID beyond SRP: favor interfaces over concrete types (DIP) when injecting dependencies.
-- **`grep -E` portability:** never use `\d` or `\D` in a `grep -E` pattern — they are PCRE-only escapes, not GNU grep extensions (unlike `\s`/`\S`/`\w`/`\W`, which GNU grep does support). Real GNU grep on Linux CI treats `\d` as a literal `d`, silently matching nothing; this only "works" on macOS if the local `grep` happens to be a permissive BSD/GNU-compatible variant. Use `[0-9]` instead. This exact defect broke the traceability gate codebase-wide (`scripts/lib/trace-stories.py`, `scripts/lib/trace-matrix.py`) while passing every local check.
-
-## Comments
-
-- Keep your own comments. Never strip them on refactor — they carry intent and provenance.
-- Write WHY, not WHAT.
-- Complex or non-obvious logic must include "Provenance" links (e.g., Jira issue, GitHub commit SHA, or ADR filename).
-- Docstrings on public functions: intent + one usage example.
-- Reference issue numbers / commit SHAs when a line exists because of a specific bug.
-- No obvious comments that restate the code.
-- No commented-out code (C5): dead code must be deleted, not commented out. Use git history to recover it.
-
-## Tests (F.I.R.S.T — Uncle Bob Ch 9)
-
-- Tests run headless with a single command (recorded in CLAUDE.md).
-- Every new function gets a test. Every bug fix gets a regression test.
-- Mocks for external I/O are named fake classes, not inline stubs.
-- Tests are **F**ast, **I**ndependent, **R**epeatable, **S**elf-Validating, **T**imely.
-- Never skip or @ignore a test without an explicit ambiguity note explaining what is unresolved (T4); silently ignored tests are prohibited.
-- Test boundary conditions (T5): every suite must cover exact edge values — empty input, maximum, minimum, and off-by-one.
-- Test through public interfaces only (T8): assert on observable outcomes (return values, API responses, UI state). Never assert on internal state or private methods.
-- Every change must be verifiable with a single runnable command before it is marked done.
-
-## Dependencies
-
-- Inject dependencies through constructor/parameter, not global/import.
-- Wrap third-party libs behind a thin project-owned interface.
-
-## Structure
-
-- Follow the framework convention (Rails, Django, Next.js, etc.).
-- Predictable paths: controller/model/view, src/lib/test.
-- Prefer small focused modules over god files.
-
-## Formatting
-
-- Use the language default formatter (cargo fmt, gofmt, prettier, black, rubocop -A).
-- Configured in pre-commit and on-save. No style debates beyond that.
-
-## Logging
-
-- Structured JSON for debugging / observability.
-- Plain text only for user-facing CLI output.
-
-## Defensive Code
-
-- Retry with backoff (for API/network calls in skill implementations)
-- Timeout (for long-running operations)
-- Graceful degradation (when external services/dependencies fail)
-
-The agent implements defensive code only for categories explicitly listed here.
-
-## Skill Naming — Conventions and Exceptions
-
-All skill directories under `skills/` use a two-word `verb-noun` kebab-case pair (ADR-0001). Grep for any skill
-name must return < 5 results across the repo.
-
-**Documented exceptions** (adjective-noun retained for clarity; renaming would reduce usability):
-
-| Skill | Convention deviation | Rationale |
-|-------|----------------------|-----------|
-| `terse-mode` | adjective-noun | `enable-terse` implies a toggle; `terse-mode` names a mode state |
-| `visual-dashboard` | adjective-noun | `view-dashboard` implies read-only; `show-dashboard` collides with `show` verbs |
-| `deploy` | single verb | Well-known DevOps single-word concept; renames like `deploy-app` or `deploy-service` are redundant since deploy always targets an application |
-| `grill-with-docs` | three-word verb-prep-noun | Variant of `grill-me`; the `-with-docs` suffix is the distinguishing feature — collapsing it would hide the doc-grounded contract |
-| `generate-allure-report` | three-word verb-noun-noun | `generate-report` is ambiguous across report types; `allure` names the specific output format consumers integrate with |
-| `simple-english` | adjective-noun | Names the recognizable STE brand users search for (`simplify-english` / `write-plain` hide intent and break searchability for users coming from the upstream skill) |
-
-Any new exception requires an entry in this table before the skill is published.
-
-## Tombstone Aliases (e53s02)
-
-Every skill rename or merge ships a tombstone alias for one release, so consumers
-referencing the old name don't break immediately.
-
-**Mechanism:**
-
-1. Run `bash scripts/tombstone-skill.sh <old-name> <new-name-or-merge-target>` when
-   renaming or merging a skill. It replaces `skills/<old-name>/SKILL.md` with a stub
-   pointing at the new name/location, preserves the old skill's `# story: eNNsNN` tags
-   for traceability, and registers the mapping in `specs/tombstones.yaml` (old name,
-   new name/target, creation timestamp, and the `created_at_version` at creation time).
-2. Run `bash scripts/validate-tombstones.sh` to confirm every registered tombstone's
-   stub still resolves, and to flag any tombstone whose `created_at_version` is in a
-   different minor/major release train (major.minor) than the current version — that
-   stub has served its one-release transition window and should be removed. Patch-only
-   bumps within the same minor version don't count as a new release: this repo ships
-   via semantic-release on every merge to main, so comparing full semver strings would
-   expire a tombstone within minutes of creation instead of giving consumers a real
-   migration window.
-3. **Required alongside the first real use of `tombstone-skill.sh`:** update
-   `docs/references/model-profiles.md`'s skill-count annotations. A tombstone stub is
-   still a `skills/*/SKILL.md` file — it increments the live skill count the same as
-   any other skill, and the count doc must reflect that.
-
-**Rejected names:** both the old and new name must be a bare kebab-case skill name
-(`^[a-z][a-z0-9-]*$`) — `tombstone-skill.sh` refuses anything else before touching the
-filesystem (path segments, absolute paths, etc.).
-
-This story (e53s02) builds the mechanism only; it creates no real tombstone stub
-itself, so the live skill count doesn't move yet. The first real use is expected in
-e56 (skill reclassification/merges).
-
-## Catalog Freeze (e54-e59 migration)
-
-The 80-skill catalog is frozen as of `specs/tech-architecture/CATALOG-BASELINE-<date>.yaml`
-(e54s01) so e56's reclassification work (80 skills → ~28 procedures) has a stable
-starting point instead of a moving target. `bash scripts/check-catalog-drift.sh`
-(e54s02) diffs the live catalog against that baseline on every Preflight run and
-prints `WARNING:` lines for drift — it is advisory only (always exits 0) and never
-blocks Preflight or CI.
-
-**Frozen (triggers a drift warning):**
-- Adding a new `skills/<name>/SKILL.md` directory
-- Structural changes to an existing skill's `phase`, `effort`, or `model` frontmatter
-  fields
-
-**Not frozen (no warning; proceed as normal):**
-- Bug fixes within an existing skill's existing shape
-- `description:` edits
-- Any other content fix that doesn't touch `phase`/`effort`/`model`
-
-**Exit criterion:** the freeze ends when e56 (reclassify-catalog) merges. e56's
-completion is the unfreeze event itself — there is no calendar date, and no other
-story or action lifts the freeze early.
-
-**Exception marker:** a change that is genuinely unrelated to the migration (e.g. an
-urgent fix that happens to touch a frozen field) can suppress its own drift warning
-by adding a comment containing the literal string `freeze-exception` to the affected
-`SKILL.md`, for example:
-
-```
-<!-- freeze-exception: urgent security fix, unrelated to the e54-e59 migration -->
-```
-
-`scripts/check-catalog-drift.sh` checks for this exact substring — it must remain
-byte-identical between this document and the script, or the exception path silently
-stops working. Use it sparingly: it should be a marker for something a human decided
-was safe to change during the freeze, not a way to permanently silence the gate for a
-skill that should just wait until e56.
-
-## File-Size Exceptions
-
-The 300-line file cap exists to ensure files fit in a single agent context
-window. The following files are documented exceptions:
-
-| File | Lines | Rationale | Review date |
-|------|-------|-----------|-------------|
-| `scripts/audit-compliance.sh` | 300 | Gherkin harness with embedded judge logic and waiver subsystem; splitting the judge loop from the reporting layer would require fragile state-passing. At the 300-line cap; monitor. | 2026-10-01 |
-
-**Note:** `scripts/trace-stories.sh` was refactored from a 613-line monolith into a
-69-line orchestrator delegating to `scripts/lib/trace-stories.py`. `scripts/lib/trace-matrix.py`
-was split into `simple_yaml.py` + `trace_renderer.py` (252 lines); see
-BUG-2026-07-06-gate-trace-matrix-oversized. Prior exception rows for trace-matrix.py
-and trace-stories.py are removed — both are now under the 300-line cap.
-
-Any new exception requires an entry in this table with rationale and a review date.
-
-## docs/references SSOT Sync (e45s10)
-
-Agent-guidance files under `docs/references/` are **distilled from upstream sources**, not hand-edited ad hoc. Canonical inputs live in `CLAUDE.md`, `docs/PRINCIPLES.md`, and `skills/*/SKILL.md`.
-
-| Action | Command |
-|--------|---------|
-| Regenerate locally | `bash scripts/sync-references.sh` |
-| Manifest | `scripts/references-manifest.yaml` |
-| Scheduled CI | `.github/workflows/sync-references.yml` (weekly) |
-
-After changing SKILL.md `model:` frontmatter or token-management prose in CLAUDE.md, run `sync-references.sh` to refresh reference docs and `.sync-stamp`.
+Every skill writes written output to `specs/` at root. See [specs/README.md](specs/README.md) for full schema.
+- **YAML cockpit:** `specs/state.yaml` (session & handoff), `specs/release-plan.yaml` (WSJF index), `specs/execution-status.yaml` (story done/todo SoT), `specs/metrics/cycle-times.yaml` (velocity ledger).
+- **BCP accounting mandate:** BCP = Business Complexity Points (story size baseline via 6-step method before build; see [docs/references/bcp.md](docs/references/bcp.md)). Timestamps: `metrics.story_start` and `metrics.story_end` mandatory.
+- **Generated targets:** Never edit `.cursor/rules/`, `.gemini/extensions/bigpowers/`, `.pi/`, or `website/src/content/docs/` directly — run `bash scripts/sync-skills.sh`.
+
+## Code Style & Clean Architecture
+
+- **Size limits:** Functions: 4–20 lines (split if longer). Source files: under 300 lines (SRP; fits single context window).
+- **Quality heuristics:** One responsibility per function/module (SRP). Stepdown Rule (G34). Demeter's Law.
+- **Names:** specific and unique (<5 hits in repo). Avoid `data`, `handler`, `Manager`, `Service`. Names describe side-effects (N7).
+- **Types:** explicit typing mandatory — no `any`, no untyped public APIs. No magic numbers/strings (G25).
+- **Errors & remediation:** Throw typed exceptions with offending value, expected shape, and actionable remediation hint.
+- **Boy Scout Rule:** Leave every file touched at least as clean as found. Remove dead code (G9/F4; no commented-out code C5).
+- **Portability:** `grep -E portability`: never use `\d` or `\D` (PCRE-only; breaks on GNU grep in Linux CI). Use `[0-9]`.
+- **Comments:** Write WHY, not WHAT. Never strip comments on refactor. Complex logic must include provenance links (issue, SHA, ADR).
+## Tests (F.I.R.S.T)
+- Fast, Independent, Repeatable, Self-Validating, Timely. Headless single-command runs.
+- Boundary conditions (T5): test exact edges (empty, min, max, off-by-one).
+- Public interfaces only (T8): test observable behavior, never private state.
+- No ignored tests without explicit ambiguity note (T4).
+
+## Detailed References
+
+- Skill Naming & Exceptions: [docs/references/skill-naming.md](docs/references/skill-naming.md)
+- Tombstone Aliases: [docs/references/tombstones.md](docs/references/tombstones.md)
+- Catalog Freeze: [docs/references/catalog-freeze.md](docs/references/catalog-freeze.md)
+- File-Size Exceptions: [docs/references/file-size-exceptions.md](docs/references/file-size-exceptions.md)
+- Reference SSOT Sync: [docs/references/ssot-sync.md](docs/references/ssot-sync.md)
+- Toolchain (bts, sqz, RTK): [docs/references/agent-tooling.md](docs/references/agent-tooling.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.92.0",
+  "version": "2.93.0",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/CLAUDE.md

@@ -1,400 +0,0 @@
-# story: e38s08
-# story: e51s05
-# story: e45s22
-# story: e45s23
-# story: e55s03
-
-# bigpowers — Claude Code
-
-Read CONVENTIONS.md before any GitHub or git operation.
-
-[`constitution.md`](constitution.md) is a consolidated entry point synthesizing
-this project's doctrine (this file, CONVENTIONS.md, docs/PRINCIPLES.md,
-docs/references/*.md) into bigspec's B0-B10 + Capstone blocks, with citations
-back to the fuller text. It's a starting point for a reader, not a
-replacement — this file remains fully authoritative for its own content today.
-
-<!-- BEGIN bigpowers:context-routing -->
-## Context Routing
-
-Load subdirectory context **by file glob** — do not read the full doc tree up front.
-
-| Glob / trigger | Load first | Fallback |
-|----------------|------------|----------|
-| `skills/**` | Active skill's `SKILL.md` + sibling `REFERENCE.md` if linked | `SKILL-INDEX.md` |
-| `specs/epics/**` | Capsule `epic.yaml` + active story `-tasks.yaml` | `specs/release-plan.yaml` |
-| `specs/product/**` | `SCOPE_LATEST.yaml`, `VISION_LATEST.yaml` | `specs/README.md` |
-| `specs/tech-architecture/**` | `tech-stack.md` + epic `eNN-TEST_PLAN_LATEST.md` if present | `CONVENTIONS.md` |
-| `scripts/**` | `CONVENTIONS.md` § Generated artifact targets | This file § Commands |
-| `website/**` | `website/README.md` if present | Never edit `website/src/content/docs/` (generated) |
-| `docs/**` | Matching doc under `docs/` | `docs/references/` |
-| Default / session start | This file → `CONVENTIONS.md` → `specs/state.yaml` | `survey-context` |
-
-Sub-AGENTS.md files (when present in consumer projects) override this table for their directory only.
-<!-- END bigpowers:context-routing -->
-
-<!-- BEGIN bigpowers:learned-preferences -->
-## Learned User Preferences
-
-_Durable preferences discovered across sessions. Update via `session-state` — do not infer from chat alone._
-
-- Prefer `rtk`-prefixed shell commands for git, test, and build output (token savings).
-- Run Preflight before forward work; never dismiss red gates as pre-existing.
-- Edit `skills/*/SKILL.md` sources only — never `.cursor/rules/` or `.gemini/` artifacts.
-
-## Workspace Facts
-
-_Stable repo facts — prefer these over re-discovery._
-
-- Stack: Markdown / Bash documentation project; skills sync via `bash scripts/sync-skills.sh`.
-- Planning SoT: `specs/state.yaml`, `specs/release-plan.yaml`, `specs/execution-status.yaml`.
-- Story traceability: `# story: eNNsNN` tags in implementing files; `bash scripts/trace-stories.sh --strict` in CI.
-- Rule matrix: `bash scripts/compile-rule-matrix.sh` → `specs/rule-matrix.json` (P0–P3 tiers from CONVENTIONS.md).
-<!-- END bigpowers:learned-preferences -->
-
-## Project
-
-bigpowers — agent skills for spec-driven, test-first software development by solo developers (skill count and catalog are auto-generated in `SKILL-INDEX.md`; never hardcode the count in docs).
-Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code, Cursor, Gemini CLI)
-
-## Commands
-
-| Action  | Command |
-|---------|---------|
-| Install | `npm install -g bigpowers && bigpowers setup` |
-| Run     | `bash scripts/sync-skills.sh` |
-| Test    | N/A (documentation project) |
-| Build   | `bash scripts/install.sh` (from source) |
-| Lint    | `bash scripts/sync-skills.sh` (validates SKILL.md syntax) |
-| Validate specs YAML | `bash scripts/validate-specs-yaml.sh` |
-| Typecheck | N/A (Markdown / Bash project) |
-| CI platform | GitHub Actions — one pipeline `.github/workflows/test-build-release.yml` (sync, verification-gates, skill-verify, story-verify → release, and → pages-build → pages-deploy when docs paths change); plus `publish-wiki.yml` |
-| Compliance | `npm run compliance` |
-| Verification Gates | `bash scripts/run-verification-gates.sh` |
-| Traceability | `bash scripts/trace-stories.sh --strict` | grep for story tags (traceability check) |
-| Preflight | `npm run compliance && bash scripts/run-verification-gates.sh && bash scripts/sync-skills.sh && bash scripts/trace-stories.sh --strict` | Full local green stack before forward work. Chain ends on `--strict` traceability — no trailing always-exit-0 step. |
-| Catalog drift (advisory) | `bash scripts/check-catalog-drift.sh` | e54s02 Confirm gate during catalog freeze — always exits 0; run manually when changing skills, not part of Preflight. |
-| CI | `gh pr checks` | Remote CI green when a PR is open |
-
-### Pre-Merge Checklist
-
-Before opening a PR or landing a branch, run:
-
-```bash
-npm run compliance && bash scripts/run-verification-gates.sh
-```
-
-If any gate fails, fix before merging. Run `--baseline` after any intentional increase in skill count or structure.
-
-**BCP Plus:** For stories sized with the 13-dimension BCP Plus methodology, confirm the `bcp_plus_breakdown` is present in the epic YAML and carried into `state.yaml` as `epic_cycle.bcp_plus`. See `docs/references/bcp-plus.md` for the NFR Gate pattern.
-
-## Architecture
-
-Collection of verb-noun skills under `skills/`, each with a SKILL.md source file and supporting documentation. Runtime specs live in `specs/state.yaml`, `specs/release-plan.yaml`, and `specs/execution-status.yaml`; intent in `specs/product/`; epic shards in `specs/epics/`. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning output goes to specs/ at the project root.
-
-## Conventions
-
-- Skill directories under `skills/` use verb-noun naming (two words, kebab-case)
-- Every skill has a single SKILL.md file as its source of truth
-- All planning/spec output goes to specs/ at project root
-- Artifacts in .cursor/rules and .gemini/ are auto-generated; edit SKILL.md, not artifacts
-- Run sync-skills.sh after any SKILL.md changes to regenerate artifacts
-- Website content in website/src/content/docs/ is auto-generated by prebuild; edit repo sources, not site files
-
-## Never
-
-- Never edit .cursor/rules or .gemini/extensions/ directly — these are generated files
-- Never edit website/src/content/docs/ directly — these are generated files; website/ is the fourth generated artifact target (alongside .cursor/, .gemini/, .pi/)
-- Never create a skill without a SKILL.md file and proper verb-noun naming
-- Never push changes without running sync-skills.sh first
-
-## Token Management
-
-**Mechanical backstop (e45s03):** `scripts/hooks/token-mgmt-pre-tool-use.sh` blocks oversized tool calls when prose rules are ignored. Wire as a `PreToolUse` hook for `Read`, `Grep`, and `Bash` (alongside `hooks/pre-tool-use.sh` for git safety). Thresholds: Read >100KB, Grep >200 matches without `head_limit`, Bash commands likely to exceed 500 output lines without `rtk`/`sqz compress`. Install snippet:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      { "matcher": "Read|Grep|Bash", "hooks": [{ "type": "command", "command": "bash scripts/hooks/token-mgmt-pre-tool-use.sh" }] }
-    ]
-  }
-}
-```
-
-Context engineering (write/select/compress/isolate — see `docs/references/context-engineering.md`):
-
-- **Write (token-efficient content):** Short functions (4-20 lines), unique symbol names, headless tests. Don't restate code in comments.
-- **Select (include only what's relevant):** Use `bts_map` for ranked file lists, `survey-context` for phase bootstrap. Don't read files you don't need.
-- **Compress (reduce without losing structure):** Use `bts_compress` or pipe through `sqz compress`. Use `rtk` for build/test/git output (60-99% savings). Prefer `terse-mode` when context is heavy.
-- **Isolate (partition work):** Use `kickoff-branch` for isolated worktrees, `dispatch-agents` for parallel tasks with disjoint scopes, `session-state` for cold-start handoff.
-
-**Effort classification:** Skills carry an `effort:` frontmatter field (`light` | `standard` | `heavy`). Prefer `light` skills for bootstrap/status checks; reserve `heavy` for epic builds and multi-phase planning.
-
-- **Auto-Terse**: When a session exceeds 20 turns or the context window feels "heavy" (latency increasing), you MUST switch to `terse-mode` to save tokens.
-- **Context Compaction**: Every 10 turns, summarize the current session state and implementation decisions into a short, high-density note.
-- **Minimal Output**: Prefer text-only output for simple status; use `web_fetch` or `run_shell_command` only for evidence.
-- **Stream Stability**: When writing large files or long documents, output continuously in chunks of ~200 lines. Do not pause. If you need time to process, emit a placeholder comment rather than going silent.
-
-## Session Start
-
-Before any task, run this sequence — not optional:
-
-1. Read `CLAUDE.md` (this file)
-2. Read `CONVENTIONS.md`
-3. Read `specs/state.yaml` if it exists — current session and active epic
-4. Read `specs/release-plan.yaml` if it exists — active release context
-
-## Agent Rules
-
-- **Workflow Mandate:** You MUST use the bigpowers skills (e.g., `plan-work`, `develop-tdd`, `craft-skill`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
-- **Always Green / fix-or-log:** Preflight and CI must be green before forward work. Any reproducible gate failure during unrelated work requires **quick-fix** or **fix-bug** — see CONVENTIONS § Discovered Defects. Never dismiss failures as pre-existing or out of scope.
-- Read specs/ and CONVENTIONS.md before writing code.
-- Write the minimum code that solves the stated problem. Nothing extra.
-- Run tests after every change. Show evidence before declaring done.
-- One clarifying question beats a wrong assumption baked into 200 lines.
-- All written output (plans, specs, investigations) goes in specs/.
-
-## bts toolchain
-
-`bts` is installed. Prefer its verbs over ad-hoc shell commands.
-
-| Task | Command | Avoid |
-|------|---------|-------|
-| Search code | `bts find --print <pattern>` | grep / find / cat |
-| Interactive search | `bts find <pattern>` | manual grep pipes |
-| Compress for context | `bts compress <file>` or `cmd \| bts compress` | summarising by hand |
-| Repo map | `bts map` | listing files by hand |
-| Library docs | `bts docs <lib>` | guessing from training data |
-| Package source | `bts src <pkg>` | git clone |
-| Toolchain health | `bts doctor` | which / command -v |
-
-**Rules**
-- Search with `bts find` before opening files to locate a symbol or pattern.
-- Pipe anything > 200 lines through `bts compress` before adding to context.
-- Run `bts map` when asked for a repo overview.
-- Use `bts docs <lib>` before answering questions about library APIs. Doc fetches use `scripts/lib/doc-fetch-cache.sh` (ETag-revalidated, 300s TTL).
-- If a tool is missing, say so and run `bts doctor` — do not silently substitute.
-
-<!-- BEGIN rtk-pretooluse-hook (e45s16 — mechanical PreToolUse backstop; remove block to disable) -->
-
-**RTK hook (installed):** `scripts/hooks/rtk-rewrite.sh` is symlinked into `~/.claude/hooks/` by `bash scripts/install.sh` and registered as a Bash `PreToolUse` hook. It delegates to `rtk hook claude` — prose rules below are a fallback only when the hook is absent.
-
-<!-- END rtk-pretooluse-hook -->
-
-<!-- BEGIN sqz-claude-guidance (auto-installed by sqz init; remove this block to disable) -->
-
-## sqz — Context Compression (READ FIRST)
-
-sqz is installed in this project. It compresses tool output so large
-files, long logs, and verbose command output cost far fewer tokens.
-There are **two ways** sqz is wired in, and you should prefer each
-one in the situations below.
-
-### Preferred tools (MCP)
-
-The `sqz-mcp` server is registered in this project's MCP config. It
-exposes three read-only tools that compress their output through the
-sqz pipeline:
-
-- **`sqz_read_file`** — read a file from disk and return a compressed
-  view. **PREFER this over the built-in `Read` tool** for any file
-  larger than ~2KB or any file you might read more than once in the
-  same session. Repeat reads return a 13-token `§ref:HASH§` reference
-  instead of the full content.
-
-- **`sqz_grep`** — search files for a literal string or regex.
-  **PREFER this over the built-in `Grep`** for anything that might
-  match more than a handful of lines. Caps at 200 matches by default;
-  raise with `max_matches` if needed.
-
-- **`sqz_list_dir`** — list a directory. Skips `.git`, `node_modules`,
-  `target`, `dist`, `build`, `vendor`, `__pycache__` so the output
-  stays focused. **PREFER this over `ls -la` via Bash** when you want
-  to see a project layout.
-
-The built-in `Read`, `Grep`, `Glob` tools remain available. Use them for:
-- Tiny config files (<1KB) where compression can't help.
-- Byte-exact reads you'll hash or diff (lockfiles, signatures).
-- Globbing (sqz has no glob tool; `Glob` is still the right choice).
-
-### Bash commands (hooked automatically)
-
-When you run a shell command through the `Bash` tool, a PreToolUse hook
-rewrites it to pipe output through `sqz compress`. This is transparent:
-you don't need to remember to add anything, but it's useful to know
-that these commands get compressed automatically:
-
-```bash
-git status           # → git status 2>&1 | sqz compress --cmd git
-cargo test           # → cargo test 2>&1 | sqz compress --cmd cargo
-docker ps            # → docker ps 2>&1 | sqz compress --cmd docker
-kubectl get pods     # → kubectl get pods 2>&1 | sqz compress --cmd kubectl
-```
-
-The rewrite is skipped for interactive commands (`vim`, `ssh`,
-`python`), compound commands (`a && b`, `a > file.txt`), and anything
-already going through sqz.
-
-### Escape hatch — when you see a `§ref:HASH§` token
-
-If tool output contains a `§ref:a1b2c3d4§` token and you need the full
-content it points at, resolve it. Three equivalent ways:
-
-- Shell: `/Users/danielvm/.local/bin/sqz expand a1b2c3d4` (or paste the whole token
-  `/Users/danielvm/.local/bin/sqz expand §ref:a1b2c3d4§`).
-- MCP tool: call `expand` with `{ "prefix": "a1b2c3d4" }`.
-- To get uncompressed output for one command: prefix it with
-  `SQZ_NO_DEDUP=1` (e.g. `SQZ_NO_DEDUP=1 git log | sqz compress`).
-
-If the compressed output is actively making the task harder (looping
-on refs, small retries replacing one big read), call the `passthrough`
-MCP tool to get raw text.
-
-### When NOT to use sqz tools
-
-- Writing or editing files — use the built-in `Write`/`Edit` tools.
-  sqz has no write tools (by design; see issue #5 follow-up).
-- Running commands interactively or in watch mode.
-- Reading very small files (<1KB) where compression can't help.
-
-<!-- END sqz-claude-guidance -->
-
-<!-- rtk-instructions v2 -->
-# RTK (Rust Token Killer) - Token-Optimized Commands
-
-## Golden Rule
-
-**Always prefix commands with `rtk`**. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use.
-
-**Important**: Even in command chains with `&&`, use `rtk`:
-```bash
-# ❌ Wrong
-git add . && git commit -m "msg" && git push
-
-# ✅ Correct
-rtk git add . && rtk git commit -m "msg" && rtk git push
-```
-
-## RTK Commands by Workflow
-
-### Build & Compile (80-90% savings)
-```bash
-rtk cargo build         # Cargo build output
-rtk cargo check         # Cargo check output
-rtk cargo clippy        # Clippy warnings grouped by file (80%)
-rtk tsc                 # TypeScript errors grouped by file/code (83%)
-rtk lint                # ESLint/Biome violations grouped (84%)
-rtk prettier --check    # Files needing format only (70%)
-rtk next build          # Next.js build with route metrics (87%)
-```
-
-### Test (60-99% savings)
-```bash
-rtk cargo test          # Cargo test failures only (90%)
-rtk go test             # Go test failures only (90%)
-rtk jest                # Jest failures only (99.5%)
-rtk vitest              # Vitest failures only (99.5%)
-rtk playwright test     # Playwright failures only (94%)
-rtk pytest              # Python test failures only (90%)
-rtk rake test           # Ruby test failures only (90%)
-rtk rspec               # RSpec test failures only (60%)
-rtk test <cmd>          # Generic test wrapper - failures only
-```
-
-### Git (59-80% savings)
-```bash
-rtk git status          # Compact status
-rtk git log             # Compact log (works with all git flags)
-rtk git diff            # Compact diff (80%)
-rtk git show            # Compact show (80%)
-rtk git add             # Ultra-compact confirmations (59%)
-rtk git commit          # Ultra-compact confirmations (59%)
-rtk git push            # Ultra-compact confirmations
-rtk git pull            # Ultra-compact confirmations
-rtk git branch          # Compact branch list
-rtk git fetch           # Compact fetch
-rtk git stash           # Compact stash
-rtk git worktree        # Compact worktree
-```
-
-Note: Git passthrough works for ALL subcommands, even those not explicitly listed.
-
-### GitHub (26-87% savings)
-```bash
-rtk gh pr view <num>    # Compact PR view (87%)
-rtk gh pr checks        # Compact PR checks (79%)
-rtk gh run list         # Compact workflow runs (82%)
-rtk gh issue list       # Compact issue list (80%)
-rtk gh api              # Compact API responses (26%)
-```
-
-### JavaScript/TypeScript Tooling (70-90% savings)
-```bash
-rtk pnpm list           # Compact dependency tree (70%)
-rtk pnpm outdated       # Compact outdated packages (80%)
-rtk pnpm install        # Compact install output (90%)
-rtk npm run <script>    # Compact npm script output
-rtk npx <cmd>           # Compact npx command output
-rtk prisma              # Prisma without ASCII art (88%)
-```
-
-### Files & Search (60-75% savings)
-```bash
-rtk ls <path>           # Tree format, compact (65%)
-rtk read <file>         # Code reading with filtering (60%)
-rtk grep <pattern>      # Search grouped by file (75%). Format flags (-c, -l, -L, -o, -Z) run raw.
-rtk find <pattern>      # Find grouped by directory (70%)
-```
-
-### Analysis & Debug (70-90% savings)
-```bash
-rtk err <cmd>           # Filter errors only from any command
-rtk log <file>          # Deduplicated logs with counts
-rtk json <file>         # JSON structure without values
-rtk deps                # Dependency overview
-rtk env                 # Environment variables compact
-rtk summary <cmd>       # Smart summary of command output
-rtk diff                # Ultra-compact diffs
-```
-
-### Infrastructure (85% savings)
-```bash
-rtk docker ps           # Compact container list
-rtk docker images       # Compact image list
-rtk docker logs <c>     # Deduplicated logs
-rtk kubectl get         # Compact resource list
-rtk kubectl logs        # Deduplicated pod logs
-```
-
-### Network (65-70% savings)
-```bash
-rtk curl <url>          # Compact HTTP responses (70%)
-rtk wget <url>          # Compact download output (65%)
-```
-
-### Meta Commands
-```bash
-rtk gain                # View token savings statistics
-rtk gain --history      # View command history with savings
-rtk discover            # Analyze Claude Code sessions for missed RTK usage
-rtk proxy <cmd>         # Run command without filtering (for debugging)
-rtk init                # Add RTK instructions to CLAUDE.md
-rtk init --global       # Add RTK to ~/.claude/CLAUDE.md
-```
-
-## Token Savings Overview
-
-| Category | Commands | Typical Savings |
-|----------|----------|-----------------|
-| Tests | vitest, playwright, cargo test | 90-99% |
-| Build | next, tsc, lint, prettier | 70-87% |
-| Git | status, log, diff, add, commit | 59-80% |
-| GitHub | gh pr, gh run, gh issue | 26-87% |
-| Package Managers | pnpm, npm, npx | 70-90% |
-| Files | ls, read, grep, find | 60-75% |
-| Infrastructure | docker, kubectl | 85% |
-| Network | curl, wget | 65-70% |
-
-Overall average: **60-90% token reduction** on common development operations.
-<!-- /rtk-instructions -->

package/GEMINI.md

@@ -1,75 +0,0 @@
-# bigpowers — Gemini CLI
-
-> **Auto-generated** by `sync-skills.sh` from `CLAUDE.md`. Edit CLAUDE.md, not this file.
-
-Read CONVENTIONS.md before any GitHub or git operation.
-
-## Project
-
-bigpowers — 58 agent skills for spec-driven, test-first software development by solo developers.
-Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code, Cursor, Gemini CLI)
-
-## Commands
-
-| Action  | Command |
-|---------|---------|
-| Install | `npm install -g bigpowers && bigpowers setup` |
-| Run     | `bash scripts/sync-skills.sh` |
-| Test    | N/A (documentation project) |
-| Build   | `bash scripts/install.sh` (from source) |
-| Lint    | `bash scripts/sync-skills.sh` (validates SKILL.md syntax) |
-
-## Architecture
-
-Collection of 58 verb-noun skills, each with a SKILL.md source file and supporting documentation. Includes Verify phase and profiles/. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning and spec output goes to specs/ at the project root.
-
-## Conventions
-
-- Skill directories use verb-noun naming (two words, kebab-case)
-- Every skill has a single SKILL.md file as its source of truth
-- All planning/spec output goes to specs/ at project root
-- Artifacts in .cursor/rules and .gemini/ are auto-generated; edit SKILL.md, not artifacts
-- Run sync-skills.sh after any SKILL.md changes to regenerate artifacts
-
-## Never
-
-- Never edit .cursor/rules or .gemini/extensions/ directly — these are generated files
-- Never create a skill without a SKILL.md file and proper verb-noun naming
-- Never push changes without running sync-skills.sh first
-
-## Token Management
-
-- **Auto-Terse**: When a session exceeds 20 turns or the context window feels "heavy" (latency increasing), you MUST switch to `terse-mode` to save tokens.
-- **Context Compaction**: Every 10 turns, summarize the current session state and implementation decisions into a short, high-density note.
-- **Minimal Output**: Prefer text-only output for simple status; use `web_fetch` or `run_shell_command` only for evidence.
-
-## Agent Rules
-
-- **Workflow Mandate:** You MUST use the bigpowers skills (e.g., `plan-work`, `develop-tdd`, `craft-skill`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
-- Read specs/ and CONVENTIONS.md before writing code.
-- Write the minimum code that solves the stated problem. Nothing extra.
-- Never refactor, rename, or reorganize code outside the task scope.
-- Run tests after every change. Show evidence before declaring done.
-- One clarifying question beats a wrong assumption baked into 200 lines.
-- All written output (plans, specs, investigations) goes in specs/.
-
-## bts toolchain
-
-`bts` is installed. Prefer its verbs over ad-hoc shell commands.
-
-| Task | Command | Avoid |
-|------|---------|-------|
-| Search code | `bts find --print <pattern>` | grep / find / cat |
-| Interactive search | `bts find <pattern>` | manual grep pipes |
-| Compress for context | `bts compress <file>` or `cmd \| bts compress` | summarising by hand |
-| Repo map | `bts map` | listing files by hand |
-| Library docs | `bts docs <lib>` | guessing from training data |
-| Package source | `bts src <pkg>` | git clone |
-| Toolchain health | `bts doctor` | which / command -v |
-
-**Rules**
-- Search with `bts find` before opening files to locate a symbol or pattern.
-- Pipe anything > 200 lines through `bts compress` before adding to context.
-- Run `bts map` when asked for a repo overview.
-- Use `bts docs <lib>` before answering questions about library APIs.
-- If a tool is missing, say so and run `bts doctor` — do not silently substitute.