bigpowers 2.1.3 → 2.2.0

package/scripts/sync-skills.sh

@@ -161,4 +161,7 @@ if [[ -f "$manifest" ]]; then
   fi
 fi
 
+# Regenerate derived reference tables from live SKILL.md frontmatter
+bash "$REPO_ROOT/scripts/generate-reference-tables.sh"
+
 exit 0

package/scripts/validate-doctrine.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Doctrine drift guard — fails CI if any tracked invariants regress.
+# Run after sync-skills.sh and before merging any branch.
+# Extended by each epic: add new assertions below the relevant section header.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+ERRORS=0
+
+fail() {
+  echo "FAIL: $*" >&2
+  ERRORS=$((ERRORS + 1))
+}
+
+pass() {
+  echo "ok  : $*"
+}
+
+# ── Epic 1: Dead skill names in model-profiles.md ─────────────────────────────
+# Scope: model-profiles.md is the canonical skill-roster reference.
+# Other docs may legitimately reference npm tools or conceptual names.
+echo "--- [Epic 1] dead skill names in docs/references/model-profiles.md ---"
+DEAD=()
+while IFS= read -r name; do
+  if [[ ! -d "$name" ]]; then
+    DEAD+=("$name")
+  fi
+done < <(grep -oE '`[a-z][a-z-]+`' docs/references/model-profiles.md \
+  | tr -d '`' \
+  | grep -E '^[a-z]+-[a-z]+(-[a-z]+)?$' \
+  | sort -u)
+
+if [[ ${#DEAD[@]} -eq 0 ]]; then
+  pass "all skill names in model-profiles.md resolve to real directories"
+else
+  for name in "${DEAD[@]}"; do
+    fail "dead skill name in model-profiles.md: '$name' has no matching directory"
+  done
+fi
+
+# ── Epic 1: Legacy MD artifact names in docs/ (excluding historical file-structure/) ──
+# docs/file-structure/ is intentional historical comparison material (Epic 6 archives it).
+echo "--- [Epic 1] legacy MD artifact names in docs/ ---"
+LEGACY_HITS=$(grep -rE "PLAN\.md|STATE\.md|PROJECT\.md|CONTEXT\.md|SUMMARY\.md|VERIFICATION\.md|RESEARCH\.md|RELEASE-PLAN\.md" \
+  docs/ 2>/dev/null \
+  | grep -v "docs/file-structure/" \
+  | grep -v "docs/report-gsd-integration.md" \
+  | grep -v "specs/archive" \
+  | wc -l | tr -d ' ') || true
+if [[ "$LEGACY_HITS" -eq 0 ]]; then
+  pass "no legacy MD artifact names in docs/ (outside file-structure/)"
+else
+  fail "legacy MD artifact names found in docs/ ($LEGACY_HITS occurrences)"
+  grep -rE "PLAN\.md|STATE\.md|PROJECT\.md|CONTEXT\.md|SUMMARY\.md|VERIFICATION\.md|RESEARCH\.md|RELEASE-PLAN\.md" \
+    docs/ 2>/dev/null \
+    | grep -v "docs/file-structure/" \
+    | grep -v "docs/report-gsd-integration.md" \
+    | grep -v "specs/archive" | head -20 >&2
+fi
+
+# ── Epic 1: Skill count consistency ───────────────────────────────────────────
+echo "--- [Epic 1] skill count consistency ---"
+LIVE_COUNT=$(ls -d */SKILL.md 2>/dev/null | wc -l | tr -d ' ')
+STALE_COUNT_HITS=$(grep -rE "expect [0-9]+" docs/ 2>/dev/null \
+  | grep -v "expect $LIVE_COUNT" | wc -l | tr -d ' ') || true
+if [[ "$STALE_COUNT_HITS" -eq 0 ]]; then
+  pass "skill count annotations match live count ($LIVE_COUNT)"
+else
+  fail "stale skill count annotation in docs/ (live=$LIVE_COUNT, $STALE_COUNT_HITS mismatches)"
+  grep -rE "expect [0-9]+" docs/ 2>/dev/null | grep -v "expect $LIVE_COUNT" >&2
+fi
+
+# ── Epic 2: Non-canonical specs/ subpaths ─────────────────────────────────────
+# Exclusions: specs/archive, specs/epics/archive, CHANGELOG.md (auto-gen),
+#   specs/verifications/reports/ (generated reports), PLAN-evolve-structure.md
+#   (migration plan that documents the before→after paths as historical record).
+echo "--- [Epic 2] canonical specs/ subpaths ---"
+LEGACY_SPECS=$(grep -rE "specs/(requirements|plans|audit)\b" \
+  --include="*.md" --include="*.sh" --include="*.yaml" --include="*.yml" --include="*.json" . \
+  2>/dev/null \
+  | grep -v "specs/archive\|specs/epics/archive\|\.git\|node_modules\|\.gemini\|\.cursor" \
+  | grep -v "CHANGELOG\.md\|specs/verifications/reports/\|PLAN-evolve-structure\.md" \
+  | wc -l | tr -d ' ') || true
+if [[ "$LEGACY_SPECS" -eq 0 ]]; then
+  pass "no legacy specs/ subpaths (requirements/, plans/, audit/)"
+else
+  fail "legacy specs/ subpaths found ($LEGACY_SPECS occurrences)"
+  grep -rE "specs/(requirements|plans|audit)\b" \
+    --include="*.md" --include="*.sh" --include="*.yaml" --include="*.yml" --include="*.json" . \
+    2>/dev/null \
+    | grep -v "specs/archive\|specs/epics/archive\|\.git\|node_modules\|\.gemini\|\.cursor" \
+    | grep -v "CHANGELOG\.md\|specs/verifications/reports/\|PLAN-evolve-structure\.md" \
+    | head -10 >&2
+fi
+
+# ── Epic 3: BCP slop guard ────────────────────────────────────────────────────
+echo "--- [Epic 3] BCP terminology ---"
+BCP_SLOP=$(grep -ri "build commit point" . 2>/dev/null \
+  | grep -v "specs/archive\|\.git\|node_modules\|\.gemini\|\.cursor\|validate-doctrine\.sh" \
+  | wc -l | tr -d ' ') || true
+if [[ "$BCP_SLOP" -eq 0 ]]; then
+  pass "no 'Build Commit Point' slop — BCP = Business Complexity Points"
+else
+  fail "'Build Commit Point' found ($BCP_SLOP hits) — canonical term is 'Business Complexity Points'; see docs/references/bcp.md"
+  grep -ri "build commit point" . 2>/dev/null \
+    | grep -v "specs/archive\|\.git\|node_modules\|\.gemini\|\.cursor\|validate-doctrine\.sh" | head -5 >&2
+fi
+
+# ── Epic 4: SKILL.md size cap ─────────────────────────────────────────────────
+echo "--- [Epic 4] SKILL.md size cap ---"
+if bash "$REPO_ROOT/scripts/check-skill-size.sh" >/dev/null 2>&1; then
+  pass "all SKILL.md files within tiered size cap (150 critical-path / 120 utility)"
+else
+  fail "a SKILL.md exceeds its size cap — run: bash scripts/check-skill-size.sh"
+  bash "$REPO_ROOT/scripts/check-skill-size.sh" 2>&1 | grep "^FAIL:" >&2 || true
+fi
+
+# ── Summary ────────────────────────────────────────────────────────────────────
+echo "---"
+if [[ "$ERRORS" -eq 0 ]]; then
+  echo "validate-doctrine: ALL checks passed"
+  exit 0
+else
+  echo "validate-doctrine: $ERRORS check(s) FAILED" >&2
+  exit 1
+fi

package/seed-conventions/REFERENCE.md

@@ -0,0 +1,63 @@
+# Seed Conventions — Reference Templates
+
+## Agent config template (CLAUDE.md / GEMINI.md / AGENTS.md)
+
+All three files use the same structure — only the header differs:
+- `CLAUDE.md` → `# [Project Name] — Claude Code`
+- `GEMINI.md` → `# [Project Name] — Gemini CLI`
+- `AGENTS.md` → `# [Project Name] — OpenCode`
+
+```markdown
+# [Project Name] — [Agent]
+
+Read CONVENTIONS.md before any GitHub or git operation.
+
+## Project
+[One sentence description]
+Stack: [language, framework, runtime]
+
+## Commands
+| Action | Command |
+|--------|---------|
+| Run    | `[cmd]` |
+| Test   | `[cmd]` |
+| Build  | `[cmd]` |
+| Lint   | `[cmd]` |
+
+## Architecture
+[1–2 sentences. Key modules and their relationships.]
+
+## Conventions
+- [convention 1]
+- [convention 2]
+
+## Never
+- [hard stop 1]
+- [hard stop 2]
+
+## Agent Rules
+- **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
+- Read specs/ before writing code.
+- All planning and specifications MUST be written to `specs/` (`product/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
+- 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.
+```
+
+## opencode.json template
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [".cursor/rules/*.mdc"]
+}
+```
+
+## CONVENTIONS.md
+
+Use the standard bigpowers CONVENTIONS.md as the base. Fill in the project-specific defensive code categories from the interview answers.
+
+## Stack profile fragments
+
+If the user selected a stack profile, merge the matching `profiles/<name>.md` fragment into the generated `CONVENTIONS.md` under a `## Stack Conventions` section. Profiles supply language-specific commands, architecture patterns, and never-do additions.

package/seed-conventions/SKILL.md

@@ -5,8 +5,7 @@ description: Generate CLAUDE.md and CONVENTIONS.md for a brand-new project throu
 ---
 
 # Seed Conventions
-> **HARD GATE** — **HARD GATE** — Before any new code lands, confirm the project conventions are understood. Ask: 'What does a good commit message look like in this project?'
-
+> **HARD GATE** — Before any new code lands, confirm the project conventions are understood. Ask: 'What does a good commit message look like in this project?'
 
 Bootstrap a new project with the AI agent conventions it needs. Run this once at the start of a greenfield project.
 
@@ -23,196 +22,41 @@ Bootstrap a new project with the AI agent conventions it needs. Run this once at
 Ask the user these questions (one at a time, wait for each answer):
 
 1. **Project name and one-sentence description** — "What is this project? One sentence."
-
 2. **Stack** — "What language, framework, and runtime? (e.g. TypeScript / Next.js / Node 22)"
-
-2b. **Stack profile (optional)** — Offer: `swift`, `typescript-vue`, `node-service`, or none. If chosen, merge the matching fragment from `profiles/<name>.md` into generated `CONVENTIONS.md` (commands, architecture, never-do).
-
-3. **Commands** — "What commands do you use for: run, test, build, lint? I'll document them so agents know how to verify their work."
-
-4. **Architecture** — "Describe the key modules and their relationships in 1–2 sentences. What are the main moving parts?"
-
-5. **Conventions** — "Any naming conventions, file organization rules, or patterns that every contributor (human or agent) must follow?"
-
-6. **Never-do list** — "What are the hard stops? Things an agent must never touch or do in this project?"
-
-7. **Defensive code categories** — "Which of these apply to your project? (Rate limit / Retry with backoff / Circuit breaker / Timeout / Graceful degradation)"
+2b. **Stack profile (optional)** — Offer: `swift`, `typescript-vue`, `node-service`, or none. If chosen, merge the matching fragment from `profiles/<name>.md` into generated `CONVENTIONS.md`.
+3. **Commands** — "What commands do you use for: run, test, build, lint?"
+4. **Architecture** — "Key modules and relationships in 1–2 sentences."
+5. **Conventions** — "Any naming, file organization, or patterns all agents must follow?"
+6. **Never-do list** — "What are the hard stops? Things an agent must never touch?"
+7. **Defensive code categories** — "Which apply? (Rate limit / Retry / Circuit breaker / Timeout / Graceful degradation)"
 
 ## Generate files
 
-After the interview, generate:
-
-### `CLAUDE.md`
-
-```markdown
-# [Project Name] — Claude Code
-
-Read CONVENTIONS.md before any GitHub or git operation.
-
-## Project
-[One sentence description]
-Stack: [language, framework, runtime]
-
-## Commands
-| Action | Command |
-|--------|---------|
-| Run    | `[cmd]` |
-| Test   | `[cmd]` |
-| Build  | `[cmd]` |
-| Lint   | `[cmd]` |
-
-## Architecture
-[1–2 sentences. Key modules and their relationships.]
-
-## Conventions
-- [convention 1]
-- [convention 2]
-
-## Never
-- [hard stop 1]
-- [hard stop 2]
-
-## Agent Rules
-- **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
-- Read specs/ before writing code.
-- All planning and specifications MUST be written to `specs/` (`product/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
-- 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.
-```
-
-### `GEMINI.md`
-
-```markdown
-# [Project Name] — Gemini CLI
-
-Read CONVENTIONS.md before any GitHub or git operation.
-
-## Project
-[One sentence description]
-Stack: [language, framework, runtime]
-
-## Commands
-| Action | Command |
-|--------|---------|
-| Run    | `[cmd]` |
-| Test   | `[cmd]` |
-| Build  | `[cmd]` |
-| Lint   | `[cmd]` |
-
-## Architecture
-[1–2 sentences. Key modules and their relationships.]
-
-## Conventions
-- [convention 1]
-- [convention 2]
-
-## Never
-- [hard stop 1]
-- [hard stop 2]
-
-## Agent Rules
-- **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
-- Read specs/ before writing code.
-- All planning and specifications MUST be written to `specs/` (`product/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
-- 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.
-```
-
-### `AGENTS.md`
-
-```markdown
-# [Project Name] — OpenCode
-
-Read CONVENTIONS.md before any GitHub or git operation.
-
-## Project
-[One sentence description]
-Stack: [language, framework, runtime]
-
-## Commands
-| Action | Command |
-|--------|---------|
-| Run    | `[cmd]` |
-| Test   | `[cmd]` |
-| Build  | `[cmd]` |
-| Lint   | `[cmd]` |
-
-## Architecture
-[1–2 sentences. Key modules and their relationships.]
-
-## Conventions
-- [convention 1]
-- [convention 2]
-
-## Never
-- [hard stop 1]
-- [hard stop 2]
-
-## Agent Rules
-- **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
-- Read specs/ before writing code.
-- All planning and specifications MUST be written to `specs/` (`product/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
-- 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.
-```
-
-### `opencode.json`
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "instructions": [".cursor/rules/*.mdc"]
-}
-```
-
-### `CONVENTIONS.md`
-
-Use the standard bigpowers CONVENTIONS.md template, filling in the project-specific defensive code categories from the interview.
+After the interview, generate each file using the templates in [REFERENCE.md](REFERENCE.md):
+- `CLAUDE.md`, `GEMINI.md`, `AGENTS.md` — from the agent-config template
+- `opencode.json` — from the opencode template
+- `CONVENTIONS.md` — bigpowers standard template + project defensive code categories
 
 ### `specs/` directory
 
-Create the evolved bigpowers directory structure:
-
 ```bash
-mkdir -p specs/product
-mkdir -p specs/product/snapshots
-mkdir -p specs/epics/archive
-mkdir -p specs/tech-architecture
-mkdir -p specs/adr
-mkdir -p specs/verifications
-mkdir -p specs/bugs
-
-# Create empty placeholder files
-touch specs/product/SCOPE_LATEST.yaml
-touch specs/product/VISION_LATEST.yaml
-touch specs/product/GLOSSARY_LATEST.yaml
-touch specs/release-plan.yaml
-touch specs/execution-status.yaml
-touch specs/planning-status.yaml
-touch specs/state.yaml
-touch specs/tech-architecture/tech-stack.md
-touch specs/tech-architecture/security.md
-touch specs/tech-architecture/test.md
-touch specs/tech-architecture/design.md
-touch specs/tech-architecture/REFACTOR_LATEST.md
-touch specs/tech-architecture/IMPACT_LATEST.md
+mkdir -p specs/product specs/product/snapshots specs/epics/archive
+mkdir -p specs/tech-architecture specs/adr specs/verifications specs/bugs
+touch specs/product/SCOPE_LATEST.yaml specs/product/VISION_LATEST.yaml specs/product/GLOSSARY_LATEST.yaml
+touch specs/release-plan.yaml specs/execution-status.yaml specs/planning-status.yaml specs/state.yaml
+touch specs/tech-architecture/tech-stack.md specs/tech-architecture/security.md
+touch specs/tech-architecture/test.md specs/tech-architecture/design.md
+touch specs/tech-architecture/REFACTOR_LATEST.md specs/tech-architecture/IMPACT_LATEST.md
 touch specs/bugs/registry.yaml
-echo "# Specs\n\nAll planning documents for this project. Evolved bigpowers structure (v2.0.0+)." > specs/README.md
+echo "# Specs\n\nAll planning documents for this project." > specs/README.md
 ```
 
-**Note:** `specs/state.yaml.lock` is NOT pre-created — it is acquired and released dynamically during writes to prevent concurrency conflicts.
+**Note:** `specs/state.yaml.lock` is NOT pre-created — acquired/released dynamically.
 
-### Verify
+## Verify
 
 - [ ] CLAUDE.md exists and is populated
 - [ ] CONVENTIONS.md exists and includes specs/ output convention
-- [ ] specs/ directory exists
 - [ ] specs/product/ exists with SCOPE_LATEST.yaml, VISION_LATEST.yaml, GLOSSARY_LATEST.yaml
 - [ ] specs/tech-architecture/ exists with tech-stack.md, security.md, test.md, design.md
 - [ ] specs/verifications/ exists

package/write-document/SKILL.md

@@ -16,7 +16,7 @@ Create high-signal technical documentation that serves as an expert collaborator
 | :--- | :--- |
 | **B**old | Make strong assertions. Define clear boundaries and "Never" rules. No "it might" or "usually." |
 | **M**inimal | High-density, low-filler. **Circuit Breaker**: If the file exceeds 300 lines or the session exceeds 20 turns, you MUST run `terse-mode` and compact state before saving. |
-| **A**ctionable | Link every doc to a verifiable outcome. **Architectural Docs**: Verify via Gherkin features (`specs/audit/features/`) or grep-based structure checks (`grep -c "pattern" file`) that prove the design's *constraints* are present. |
+| **A**ctionable | Link every doc to a verifiable outcome. **Architectural Docs**: Verify via Gherkin features (`specs/verifications/features/`) or grep-based structure checks (`grep -c "pattern" file`) that prove the design's *constraints* are present. |
 | **D**urable | Design for the long-term. **Scalability**: Use "Nested Indexing"—root files link to module-level `GEMINI.md` indexes; do not list individual sub-files in the root. |
 
 ## Process
@@ -27,7 +27,7 @@ Choose the correct BMAD-BigPowers artifact:
 - **Decision Record (ADR)**: For "Why" decisions (saved to `specs/adr/`).
 - **Context Map**: For system-wide architectural mapping (`specs/tech-architecture/tech-stack.md`).
 - **Technical Guide**: For "How-to" with verification (saved to `<module>/REFERENCE.md`).
-- **Behavioral Feature**: Gherkin-style compliance specs (saved to `specs/audit/features/`).
+- **Behavioral Feature**: Gherkin-style compliance specs (saved to `specs/verifications/features/`).
 - **Project README**: Project-facing documentation (saved to `README.md` at project root).
 
 **Cross-Cutting Concerns**: If a doc affects multiple modules, place the authoritative source in the lowest common ancestor directory and use "Delegates" (one-line pointers) in sub-directories to maintain the Single Source of Truth without violating the Stepdown Rule.