bigpowers 1.0.0

package/skills-lock.json

@@ -0,0 +1,157 @@
+{
+  "version": 1,
+  "skills": {
+    "audit-code": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "commit-message": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "craft-skill": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "deepen-architecture": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "define-language": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "define-success": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "delegate-task": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "design-interface": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "develop-tdd": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "diagnose-root": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "dispatch-agents": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "edit-document": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "elaborate-spec": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "enforce-first": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "execute-plan": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "grill-me": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "grill-with-docs": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "guard-git": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "hook-commits": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "inspect-quality": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "investigate-bug": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "kickoff-branch": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "model-domain": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "organize-workspace": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "plan-refactor": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "plan-work": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "release-branch": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "request-review": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "respond-review": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "scope-work": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "seed-conventions": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "slice-tasks": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "spike-prototype": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "survey-context": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "terse-mode": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "using-bigpowers": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "validate-fix": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    },
+    "wire-observability": {
+      "source": "danielvm-git/skills",
+      "sourceType": "github"
+    }
+  }
+}

package/spike-prototype/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: spike-prototype
+description: Throw-away prototype for unknown problem spaces. Output is learning notes in specs/SPIKE-<name>.md, not production code. Use when the domain or technology is unexplored, when estimates are impossible without experimentation, or when user says "spike", "prototype", or "proof of concept".
+---
+
+# Spike Prototype
+
+A spike is a time-boxed experiment to answer a specific question. The code is thrown away. The learning is kept in `specs/SPIKE-<name>.md`.
+
+**The spike produces learning, not code to ship.** If you find yourself cleaning up spike code for production, stop — run `plan-work` and `develop-tdd` instead with the insights you gained.
+
+## When to spike
+
+- The technology is unfamiliar (new library, API, infrastructure)
+- The approach is uncertain (multiple solutions exist; none has been tried)
+- Estimates are impossible without seeing how the thing actually behaves
+- A key assumption needs to be validated before committing to a design
+
+## Process
+
+### 1. Define the question
+
+Before writing a single line, state the question the spike must answer:
+
+> "Can we [specific thing] using [specific approach] within [constraint]?"
+
+Examples:
+- "Can we stream large files from S3 to the client without buffering in memory?"
+- "Does the Stripe webhook SDK handle signature verification correctly in our edge runtime?"
+- "Can we achieve < 100ms p99 response time for the search endpoint with a naive Postgres full-text search?"
+
+A spike with no question is just unplanned coding. Refuse to start if the question isn't clear.
+
+### 2. Set a timebox
+
+Agree on a timebox with the user: 30 minutes, 1 hour, 2 hours. When time is up, stop — even if the question isn't fully answered. Partial learning is still learning.
+
+### 3. Experiment
+
+Write the simplest code that could answer the question. Ignore:
+- Error handling
+- Test coverage
+- Code quality
+- Production concerns
+
+Focus entirely on answering the question.
+
+### 4. Write specs/SPIKE-<name>.md
+
+Save the learning to `specs/SPIKE-<name>.md`. Create the `specs/` directory if it doesn't exist.
+
+<spike-template>
+
+# Spike: [name]
+
+## Question
+
+[The specific question this spike was answering]
+
+## Result
+
+[Answered / Partially answered / Not answered]
+
+## Findings
+
+[What you learned — concrete observations, not opinions]
+
+## Evidence
+
+[Code snippet, benchmark result, API response, or screenshot that proves the finding]
+
+## Implications for the plan
+
+[How this changes the approach, the design, or the estimate]
+
+## What was NOT explored
+
+[Known gaps — things the spike didn't validate]
+
+## Recommendation
+
+[Should we proceed with this approach? If yes, what does plan-work need to account for?]
+
+</spike-template>
+
+### 5. Delete the spike code
+
+After writing the findings, delete or discard the spike code. It is not meant to ship.
+
+### 6. Feed back into plan-work
+
+The spike findings are the input to `plan-work`. Call `plan-work` next, informed by `specs/SPIKE-<name>.md`.

package/survey-context/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: survey-context
+description: Per-task context survey — reads specs/ and CONVENTIONS.md, maps the current lifecycle phase, and suggests the next skill to invoke. Use at the start of any new task, when returning to a project after a break, or when unsure what to do next.
+---
+
+# Survey Context
+
+Read the project's current state and give a phase map + next-skill recommendation. This is the "where am I?" skill — run it at the start of every task.
+
+## Process
+
+### 1. Read CONVENTIONS.md
+
+If `CONVENTIONS.md` exists at the project root, read it first. It contains the rules all agents must follow in this project.
+
+### 2. Read specs/
+
+Scan the `specs/` directory if it exists:
+
+```
+specs/
+├── CONTEXT.md          → domain model status
+├── UBIQUITOUS_LANGUAGE.md → glossary status
+├── SCOPE.md            → scope definition status
+├── TASKS.md            → task breakdown status
+├── PLAN.md             → implementation plan status
+├── REFACTOR.md         → refactor plan status
+├── DIAGNOSIS.md        → active bug investigation
+├── BUG-LOG.md          → historical bug log
+└── SPIKE-*.md          → spike learning notes
+```
+
+For each file found, note: does it exist? Is it complete? Does it have open items?
+
+### 3. Read CLAUDE.md
+
+If `CLAUDE.md` exists at the project root, read it for project context (stack, commands, architecture, conventions).
+
+### 4. Check git state
+
+```bash
+git status --short
+git log --oneline -5
+git branch --show-current
+```
+
+Note: is there a feature branch active? Are there uncommitted changes? Are there unpushed commits?
+
+### 5. Map the lifecycle phase
+
+Based on what you've found, identify which PMBOK phase this project is currently in:
+
+| Phase | Signals |
+|-------|---------|
+| **Discover** | No specs/ yet, or only rough notes |
+| **Design** | specs/SCOPE.md exists but no PLAN.md |
+| **Plan** | specs/TASKS.md or PLAN.md exists; on `main`/`master` branch |
+| **Initiate** | On a feature branch; no code changes yet |
+| **Execute** | PLAN.md exists; on feature branch; steps in progress |
+| **Verify** | All implementation steps for a story/epic are done; awaiting UAT |
+| **Bug** | DIAGNOSIS.md exists; on `main`/`master` |
+| **Review** | All code written; no PR yet |
+| **Integrate** | PR open; tests passing |
+| **Sustain** | Ongoing; no active task |
+
+### 6. Suggest next skill
+
+Based on the phase and state, recommend the most useful next step:
+
+- **If in Plan/Bug phase and on `main`**: Suggest `kickoff-branch` next.
+- **If in Initiate phase**: Suggest `develop-tdd` or `execute-plan`.
+- **If in Execute phase**: Suggest `develop-tdd` (continue step X) or `execute-plan`.
+
+Example:
+```
+Phase: Plan
+Active branch: main
+PLAN.md: exists
+
+Suggested next: kickoff-branch (to create feature/auth branch)
+```
+
+Be specific — name the exact skill and why. If multiple options exist, list them in priority order.
+
+### 7. Surface blockers
+
+If something looks wrong:
+- Broken tests in the baseline
+- DIAGNOSIS.md open with no active fix branch
+- PLAN.md with missing verify commands
+- CONVENTIONS.md violations in recent commits
+
+Report blockers first, before recommendations.

package/terse-mode/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: terse-mode
+description: Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use ONLY when context is critically long and compressing output is necessary to continue. Not a strategy — token discipline comes from code shape (small functions, unique names, headless tests), not terser prompts. Use when user says "caveman mode", "terse mode", "less tokens", "be brief", or invokes /terse-mode.
+---
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop" or "normal mode".
+
+## Rules
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+
+Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+## Auto-Clarity Exception
+
+Drop terse temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume after clear part done.
+
+Example — destructive op:
+
+> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
+>
+> ```sql
+> DROP TABLE users;
+> ```
+>
+> Terse resume. Verify backup exist first.

package/trace-requirement/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: trace-requirement
+description: Link story IDs from specs/RELEASE-PLAN.md to the implementing code and tests. Produces specs/TRACEABILITY.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find "dark" stories with no code.
+---
+
+# Trace Requirement
+
+Build a traceability matrix from `specs/RELEASE-PLAN.md` to implementing code and tests. Surfaces gaps in both directions: stories with no code, and code with no story.
+
+## Pre-flight
+
+> **HARD GATE** — `specs/RELEASE-PLAN.md` must exist. If it doesn't, run `plan-release` first.
+
+→ verify: `[ -f specs/RELEASE-PLAN.md ] && echo "ready" || echo "BLOCKED: run plan-release first"`
+
+Read `specs/RELEASE-PLAN.md` fully before proceeding.
+
+## Process
+
+### 1. Extract story IDs
+
+From RELEASE-PLAN.md, collect all story IDs (e.g. `1.1`, `1.2`, `2.1`).
+
+→ verify: `grep -o "Story [0-9]\+\.[0-9]\+" specs/RELEASE-PLAN.md | sort -u`
+
+### 2. Search for story tags in code
+
+Look for `// story: X.Y` or `# story: X.Y` comments in source files and tests:
+
+```
+grep -rn "story: " . --include="*.ts" --include="*.js" --include="*.py" --include="*.sh" | grep -v node_modules
+```
+
+→ verify: `grep -rn "story: " . --include="*.ts" --include="*.sh" | wc -l`
+
+### 3. Build the matrix
+
+For each story ID:
+- **Implemented**: list files that contain `// story: X.Y`
+- **Tested**: list test files that contain `// story: X.Y`
+- **Dark**: story has no tag in any file — flag as unimplemented
+
+For each tagged file with no matching story ID in RELEASE-PLAN.md:
+- **Orphan**: code exists but story was removed or never planned — flag for cleanup
+
+### 4. Write specs/TRACEABILITY.md
+
+```
+## Story Coverage
+
+| Story | Title              | Files | Tests | Status    |
+|-------|--------------------|-------|-------|-----------|
+| 1.1   | [title]            | 2     | 1     | Covered   |
+| 1.2   | [title]            | 0     | 0     | Dark      |
+
+## Orphan Code (no story tag)
+- [file]: contains untagged implementation
+
+## Gaps (dark stories)
+- Story 1.2: no implementation found → run plan-work
+
+## Coverage summary
+Stories: [X] covered / [Y] dark / [Z] total
+```
+
+→ verify: `grep -c "Covered\|Dark" specs/TRACEABILITY.md`
+
+Suggest `plan-work` for each dark story found.

package/using-bigpowers/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: using-bigpowers
+description: One-time bootstrap that introduces the bigpowers skills system, the PMBOK lifecycle arc, and tells you which skill to call first for your situation. Use when starting with bigpowers for the first time, when user asks "where do I start?", or when the skills system needs to be explained.
+---
+
+# Using bigpowers
+
+Welcome to **bigpowers** — a lifecycle of 37 agent skills for production-ready, TDD-driven software by solo developers.
+
+## What bigpowers is
+
+A curated set of skills organized around the PMBOK developer lifecycle. Each skill does one thing. Skills reference each other by name only — low coupling, high cohesion. All written output goes to `specs/` at your project root.
+
+## The lifecycle at a glance
+
+```
+BOOTSTRAP   using-bigpowers (this skill, first time only)
+              ↓
+DISCOVER    survey-context → elaborate-spec
+              ↓
+DESIGN      model-domain / define-language / grill-me / deepen-architecture / design-interface
+              ↓
+PLAN        scope-work → slice-tasks → define-success → plan-work / plan-refactor
+              ↓
+INITIATE    kickoff-branch → guard-git / hook-commits / seed-conventions
+              ↓
+SPIKE?      spike-prototype → (feeds back to plan-work)
+              ↓
+EXECUTE     develop-tdd + enforce-first ←→ delegate-task / dispatch-agents / execute-plan
+              ↓
+HARDEN      wire-observability (any phase)
+              ↓
+BUG?        investigate-bug → diagnose-root → validate-fix
+              ↓
+REVIEW      audit-code → request-review → respond-review
+              ↓
+INTEGRATE   commit-message → release-branch
+              ↓
+SUSTAIN     inspect-quality / organize-workspace (ongoing)
+
+UTILITY     terse-mode / craft-skill / edit-document (any phase)
+```
+
+## Where to start
+
+| Your situation | First skill to call |
+|---------------|---------------------|
+| Greenfield project, nothing set up | `seed-conventions` |
+| Existing project, new task | `survey-context` |
+| Vague idea that needs shaping | `elaborate-spec` |
+| Plan exists, ready to implement | `kickoff-branch` → `develop-tdd` |
+| Bug to fix | `investigate-bug` |
+| Code ready for review | `audit-code` |
+| Shipping a feature | `commit-message` → `release-branch` |
+
+## Key conventions
+
+- **specs/ is your memory.** All domain docs, plans, and investigation outputs go in `specs/` at your project root.
+- **`gh` for PRs only.** Never create GitHub issues from skills — use local Markdown files instead.
+- **One skill, one thing.** If you're unsure which skill to call, call `survey-context` — it reads your current state and recommends the next step.
+- **verify: every step.** Every task in `specs/PLAN.md` must have a `verify: <runnable command>`. Evidence over claims.
+
+## After this
+
+Call `survey-context` to read your project's current state and get a personalized recommendation for where to go next.

package/validate-fix/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: validate-fix
+description: Prove a fix works before declaring done — re-run the failing test, run the full suite, typecheck, lint, and harden against recurrence. Use after implementing a bug fix, when user says "is this fixed?", or before closing an investigation.
+---
+
+# Validate Fix
+
+Prove the fix works. "I think it works" is not evidence. Run the suite, show the output, then harden against recurrence.
+
+## Checklist
+
+### 1. Re-run the originally failing test
+
+```bash
+# Run the specific test that captured the bug
+<test command for the failing test>
+```
+
+- [ ] Previously failing test now passes
+
+### 2. Run the full test suite
+
+```bash
+# Run all tests — no filtering
+<full test command from CLAUDE.md>
+```
+
+- [ ] All tests pass (zero regressions)
+
+### 3. Type check
+
+```bash
+<typecheck command>
+```
+
+- [ ] No type errors introduced
+
+### 4. Lint
+
+```bash
+<lint command>
+```
+
+- [ ] No lint violations introduced
+
+### 5. Harden against recurrence
+
+For every bug fixed, add at least one prevention layer:
+
+| Mechanism | When to use |
+|-----------|-------------|
+| Type guard | Input could be the wrong shape |
+| Schema validation (Zod, Pydantic, etc.) | External data crossing a boundary |
+| Invariant assertion | Internal state that must always hold |
+| Lint rule | Pattern that's easy to repeat by mistake |
+| Environment check at startup | Missing config causes silent failure |
+
+- [ ] At least one hardening mechanism added
+- [ ] Hardening mechanism is tested
+
+### 6. Update specs/DIAGNOSIS.md
+
+If a `specs/DIAGNOSIS.md` exists for this bug, append the resolution:
+
+```markdown
+## Resolution
+
+**Fixed:** [date]
+**Root cause confirmed:** [one sentence]
+**Fix applied:** [what was changed]
+**Hardening added:** [type guard / schema / assertion / lint rule]
+**Evidence:** all tests pass (`<verify command>`)
+**Commit:** `fix(<scope>): <description>`
+```
+
+- [ ] specs/DIAGNOSIS.md updated with resolution
+
+### 7. Behavioral Proof (HARD GATE)
+
+Mechanical verification (tests passing) is only half the fix. You must prove **behavioral correctness**.
+
+- [ ] Manually demonstrate the fixed behavior (e.g., via `run_shell_command` or `web_fetch`)
+- [ ] Compare the output/state against the "Expected Behavior" in `specs/DIAGNOSIS.md`
+- [ ] Show the user evidence of the behavior, not just the test logs
+
+## Rules
+
+- **Loop until behavioral correctness is verified**: if any checklist item fails, or if the behavior is still incorrect despite passing tests, return to step 1 and run all checks again from the top — do not declare done until every item is green and the behavior is proven correct in a single run.
+- **Never use `@ts-ignore`, `as any`, or `// eslint-disable`** to "fix" a bug — these suppress the symptom without fixing the root cause
+- **Never mark the task done if any test is still failing**
+- **The verify command from specs/DIAGNOSIS.md or specs/PLAN.md must pass**
+
+Suggest next skill: `audit-code` → `commit-message`.

package/visual-dashboard/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: visual-dashboard
+description: Start a browser-based dashboard that visualizes architecture, implementation plans, and project status. Use when showing complex diagrams, progress roadmaps, or UI mockups would be clearer than text. Persists artifacts in .bigpowers/dashboard/.
+---
+
+# Visual Dashboard
+
+Browser-based visual companion for bigpowers. Visualizes architecture, plans, and status.
+
+## When to Use
+
+Use when the user would understand the project state better by seeing it than reading it.
+
+- **Architecture maps** — visualizing module dependencies and "code rot."
+- **Implementation progress** — seeing the vertical slices of a `PLAN.md` as a visual roadmap.
+- **UI brainstorming** — wireframes and layout options.
+- **Complexity audits** — visualizing "God classes" vs "Clean modules."
+
+## How It Works
+
+The server watches for updates to your artifacts and serves a dashboard to the browser. You write visual representations (HTML fragments) to the dashboard's `screen_dir`, and the user interacts with them.
+
+## Starting a Session
+
+```bash
+# Start server with project persistence
+visual-dashboard/scripts/start-server.sh --project-dir $(pwd)
+```
+
+Save the `url`, `screen_dir`, and `state_dir` from the response. Tell the user to open the dashboard.
+
+## Dashboard Loops
+
+### 1. The Architecture View
+When using `deepen-architecture`, push a Mermaid diagram of the target modules to the dashboard.
+Filename: `architecture.html`
+
+### 2. The Plan View
+When using `plan-work`, push a step-by-step progress map.
+Filename: `plan.html`
+
+### 3. User Interaction
+Read `state_dir/events` to see which components or options the user clicked in the dashboard. Use this to refine your next design pass.
+
+## Cleaning Up
+
+```bash
+visual-dashboard/scripts/stop-server.sh $SESSION_DIR
+```