bigpowers 2.81.0 → 2.82.0

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.81.0",
+  "version": "2.82.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/CHANGELOG.md

@@ -1,3 +1,16 @@
+# [2.82.0](https://github.com/danielvm-git/bigpowers/compare/v2.81.0...v2.82.0) (2026-07-24)
+
+
+### Bug Fixes
+
+* **e55:** add gemini configuration to extension manifest for AGY CLI discovery ([8c717db](https://github.com/danielvm-git/bigpowers/commit/8c717db2bb85126adcab02354f5ca45da8482b4c))
+* **plan-consistency-check:** stop treating story deliverables as specs ([8d9814a](https://github.com/danielvm-git/bigpowers/commit/8d9814a5ce09e8b8ce563accb785f109dc55b56e))
+
+
+### Features
+
+* **installer:** add interactive setup with BMAD-polished UI ([5ba8da8](https://github.com/danielvm-git/bigpowers/commit/5ba8da851987ac6e856a6efee6e2729d0fab3ec7))
+
 # [2.81.0](https://github.com/danielvm-git/bigpowers/compare/v2.80.0...v2.81.0) (2026-07-23)
 
 

package/CLAUDE.md

@@ -2,11 +2,18 @@
 # 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
 

package/CONVENTIONS.md

@@ -10,9 +10,17 @@
 # story: e45s36
 # story: e27s01
 # story: e29s03
+# story: e54s03
+# story: e55s03
 
 # 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.
+
 ## 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/).
@@ -386,6 +394,44 @@ 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

package/bin/bigpowers.js

@@ -32,21 +32,17 @@ function run(cmd, cwd = ROOT) {
 const cmd = process.argv[2];
 
 if (cmd === 'setup' || cmd === 'install') {
-  console.log(`🚀 bigpowers v${pkg.version} — setting up...\n`);
-  run('bash scripts/sync-skills.sh');
-  run('bash scripts/install.sh');
-  console.log(`\n✅ bigpowers v${pkg.version} setup complete!`);
-  console.log('   Skills installed in ~/.claude/skills/');
-  console.log('   Run again anytime to update: bigpowers setup\n');
-  process.exit(0);
+  // Delegate to interactive installer
+  const setupScript = path.join(ROOT, 'bin', 'setup.js');
+  require(setupScript);
+  return;
 }
 
 if (cmd === 'update') {
-  console.log(`🔄 Updating bigpowers v${pkg.version}...\n`);
-  run('bash scripts/sync-skills.sh');
-  run('bash scripts/install.sh');
-  console.log(`\n✅ bigpowers v${pkg.version} updated!\n`);
-  process.exit(0);
+  // Delegate to interactive installer (same as setup)
+  const setupScript = path.join(ROOT, 'bin', 'setup.js');
+  require(setupScript);
+  return;
 }
 
 if (cmd === 'status') {

package/bin/setup.js

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+// bigpowers setup — interactive installer
+// Combines GSD simplicity with BMAD visual polish.
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { installGlobal, installLocal, uninstallTool, detectExistingInstall } = require('../scripts/lib/install-helpers');
+
+const ROOT = path.resolve(path.dirname(__filename), '..');
+const pkg = require(path.join(ROOT, 'package.json'));
+
+// ── ANSI helpers ─────────────────────────────────────────────────────────────
+const c = {
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+
+// ── ASCII banner ─────────────────────────────────────────────────────────────
+const BANNER = `
+${c.cyan('╔════════════════════════════════════════════════════════════════════════════╗')}
+${c.cyan('║')}                                                                            ${c.cyan('║')}
+${c.cyan('║')}   ${c.bold(c.cyan('██████╗ ██╗ ██████╗ ██████╗  ██████╗ █      █ ███████╗██████╗ ███████╗'))}   ${c.cyan('║')}
+${c.cyan('║')}   ${c.bold(c.cyan('██╔══██╗██║██╔════╝ ██╔══██╗██╔═══██╗█      █ ██╔════╝██╔══██╗██╔════╝'))}   ${c.cyan('║')}
+${c.cyan('║')}   ${c.bold(c.cyan('██████╔╝██║██║  ███╗██████╔╝██║   ██║█  ██  █ █████╗  ██████╔╝███████╗'))}   ${c.cyan('║')}
+${c.cyan('║')}   ${c.bold(c.cyan('██╔══██╗██║██║   ██║██╔═══╝ ██║   ██║█ ████ █ ██╔══╝  ██╔══██╗╚════██║'))}   ${c.cyan('║')}
+${c.cyan('║')}   ${c.bold(c.cyan('██████╔╝██║╚██████╔╝██║     ╚██████╔╝███  ███ ███████╗██║  ██║███████║'))}   ${c.cyan('║')}
+${c.cyan('║')}   ${c.bold(c.cyan('╚═════╝ ╚═╝ ╚═════╝ ╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚══════╝╚═╝  ╚═╝╚══════╝'))}   ${c.cyan('║')}
+${c.cyan('║')}                                                                            ${c.cyan('║')}
+${c.cyan('║')}           ${c.dim('Spec-Driven & Test-First Skills for Solo Developers')}              ${c.cyan('║')}
+${c.cyan('║')}           ${c.dim(`v${pkg.version}`)}                                                          ${c.cyan('║')}
+${c.cyan('╚════════════════════════════════════════════════════════════════════════════╝')}
+`;
+
+// ── Tool definitions ─────────────────────────────────────────────────────────
+const TOOLS = [
+  { id: 'claude', name: 'Claude Code', globalPath: '~/.claude', localPath: '.claude' },
+  { id: 'antigravity', name: 'Antigravity', globalPath: '~/.gemini/antigravity', localPath: '.gemini/antigravity' },
+  { id: 'augment', name: 'Augment', globalPath: '~/.augment', localPath: '.augment' },
+  { id: 'cline', name: 'Cline', globalPath: '.clinerules', localPath: '.clinerules' },
+  { id: 'codebuddy', name: 'CodeBuddy', globalPath: '~/.codebuddy', localPath: '.codebuddy' },
+  { id: 'codex', name: 'Codex', globalPath: '~/.codex', localPath: '.codex' },
+  { id: 'copilot', name: 'Copilot', globalPath: '~/.copilot', localPath: '.copilot' },
+  { id: 'cursor', name: 'Cursor', globalPath: '~/.cursor', localPath: '.cursor' },
+  { id: 'gemini', name: 'Gemini', globalPath: '~/.gemini', localPath: '.gemini' },
+  { id: 'hermes', name: 'Hermes Agent', globalPath: '~/.hermes', localPath: '.hermes' },
+  { id: 'kilo', name: 'Kilo', globalPath: '~/.config/kilo', localPath: '.config/kilo' },
+  { id: 'opencode', name: 'OpenCode', globalPath: '~/.config/opencode', localPath: '.config/opencode' },
+  { id: 'qwen', name: 'Qwen Code', globalPath: '~/.qwen', localPath: '.qwen' },
+  { id: 'trae', name: 'Trae', globalPath: '~/.trae', localPath: '.trae' },
+  { id: 'windsurf', name: 'Windsurf', globalPath: '~/.codeium/windsurf', localPath: '.codeium/windsurf' },
+];
+const ALL_ID = '__all__';
+const SUPPORTED_IDS = new Set(['claude', 'gemini', 'pi', 'cursor', 'codex']);
+const UNSUPPORTED_HINT = '(TODO)';
+
+// ── clack helpers (lazy ESM import from CJS) ─────────────────────────────────
+let _clack;
+async function clack() {
+  if (!_clack) _clack = await import('@clack/prompts');
+  return _clack;
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function runInherited(cmd) {
+  execSync(cmd, { cwd: ROOT, stdio: 'inherit' });
+}
+
+
+
+// ── Uninstall flow ──────────────────────────────────────────────────────────
+async function handleUninstall() {
+  const { multiselect: ms, confirm: cf, spinner: sp, outro: ot, isCancel: ic } = await clack();
+
+  const toolOptions = TOOLS.filter((t) => SUPPORTED_IDS.has(t.id)).map((tool) => {
+    return { value: tool.id, label: tool.name, hint: `(${tool.globalPath})` };
+  });
+
+  const selectedToolIds = await ms({
+    message: 'Uninstall from which tools?',
+    options: toolOptions,
+    initialValues: ['claude'],
+    required: true,
+  });
+
+  if (ic(selectedToolIds)) {
+    ot('Cancelled.');
+    process.exit(0);
+  }
+
+  const yes = await cf({
+    message: `Remove symlinks from ${selectedToolIds.length} tool${selectedToolIds.length > 1 ? 's' : ''}?`,
+    initialValue: true,
+  });
+
+  if (!yes || ic(yes)) {
+    ot('Cancelled.');
+    process.exit(0);
+  }
+
+  const s = await sp();
+  s.start('Removing...');
+
+  const results = [];
+  for (const toolId of selectedToolIds) {
+    const tool = TOOLS.find((t) => t.id === toolId);
+    try {
+      uninstallTool(toolId, ROOT);
+      results.push({ name: tool.name, ok: true });
+    } catch (err) {
+      results.push({ name: tool.name, ok: false, error: err.message });
+    }
+  }
+
+  s.stop('Done.');
+
+  console.log('');
+  for (const r of results) {
+    const icon = r.ok ? c.green('✓') : c.red('✗');
+    const detail = r.ok ? c.dim('removed') : c.red(r.error);
+    console.log(`  ${icon} ${r.name} — ${detail}`);
+  }
+  console.log('');
+
+  ot('Uninstall complete.');
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+  const { intro, outro, select, multiselect, spinner, confirm, isCancel } = await clack();
+
+  console.log(BANNER);
+  intro(c.bold(`bigpowers v${pkg.version}`));
+
+  // ── Step 0: Detect existing install ────────────────────────────────────
+  const hasExisting = detectExistingInstall();
+  let mode = 'install';
+
+  if (hasExisting) {
+    mode = await select({
+      message: 'Existing installation detected. How would you like to proceed?',
+      options: [
+        { value: 'install', label: 'Setup / Update', hint: '(reinstall or add tools)' },
+        { value: 'uninstall', label: 'Uninstall', hint: '(remove symlinks and hooks)' },
+      ],
+    });
+
+    if (isCancel(mode)) {
+      outro('Cancelled.');
+      process.exit(0);
+    }
+  }
+
+  if (mode === 'uninstall') {
+    await handleUninstall(clack);
+    return;
+  }
+
+  // ── Step 1: Global vs Local ──────────────────────────────────────────────
+  const installMode = await select({
+    message: 'Where would you like to install?',
+    options: [
+      { value: 'global', label: 'Global', hint: '(~/.claude/skills/) — available in all projects' },
+      { value: 'local', label: 'Local', hint: '(./.claude/skills/) — this project only' },
+    ],
+  });
+
+  if (isCancel(installMode)) {
+    outro('Setup cancelled.');
+    process.exit(0);
+  }
+
+  // ── Step 2: Tool selection ─────────────────────────────────────────────
+  const toolOptions = TOOLS.map((tool) => {
+    const p = installMode === 'global' ? tool.globalPath : tool.localPath;
+    const supported = SUPPORTED_IDS.has(tool.id);
+    return {
+      value: tool.id,
+      label: supported ? tool.name : c.dim(tool.name),
+      hint: supported ? `(${p})` : c.dim(`${UNSUPPORTED_HINT} ${p}`),
+    };
+  });
+
+  let selectedToolIds = await multiselect({
+    message: 'Install for which tools?',
+    options: toolOptions,
+    initialValues: ['claude'],
+    required: true,
+  });
+
+  if (isCancel(selectedToolIds)) {
+    outro('Setup cancelled.');
+    process.exit(0);
+  }
+
+  // Filter out TODO tools — they can't be installed yet
+  const selectedTools = selectedToolIds.filter((id) => SUPPORTED_IDS.has(id));
+  const todoSkipped = selectedToolIds.filter((id) => !SUPPORTED_IDS.has(id));
+  if (todoSkipped.length > 0) {
+    const names = todoSkipped.map((id) => TOOLS.find((t) => t.id === id)?.name || id);
+    console.log(`\n  ${c.dim('TODO (not yet implemented):')} ${names.join(', ')}`);
+  }
+  if (selectedTools.length === 0) {
+    console.log(`\n  ${c.red('No supported tools selected.')}`);
+    outro('Setup cancelled.');
+    process.exit(0);
+  }
+
+  // ── Step 3: Confirm ───────────────────────────────────────────────────
+  const skillsDir = path.join(ROOT, 'skills');
+  const skillCount = fs
+    .readdirSync(skillsDir)
+    .filter((d) => fs.existsSync(path.join(skillsDir, d, 'SKILL.md'))).length;
+
+  const yes = await confirm({
+    message: `Install ${skillCount} skills to ${selectedTools.length} runtime${selectedTools.length > 1 ? 's' : ''}?`,
+    initialValue: true,
+  });
+
+  if (!yes || isCancel(yes)) {
+    outro('Setup cancelled.');
+    process.exit(0);
+  }
+
+  // ── Step 4: Install ───────────────────────────────────────────────────
+  const s = await spinner();
+  s.start('Preparing installation...');
+  await sleep(200);
+
+  s.message('Syncing skills...');
+  try {
+    runInherited('bash scripts/sync-skills.sh');
+  } catch {
+    s.error('Sync failed.');
+    process.exit(1);
+  }
+
+  const results = [];
+  for (const toolId of selectedTools) {
+    const tool = TOOLS.find((t) => t.id === toolId);
+    const p = installMode === 'global' ? tool.globalPath : tool.localPath;
+
+    s.message(`Installing ${tool.name}...`);
+    await sleep(300);
+
+    try {
+      if (installMode === 'global') {
+        installGlobal(tool, ROOT);
+      } else {
+        installLocal(tool, ROOT);
+      }
+      results.push({ name: tool.name, path: p, ok: true });
+    } catch (err) {
+      results.push({ name: tool.name, path: p, ok: false, error: err.message });
+    }
+  }
+
+  s.stop('Installation complete.');
+
+  // ── Step 5: Results ────────────────────────────────────────────────────
+  console.log('');
+  for (const r of results) {
+    const icon = r.ok ? c.green('✓') : c.red('✗');
+    const detail = r.ok ? c.dim(r.path) : c.red(r.error);
+    console.log(`  ${icon} ${r.name} — ${detail}`);
+  }
+  console.log('');
+
+  const allOk = results.every((r) => r.ok);
+  if (allOk) {
+    outro(`bigpowers installed. ${c.dim('Run bigpowers update anytime.')}`);
+  } else {
+    outro('Some installations failed. Check errors above.');
+    process.exit(1);
+  }
+}
+
+// ── Run ──────────────────────────────────────────────────────────────────────
+main().catch((err) => {
+  console.error(`${c.red('Error:')} ${err.message}`);
+  process.exit(1);
+});

package/constitution.md

@@ -0,0 +1,217 @@
+# bigpowers Constitution
+
+<!-- story: e55s02 -->
+
+> **Status:** consolidated entry point for bigpowers' doctrine, built from a
+> full audit of every current rule source
+> (`specs/epics/e55-extract-constitution/e55s01-doctrine-mapping.md`).
+>
+> **Authority:** this file is where a reader starts. It does **not** yet
+> replace `CLAUDE.md` or `CONVENTIONS.md` — both remain fully authoritative in
+> their own right today. Each block below synthesizes what those files (and
+> the supporting `docs/references/*.md` sources) currently say, with citations
+> to the fuller text rather than a full copy of it, so this file doesn't
+> become a second place the same rule can drift out of sync.
+>
+> This file has no `constitution_version` or amendment scheme — that
+> compatibility-tracking mechanism is a later concern (e59, absorb-fresh-
+> references), not something this story invents ahead of schedule.
+>
+> Structure follows bigspec's 11 blocks (B0–B10) plus a Capstone category, used
+> here purely as an organizing skeleton (`specs/reborn-constitution.md` Part I),
+> not as a source of content — every claim below is about what *this* repo's
+> doctrine actually says today.
+
+---
+
+## B0 · Token/Context Substrate
+
+Content is written to be consumed by an agent under a real token budget, not
+skimmed by a human. Files stay under size caps so they fit a single context
+window; skills load progressively (frontmatter → summary → detail) instead of
+being read in full up front; `verify:` commands are one-line and runnable.
+
+- 300-line file cap, `SKILL.md` size caps — `CONVENTIONS.md` §Code Style, `docs/PRINCIPLES.md` §5/§8
+- Context Routing (load by glob, not the full doc tree) — `CLAUDE.md`
+- Token Economy, high-density skill descriptions — `docs/PRINCIPLES.md` §5, `docs/references/akita.md`
+- Full progressive-disclosure framework, `bts_map`/`bts_compress`/`sqz`/`rtk` tooling — `docs/references/context-engineering.md`
+- `terse-mode` past ~20 turns — `CONVENTIONS.md` §Risk Tiers (`terse-when-heavy`)
+
+## B1 · Agent-Grade Craftsmanship
+
+The code floor: functions 4–20 lines, files under 300 lines, one responsibility
+per module, names specific enough that `grep` returns under 5 hits, no
+duplication, exceptions over error codes, dead code deleted not commented out,
+Boy Scout Rule, Law of Demeter, error messages that carry a remediation hint.
+
+- Full Code Style, Comments, Dependencies, Structure, Formatting, Logging sections — `CONVENTIONS.md`
+- SRP, Boy Scout Rule, intention-revealing names — `docs/PRINCIPLES.md` §1
+- Deep modules, information hiding — `docs/PRINCIPLES.md` §2, `docs/references/ousterhout.md`, `docs/references/pocock.md`
+- Grep-ability, structured observability, remediation hints — `docs/PRINCIPLES.md` §5, `docs/references/akita.md`
+- SOLID, DRY, refactoring catalog, seams for testability — `docs/references/sandi-metz.md`, `docs/references/fowler.md`, `docs/references/uncle-bob.md`, `docs/references/feathers.md`, `docs/references/pragmatic-programmer.md`, `docs/references/rich-hickey.md`
+- Conventional Commits message mechanics — `docs/references/git-integration.md`
+
+## B2 · Think-First Behavior
+
+Understand before acting; act minimally. Assumptions get surfaced before code
+is written, ambiguous requests get multiple readings named explicitly, and
+edits stay surgical — touching only what the task requires.
+
+- Session Start read order, "minimum code", "one clarifying question beats a wrong assumption" — `CLAUDE.md`
+- Think First, Zoom-Out Strategy, Surgical Edits — `docs/PRINCIPLES.md` §3
+- Zoom-out mandate, `define-success` hard gate, "we'll decide during code" red flag — `docs/references/orchestration.md`, `docs/references/workflow-steps.md`
+- Tidy First?, tracer bullets, good-enough software — `docs/references/kent-beck.md`, `docs/references/pragmatic-programmer.md`
+- System 1 vs System 2 thinking, model-escalation cost-benefit — `docs/references/thinking-models.md`
+- Domain probes (`grill-me`), model-domain invariant grilling — `docs/references/domain-probes.md`, `docs/references/ddd.md`
+
+## B3 · The Skill Primitive
+
+A skill is a verb-noun procedure, not a class of code. Every critical-path
+skill writes `handoff.next_skill` as its last action so work can resume
+anywhere it stopped.
+
+- Workflow Mandate: route work through bigpowers skills, never write code directly — `CLAUDE.md`, `CONVENTIONS.md` §Agent Workflow Mandates
+- Skill Naming, Tombstone Aliases, next_skill signaling mandate — `CONVENTIONS.md`
+- Skill-Based Architecture, zoom-out mandate — `docs/PRINCIPLES.md` §3
+- `seed-conventions` bootstrap, `survey-context` phase mapping — `docs/references/agent-config-files-and-okf.md`, `docs/references/workflow-steps.md`
+
+## B4 · Spec-as-Contract
+
+The spec is the source of truth, not the chat history. `plan-work` produces
+`verify:`-bearing tasks before any feature code is written; a story only
+counts as done once `verify-work` confirms it against those criteria.
+
+- `plan-work` before feature code, UAT sign-off mandate, delta-tag requirement — `CONVENTIONS.md` §Agent Workflow Mandates
+- Intent/delivery/execution file ownership table — `CONVENTIONS.md` §specs/
+- SDD, BDD/Gherkin as the link — `docs/PRINCIPLES.md` §4, `docs/references/wasowski.md`
+- Ubiquitous Language, information-first design — `docs/references/pocock.md`, `docs/references/rich-hickey.md`
+- Story maturity/INVEST gates, NFR Gate pattern, structured-spec pattern — `docs/references/bcp.md`, `docs/references/bcp-plus.md`, `docs/references/spec-kit.md`
+- Bounded context, context mapping, `define-language` — `docs/references/ddd.md`
+
+## B5 · Risk-Tiered Verification
+
+Proof is proportionate to risk. Every story is tagged P0–P3 at plan time; that
+tier picks how much verification it gets — full multi-phase UAT for P0, down
+to typecheck-and-lint for P3.
+
+- Full Risk Tiers (P0–P3) table, Tests (F.I.R.S.T) — `CONVENTIONS.md` §Risk Tiers, §Tests
+- F.I.R.S.T Testing — `docs/PRINCIPLES.md` §1, `docs/references/kent-beck.md`, `docs/references/uncle-bob.md`, `docs/references/tdd.md`, `docs/references/wasowski.md` *(stated in at least 5 sources — a live duplication instance, not evidence of 5 distinct rules)*
+- P0–P3 risk-based test-depth tables — `docs/references/bmad.md`, `docs/references/tea.md`
+- Boundary conditions, public-interface-only testing (T4/T5/T8), ≥95% coverage, NFR Evidence Audit — `docs/references/tdd.md`, `docs/references/bmad.md`, `docs/references/tea.md`
+- OKF validation gates on structure/provenance, never a value — `docs/references/okf.md`
+- Slopcheck [OK]/[SUS]/[SLOP], supply-chain and security-audit checklists — `docs/references/security-threats.md`
+
+## B6 · Gates & Hard-Stops
+
+Forward progress blocks until conditions are met — Preflight and CI must be
+green before any forward work, and any reproducible gate failure is a
+discovered defect, not something to note and move past.
+
+- Always Green / Shift Left, Discovered Defects fix-or-log ladder, banned dismissive phrases — `CONVENTIONS.md` §Always Green, §Discovered Defects
+- Hard Gates — `docs/PRINCIPLES.md` §6
+- Broken Windows, quality-score gate, review workflow gate — `docs/references/pragmatic-programmer.md`, `docs/references/code-review.md`
+- Checkpoint state machine, safety checkpoints, never-auto-merge — `docs/references/checkpoints.md`, `docs/references/git-integration.md`
+- 6-phase Confirm-gates, deviation-from-plan red flag, mode-scaled strictness — `docs/references/orchestration.md`, `docs/references/orchestration-modes.md`
+- Full Traceability Gate pipeline (coverage matrix, blind-spot categories, PASS/CONCERNS/FAIL/WAIVED verdicts) — `docs/references/traceability-gate.md`
+- Four gate types (Confirm/Quality/Safety/Transition) — `docs/references/gates.md`
+
+**Today's proof mechanism, described honestly:** the actual gate that runs on
+every `npm run compliance` invocation is a Gherkin-based self-compliance suite
+with a 94% pass threshold (`docs/PRINCIPLES.md` §6/§7, `CLAUDE.md` §Commands,
+`docs/references/gates.md`). This is what genuinely exists and gates merges
+today. `specs/reborn-constitution.md`'s Capstone block describes a *target*
+state where outcome evals (with-skill vs without-skill delta) replace this
+threshold — that replacement is **e58's job (evals-over-compliance), not yet
+built**. The 94% Gherkin gate is not deprecated; it is the live mechanism
+until e58 ships something to replace it with.
+
+## B7 · Context Isolation
+
+Context rot is the primary failure mode of long agentic sessions. The fix is
+fresh-context subagents with file-based handoff, not a bigger prompt —
+`state.yaml` tracks precise session state so any interruption can resume
+exactly where it stopped.
+
+- Token Management (Write/Select/Compress/Isolate, effort classification) — `CLAUDE.md`
+- Session Governance via `state.yaml`/`release-plan.yaml` — `docs/PRINCIPLES.md` §6
+- Model-escalation to fresh-context subagents — `docs/references/thinking-models.md`
+- Handoff-contract principle, `dispatch-agents`/`delegate-task` scoped file access, `kickoff-branch` worktree isolation, `agent-locks.yaml` concurrency — `docs/references/context-engineering.md`
+- `state.yaml` tracking, resume-via-survey-context, stale-lock detection — `docs/references/gsd.md`, `docs/references/semantic-context-bridge.md`
+
+## B8 · Self-Describing Artifacts
+
+Every planning artifact has exactly one owning file — `specs/execution-status.yaml`
+is the sole source of truth for story status, `specs/release-plan.yaml` for
+epic ordering, and so on. Generated artifacts (`.cursor/`, `.gemini/`,
+`.pi/`, `website/`) are never hand-edited; their `SKILL.md` sources are.
+
+- Full specs/ ownership model, Documentation Responsibilities table, Generated artifact targets, docs/references SSOT Sync — `CONVENTIONS.md` §specs/
+- Never-edit-generated-artifacts, single-source-of-truth `SKILL.md` — `CLAUDE.md`
+- OKF bundle frontmatter (`okf_kind`/`okf_version`/provenance), kind-aware validation, "gate on pipeline not value" — `docs/references/okf.md`
+- CLAUDE.md/AGENTS.md dual-pattern — `docs/references/agent-config-files-and-okf.md`
+- Skill graph, OKF wiki bundle, targets-registry as the single Integration Registry — `docs/references/semantic-context-bridge.md`, `docs/references/targets-registry.md`
+
+*Note: `docs/references/okf.md` describes OKF-bundle conformance as achievable
+"if all `SKILL.md` files add frontmatter fields" — that's a conditional, not a
+claim that every generated file already carries this envelope today. Making
+that universal across the whole `specs/` tree is e57's job (adopt-okf-envelope),
+not yet built.*
+
+## B9 · Effort Accounting (BCP)
+
+BCP (Business Complexity Points) sizes a story before it's built, from a
+6-step method summing per-element Fibonacci scores. It lives at the story
+level only — there is no per-task `[BCP N]` annotation in the current method.
+
+- Full BCP accounting mandate, Timestamp mandate, story-level-only rule — `CONVENTIONS.md` §BCP accounting mandate, §Timestamp mandate
+- `effort:` frontmatter (light/standard/heavy) — `docs/references/context-engineering.md`, `docs/references/model-profiles.md`
+- 6-step sizing method, size bands, velocity tracking — `docs/references/bcp.md`
+- BCP-Plus 13-dimension framework — `docs/references/bcp-plus.md`
+
+*Note: some older docs (`docs/references/workflow-artifacts.md`,
+`docs/references/orchestration.md`) still reference a per-task `[BCP N]` tag
+convention that `CONVENTIONS.md` has since superseded — a live drift instance
+this consolidation surfaces rather than resolves. Resolving it is a
+`docs/references` sync task, not this story's job.*
+
+## B10 · The Synthesis
+
+The 6-phase core loop — Discover → Elaborate → Plan → Build → Verify →
+Release — runs at project, epic, and story scope alike. *Sustain* is a
+session-flow state, not a seventh lifecycle phase.
+
+- 6-Phase Lifecycle, Hard Gates, 94% threshold — `docs/PRINCIPLES.md` §6
+- Same 6-phase loop, `orchestrate-project` phase sequencing — `docs/references/orchestration.md`, `docs/references/workflow-steps.md`
+- BMAD's Discover→Elaborate→Plan→Build→Sustain arc, TEA's workflows, SDD lifecycle integration — `docs/references/bmad.md`, `docs/references/tea.md`, `docs/references/wasowski.md`
+
+## ★ Capstone · Outcome Evals
+
+The foundation should prove it produces better software, not just that it
+follows its own rules. Bigpowers doesn't have this yet in the target form —
+what exists today is described honestly in B6 above: a 94% Gherkin
+self-compliance gate. `reborn-constitution.md`'s Capstone block names the
+target (with-skill vs without-skill delta, pass@k + token cost) as what
+**e58 (evals-over-compliance)** is expected to build. Until then:
+
+- Request-review checklist / quality-score gate as today's closest analog — `docs/references/code-review.md`
+- Human-in-the-loop UAT mandate after every story — `docs/references/spec-kit.md`
+- `run-evals` + regression UAT phase, `specs/EVALS-<feature>.md` — `docs/references/workflow-steps.md`, `docs/references/workflow-artifacts.md`
+
+---
+
+## What this file deliberately doesn't do (yet)
+
+- **No content migration.** Full rule text stays in `CONVENTIONS.md`,
+  `CLAUDE.md`, `docs/PRINCIPLES.md`, and `docs/references/*.md`. Moving
+  rule-classified content in is e56's job (reclassify-catalog) — this file
+  only builds the destination structure.
+- **No cross-references back from `CLAUDE.md`/`CONVENTIONS.md` yet.** Those
+  files don't point here yet; that's e55s03.
+- **No amendment/versioning scheme.** `constitution_version`, SemVer bumps,
+  and ADR-gated amendments are e59's job (absorb-fresh-references).
+- **No universal OKF envelope claim.** Not every generated file in this repo
+  carries `okf_kind`/`okf_version` frontmatter yet — that's e57's job
+  (adopt-okf-envelope).
+- **No `count-bcp` skill.** BCP sizing today is the 6-step method in
+  `docs/references/bcp.md`, applied by hand during `plan-work`/`plan-release` —
+  not a dedicated skill or kernel module.

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "bigpowers",
-  "version": "2.81.0",
+  "version": "2.82.0",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {
+    "setup": "node bin/setup.js",
     "compliance": "bash scripts/audit-compliance.sh specs/verifications/features && bash scripts/validate-doctrine.sh && python3 scripts/check-skill-links.py",
     "doctrine": "bash scripts/validate-doctrine.sh",
     "sync": "bash scripts/sync-skills.sh",
@@ -47,11 +48,16 @@
   },
   "bin": {
     "bigpowers": "./bin/bigpowers.js",
+    "bigpowers-setup": "./bin/setup.js",
     "bigpowers-dashboard": "./dashboard/bin/dashboard.js"
   },
   "engines": {
     "node": ">=14.0.0"
   },
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "picocolors": "^1.1.1"
+  },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/exec": "^7.1.0",

package/scripts/lib/install-helpers.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// install-helpers.js — symlink helpers for bigpowers setup
+
+const fs = require('fs');
+const path = require('path');
+
+function linkSkills(skillsDir, targetDir) {
+  for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (!fs.existsSync(path.join(skillsDir, entry.name, 'SKILL.md'))) continue;
+
+    const src = path.join(skillsDir, entry.name);
+    const dst = path.join(targetDir, entry.name);
+
+    try {
+      const stat = fs.lstatSync(dst);
+      if (stat.isSymbolicLink()) fs.unlinkSync(dst);
+    } catch {}
+
+    fs.symlinkSync(src, dst);
+  }
+}
+
+function linkDir(src, dst) {
+  try {
+    const stat = fs.lstatSync(dst);
+    if (stat.isSymbolicLink()) fs.unlinkSync(dst);
+  } catch {}
+  fs.symlinkSync(src, dst);
+}
+
+function linkFile(src, dst) {
+  try {
+    const stat = fs.lstatSync(dst);
+    if (stat.isSymbolicLink()) fs.unlinkSync(dst);
+  } catch {}
+  fs.symlinkSync(src, dst);
+}
+
+function linkHook(src, dst) {
+  if (!fs.existsSync(src)) return;
+  try {
+    const stat = fs.lstatSync(dst);
+    if (stat.isSymbolicLink()) fs.unlinkSync(dst);
+  } catch {}
+  fs.symlinkSync(src, dst);
+  try { fs.chmodSync(src, 0o755); } catch {}
+}
+
+// ── Install per tool ─────────────────────────────────────────────────────────
+
+function installGlobal(tool, repoRoot) {
+  const homeDir = require('os').homedir();
+  const skillsDir = path.join(repoRoot, 'skills');
+
+  switch (tool.id) {
+    case 'claude': {
+      const targetDir = path.join(homeDir, '.claude', 'skills');
+      fs.mkdirSync(targetDir, { recursive: true });
+      linkSkills(skillsDir, targetDir);
+
+      const hooksDir = path.join(homeDir, '.claude', 'hooks');
+      fs.mkdirSync(hooksDir, { recursive: true });
+      linkHook(
+        path.join(repoRoot, 'guard-git', 'scripts', 'block-dangerous-git.sh'),
+        path.join(hooksDir, 'block-dangerous-git.sh')
+      );
+      linkHook(
+        path.join(repoRoot, 'scripts', 'hooks', 'rtk-rewrite.sh'),
+        path.join(hooksDir, 'rtk-rewrite.sh')
+      );
+      break;
+    }
+    case 'gemini': {
+      const extSrc = path.join(repoRoot, '.gemini', 'extensions', 'bigpowers');
+      const extDst = path.join(homeDir, '.gemini', 'config', 'plugins', 'bigpowers');
+      fs.mkdirSync(path.dirname(extDst), { recursive: true });
+      linkDir(extSrc, extDst);
+      break;
+    }
+    case 'pi': {
+      const targetDir = path.join(homeDir, '.pi', 'agent', 'skills');
+      fs.mkdirSync(targetDir, { recursive: true });
+      linkSkills(skillsDir, targetDir);
+      break;
+    }
+    case 'cursor': {
+      const rulesSrc = path.join(repoRoot, '.cursor', 'rules');
+      const rulesDst = path.join(homeDir, '.cursor', 'rules');
+      fs.mkdirSync(path.dirname(rulesDst), { recursive: true });
+      linkDir(rulesSrc, rulesDst);
+      break;
+    }
+    case 'codex': {
+      const templatePath = path.join(repoRoot, 'templates', 'codex', 'AGENTS.md');
+      const targetPath = path.join(homeDir, '.codex', 'AGENTS.md');
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      linkFile(templatePath, targetPath);
+      break;
+    }
+  }
+}
+
+function installLocal(tool, repoRoot) {
+  const skillsDir = path.join(repoRoot, 'skills');
+  const cwd = process.cwd();
+
+  switch (tool.id) {
+    case 'claude': {
+      const targetDir = path.join(cwd, '.claude', 'skills');
+      fs.mkdirSync(targetDir, { recursive: true });
+      linkSkills(skillsDir, targetDir);
+      break;
+    }
+    case 'gemini': {
+      const extSrc = path.join(repoRoot, '.gemini', 'extensions', 'bigpowers');
+      const extDst = path.join(cwd, '.gemini', 'extensions', 'bigpowers');
+      fs.mkdirSync(path.dirname(extDst), { recursive: true });
+      linkDir(extSrc, extDst);
+      break;
+    }
+    case 'pi': {
+      const targetDir = path.join(cwd, '.pi', 'agent', 'skills');
+      fs.mkdirSync(targetDir, { recursive: true });
+      linkSkills(skillsDir, targetDir);
+      break;
+    }
+    case 'cursor': {
+      const rulesSrc = path.join(repoRoot, '.cursor', 'rules');
+      const rulesDst = path.join(cwd, '.cursor', 'rules');
+      fs.mkdirSync(path.dirname(rulesDst), { recursive: true });
+      linkDir(rulesSrc, rulesDst);
+      break;
+    }
+    case 'codex': {
+      const templatePath = path.join(repoRoot, 'templates', 'codex', 'AGENTS.md');
+      const targetPath = path.join(cwd, '.codex', 'AGENTS.md');
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      linkFile(templatePath, targetPath);
+      break;
+    }
+  }
+}
+
+// ── Uninstall per tool ───────────────────────────────────────────────────────
+
+function uninstallTool(toolId, repoRoot) {
+  const homeDir = require('os').homedir();
+
+  switch (toolId) {
+    case 'claude': {
+      const skillsDir = path.join(homeDir, '.claude', 'skills');
+      if (fs.existsSync(skillsDir)) {
+        for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+          if (!entry.isSymbolicLink()) continue;
+          const target = fs.readlinkSync(path.join(skillsDir, entry.name));
+          if (target.includes('bigpowers')) {
+            removeSymlink(path.join(skillsDir, entry.name));
+          }
+        }
+      }
+      const hooksDir = path.join(homeDir, '.claude', 'hooks');
+      removeSymlink(path.join(hooksDir, 'block-dangerous-git.sh'));
+      removeSymlink(path.join(hooksDir, 'rtk-rewrite.sh'));
+      break;
+    }
+    case 'gemini':
+      removeSymlink(path.join(homeDir, '.gemini', 'config', 'plugins', 'bigpowers'));
+      break;
+    case 'pi': {
+      const skillsDir = path.join(homeDir, '.pi', 'agent', 'skills');
+      if (fs.existsSync(skillsDir)) {
+        for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+          if (!entry.isSymbolicLink()) continue;
+          const target = fs.readlinkSync(path.join(skillsDir, entry.name));
+          if (target.includes('bigpowers')) {
+            removeSymlink(path.join(skillsDir, entry.name));
+          }
+        }
+      }
+      break;
+    }
+    case 'cursor':
+      removeSymlink(path.join(homeDir, '.cursor', 'rules'));
+      break;
+    case 'codex':
+      removeSymlink(path.join(homeDir, '.codex', 'AGENTS.md'));
+      break;
+  }
+}
+
+function removeSymlink(p) {
+  try {
+    const stat = fs.lstatSync(p);
+    if (stat.isSymbolicLink()) {
+      fs.unlinkSync(p);
+      return true;
+    }
+  } catch {}
+  return false;
+}
+
+function detectExistingInstall() {
+  const homeDir = require('os').homedir();
+  const marker = path.join(homeDir, '.claude', 'skills', 'survey-context');
+  try {
+    const stat = fs.lstatSync(marker);
+    return stat.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  linkSkills,
+  linkDir,
+  linkFile,
+  linkHook,
+  installGlobal,
+  installLocal,
+  uninstallTool,
+  removeSymlink,
+  detectExistingInstall,
+};

package/scripts/lib/plan-consistency-check.sh

@@ -51,26 +51,29 @@ shopt -u nullglob
 (( ${#SPECS[@]} > 0 )) || report CRITICAL "No story spec .md files in capsule (run slice-tasks first)"
 (( ${#TASKS[@]} > 0 )) || report CRITICAL "No *-tasks.yaml files in capsule (run plan-work first)"
 
+# A story's real spec is whatever its own tasks.yaml declares via `spec:` —
+# not every e*s*.md file, which also matches non-spec deliverables a story
+# produces (e.g. an audit story's own eNNsYY-<slug>.md output document).
 SPEC_IDS=()
-for spec in "${SPECS[@]+"${SPECS[@]}"}"; do
-  base="$(basename "$spec" .md)"
-  sid="$(echo "$base" | grep -oE 'e[0-9]+s[0-9]+' | head -1)"
-  [[ -n "$sid" ]] || continue
-  SPEC_IDS+=("$sid")
-  in_array "$sid" "${EPIC_STORIES[@]+"${EPIC_STORIES[@]}"}" \
-    || report HIGH "Story $sid in spec file but missing from epic.yaml manifest"
-  grep -qE '^#{2,3} (17\.|Acceptance|Verification Script)' "$spec" \
-    || report HIGH "Story $sid spec missing §17 acceptance criteria or Verification Script"
-  grep -qiE 'ambiguous|TBD|TODO|FIXME' "$spec" \
-    && report MED "Story $sid spec contains ambiguous/TBD markers"
-done
-
 for tasks in "${TASKS[@]+"${TASKS[@]}"}"; do
   base="$(basename "$tasks" -tasks.yaml)"
   sid="$(echo "$base" | grep -oE 'e[0-9]+s[0-9]+' | head -1)"
   [[ -n "$sid" ]] || continue
-  in_array "$sid" "${SPEC_IDS[@]+"${SPEC_IDS[@]}"}" \
-    || report CRITICAL "tasks.yaml for $sid without matching story spec .md"
+
+  spec_name="$(grep -E '^spec:' "$tasks" | head -1 | sed -E 's/^spec:[[:space:]]*//; s/^"(.*)"$/\1/')"
+  spec="$CAPSULE/$spec_name"
+  if [[ -z "$spec_name" || ! -f "$spec" ]]; then
+    report CRITICAL "Story $sid tasks.yaml declares no valid spec: file"
+  else
+    SPEC_IDS+=("$sid")
+    in_array "$sid" "${EPIC_STORIES[@]+"${EPIC_STORIES[@]}"}" \
+      || report HIGH "Story $sid in spec file but missing from epic.yaml manifest"
+    grep -qE '^#{2,3} (17\.|Acceptance|Verification Script)' "$spec" \
+      || report HIGH "Story $sid spec missing §17 acceptance criteria or Verification Script"
+    grep -qiE 'ambiguous|TBD|TODO|FIXME' "$spec" \
+      && report MED "Story $sid spec contains ambiguous/TBD markers"
+  fi
+
   grep -qE '^[[:space:]]*verify:' "$tasks" \
     || report CRITICAL "Story $sid tasks.yaml missing runnable verify: commands"
   grep -qE '^status:[[:space:]]*(failing|todo|passing)' "$tasks" \

package/scripts/lib/sync-post.sh

@@ -24,7 +24,16 @@ sync_post_run() {
   jq -n --arg name "bigpowers" \
         --arg version "$pkg_version" \
         --arg desc "${skill_count} skills — ${pkg_desc}" \
-        '{name: $name, version: $version, description: $desc}' > "$GEMINI_MANIFEST"
+        '{
+          name: $name,
+          version: $version,
+          description: $desc,
+          keywords: ["gemini-extension"],
+          gemini: {
+            skills: ["./skills"],
+            commands: ["./commands"]
+          }
+        }' > "$GEMINI_MANIFEST"
 
   jq -n --arg version "$pkg_version" \
         --arg desc "${skill_count} skills — ${pkg_desc}" \