bigpowers 2.43.2 → 2.43.4

package/README.md

@@ -1,247 +1,253 @@
-# bigpowers — Best-in-Class Agentic Skills
+# bigpowers
 
 ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
-![npm version](https://img.shields.io/npm/v/bigpowers.svg)
-![Skills](https://img.shields.io/badge/skills-70-brightgreen.svg)
 
-**70 agent skills for high-integrity, spec-driven, test-first software development by solo developers.**
+![npm version](https://img.shields.io/badge/npm-v2.43.2-blue.svg)
 
-`bigpowers` provides a prescriptive, vertical-slice methodology for building software with AI agents (Claude Code, Gemini CLI, Cursor, pi). It bridges the gap between raw LLM capabilities and professional engineering standards.
+![Skills](https://img.shields.io/badge/skills-72-brightgreen.svg)
 
-Published on npm: [bigpowers@2.0.0](https://www.npmjs.com/package/bigpowers)
+> 72 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers.
 
----
+`bigpowers` is not a random collection of best practices. It is a highly opinionated, chronological layer cake of ideas, combining classical software craftsmanship with modern AI-native architecture. 
 
-## 🚀 Quick Start
+It provides a 6-phase lifecycle with hard gates, a 94% quality threshold, and a YAML cockpit (`specs/state.yaml`) that keeps both human and AI agents perfectly aligned across complex software projects. By enforcing strict boundaries and verifiable outcomes, it allows solo developers to orchestrate multi-agent workflows with predictable, high-quality results.
 
-### npm (recommended)
+## Prerequisites
+
+- **Runtime**: Node.js v14+
+- **Environment**: Bash (required for all internal scripts)
+- **Tooling**: jq (highly recommended for configuration)
+- **AI Tools**: Claude Code, Gemini CLI, Cursor, or pi
+
+## Installation
 
 ```bash
-# One-shot setup — downloads, syncs artifacts, and links skills to your tools
+# One-shot setup: downloads, syncs artifacts, and links skills
 npx bigpowers
 
-# Or install globally and run the setup command anytime
+# Or install globally
 npm install -g bigpowers
 bigpowers
 ```
 
-Both commands sync skill artifacts and link them to Claude Code, Gemini CLI, and Cursor (see [Prerequisites](#-prerequisites)).
+## Usage
+
+```bash
+# Update and re-sync your local skills
+npm update -g bigpowers
+bigpowers
+```
 
-### From source (contributors)
+For deep usage, integrate the generated skills directly into your favorite AI tool (Claude Code, Gemini CLI, Cursor). Use the provided MCP Server to expose skills dynamically:
 
 ```bash
-git clone https://github.com/danielvm-git/bigpowers.git && cd bigpowers
-npm install          # runs postinstall: sync + link
-# or manually:
-bash scripts/install.sh
-npm run sync
+node scripts/mcp-server.js
 ```
 
----
+## Features
 
-## 🛠 Prerequisites
+- **72 Purpose-Built Skills**: From `survey-context` to `develop-tdd`, each skill is a targeted tool for a specific phase of development.
+- **Spec-Driven Cockpit**: Uses `specs/state.yaml` and `release-plan.yaml` to maintain state across agent sessions, preventing context drift.
+- **Native IDE Support**: Automatically generates configurations for Cursor (`.cursor/rules`), Gemini CLI, and pi.
+- **Model Context Protocol (MCP)**: Dynamic tool discovery and invocation via the included MCP server.
+- **Built-in Quality Gates**: Strict verification standards (e.g., F.I.R.S.T tests, BCP accounting) enforced before any code is merged.
 
-- **Bash**: Required for all scripts.
-- **Node.js**: v14+ (required for npm/npx).
-- **jq**: (Highly Recommended) Used for robust configuration of tool settings.
-- **AI Tools**: One or more of:
-  - [Claude Code](https://claude.ai/code)
-  - [Gemini CLI](https://github.com/google/gemini-cli)
-  - [Cursor](https://cursor.sh/)
-  - [pi](https://pi.dev/) — coding agent harness
+🏗 The v2.0.0 Lifecycle
 
----
+Every project follows the orchestrate-project 6-phase model (full SOP: docs/[WORKFLOW-SOP-v2.md](http://WORKFLOW-SOP-v2.md)):
 
-## 🔄 Maintenance (Update & Uninstall)
+ONE TIME    seed-conventions  ([CLAUDE.md](http://CLAUDE.md), .claude/, .gemini/, agents/, skill sync)
 
-### Update
+              ↓
 
-**npm install:**
+ONCE/PROJECT orchestrate-project
 
-```bash
-npm update -g bigpowers
-bigpowers    # re-sync and refresh symlinks
-```
+              │
 
-**git clone:**
+              ├─ Ph1 DISCOVER   survey-context, research-first, elaborate-spec
 
-```bash
-git pull
-npm run sync
-```
+              ├─ Ph2 ELABORATE  model-domain, grill-me, define-language, deepen-architecture
 
-*Install uses symlinks — re-running setup refreshes links without duplicating files.*
+              ├─ Ph3 PLAN       scope-work, slice-tasks, plan-work → release-plan.yaml (BCP baseline)
 
-### Uninstall
+              ├─ Ph4 BUILD      build-epic × N stories
 
-**npm install:**
+              │
 
-```bash
-bash "$(npm root -g)/bigpowers/scripts/install.sh" --uninstall
-npm uninstall -g bigpowers
-```
+              │  Per story — 8-step build-epic cycle:
 
-**git clone:**
+              │   1. survey-context   ← stamps story_start in state.yaml
 
-```bash
-bash scripts/install.sh --uninstall
-```
+              │   2. plan-work        ← [BCP N] tasks + verify: commands
 
-### Reinstall
+              │   3. kickoff-branch   ← worktree + feature branch
 
-```bash
-npx bigpowers
-# or, if installed globally:
-bigpowers
-```
+              │   4. develop-tdd      ← RED → GREEN → REFACTOR
 
----
+              │   5. verify-work      ← UAT gate
 
-## 🔌 pi Support
+              │   6. audit-code       ← quality gate ≥ 94%
 
-bigpowers generates pi Agent Skills and prompt templates alongside Cursor and Gemini artifacts via `sync-skills.sh`.
+              │   7. commit-message   ← Conventional Commits + semver
 
-### Install as a pi package
+              │   8. release-branch   ← land to main; writes story_end + cycle-times.yaml
 
-```bash
-# Clone and sync to generate pi artifacts
-cd bigpowers
-bash scripts/sync-skills.sh
+              │
 
-# Install from local path as a pi package
-pi install .
+              ├─ Ph5 VERIFY     run-evals, verify-work (project-level)
+
+              └─ Ph6 RELEASE    semantic-release → v1.0.0 MVP tag
+
+Semver: projects start at 0.0.0-β; each feat: story → minor bump; developer declares MVP → 1.0.0.
+
+BCP accounting: every task labeled [BCP N]; story total in state.yaml; BCP/hr logged to specs/metrics/cycle-times.yaml.
+
+next_skill signaling: each critical-path skill writes [handoff.next](http://handoff.next)_skill to state.yaml. Call survey-context after any interruption to resume exactly where you left off.
+
+## 🧠 Philosophical Stack — How These Ideas Concatenate
+
+`bigpowers` is not a flat list of influences. It is a **chronological layer cake** — each wave of thinking builds on and resolves tensions from the previous one. No layer replaces the last; each addresses a problem the prior one created.
+
+![Philosophy Diagram](docs/images/philosophy_diagram.jpg)
+
+
+| Era           | Source                                                                                                                                                                                               | Contribution                                                                       | Tension Resolved                                                                 |
+| :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
+| **2008**      | [Uncle Bob](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882) (Clean Code)                                                                                            | SRP, Boy Scout Rule, F.I.R.S.T. tests, intention-revealing names                   | — (foundation)                                                                   |
+| **2018**      | [Ousterhout](https://www.amazon.com/Philosophy-Software-Design-John-Ousterhout/dp/1732102201) (*A Philosophy of Software Design*)                                                                    | Deep modules, information hiding, define errors out of existence                   | Small functions alone create shallow modules with bloated interfaces             |
+| **2023–24**   | [Karpathy](https://github.com/multica-ai/andrej-karpathy-skills), [Superpowers](https://github.com/obra/superpowers), [Pocock](https://github.com/mattpocock/skills)                                 | Think-first planning, verb-noun skill architecture, zoom-out strategy              | Raw LLMs have no discipline — they need orchestration, not raw prompting         |
+| **2024**      | [Wasowski](https://medium.com/@wasowski.jarek/sdd-writing-specifications-for-ai-bdd-as-the-missing-link-spec-driven-development-ad1b540b7f75) (SDD), [BCP](https://github.com/flow-ciandt/bcp-agent) | Specs as the human-agent interface; business complexity as a pre-build sizing unit | Agents drift without a verifiable spec — BDD Gherkin closes the loop             |
+| **2026**      | [Akita](https://akitaonrails.com/2026/04/20/clean-code-para-agentes-de-ia/) (*Clean Code for AI Agents*)                                                                                             | Grep-ability, structured JSON logging, token economy, remediation hints in errors  | Uncle Bob's rules were written for humans — agents need different code hygiene   |
+| **Synthesis** | BMAD + GSD (self-authored)                                                                                                                                                                           | 6-phase lifecycle, hard gates, 94% quality threshold, `specs/state.yaml` cockpit   | All the above are principles; bigpowers turns them into an executable discipline |
 
-# Or install as a pi npm package (once published with pi-package keyword)
-pi install npm:bigpowers
-```
 
-**What you get:**
-- **62 pi skills** in `.pi/skills/` — loaded automatically into pi's system prompt as `<available_skills>`
-- **62 pi prompt templates** in `.pi/prompts/` — slash commands like `/survey-context`, `/plan-work`
-- **pi package manifest** in `.pi/package.json` — enables `pi install` with auto-discovery
+### How to see the concatenation in action
 
-Skills are loaded on-demand via progressive disclosure: only descriptions are always in context; the full SKILL.md loads when the agent reads it. Prompt templates expand in pi's editor with autocomplete.
+Each philosophical pillar has a corresponding Gherkin `.feature` file in [`specs/verifications/features/`](specs/verifications/features/) that empirically proves compliance:
 
-## 🔧 MCP Server (Model Context Protocol)
+
+| Pillar                  | Verification             |
+| :----------------------- | :------------------------ |
+| Classical Craftsmanship | `cleancode.feature`      |
+| Complexity Management   | `pocock.feature`         |
+| Behavioral Integrity    | `karpathy.feature`       |
+| Spec-Driven Development | Implicit in SDD workflow |
+| Agentic Standard        | `akita.feature`          |
+| Project Conventions     | `conventions.feature`    |
+| Original Baseline       | `superpowers.feature`    |
+
+
+Run `npm run compliance` to audit all features. Score &lt; 94% = hard stop.
+
+
+
+🔧 MCP Server (Model Context Protocol)
 
 bigpowers ships an MCP server that exposes all skills as callable MCP tools. Agents can discover and invoke skills dynamically instead of relying on a static system prompt.
 
-### Start the server
+Start the server
 
-```bash
 node scripts/mcp-server.js
-```
 
-### Add to Claude Code
+Add to Claude Code
 
-```bash
 claude mcp add bigpowers node /path/to/bigpowers/scripts/mcp-server.js
-```
 
-Or add manually to `.claude/settings.json`:
+Or add manually to .claude/settings.json:
 
-```json
 {
+
   "mcpServers": {
+
     "bigpowers": {
+
       "command": "node",
+
       "args": ["/path/to/bigpowers/scripts/mcp-server.js"]
+
     }
+
   }
+
 }
-```
 
-### Available MCP tools
+Available MCP tools
 
-| Tool | Description |
-|------|-------------|
-| `bigpowers_list_skills` | List all 70 skills with name, description, phase. Optional `phase` filter. |
-| `bigpowers_get_skill` | Get full SKILL.md content for any skill by name. |
-| `bigpowers_search_skills` | Keyword/semantic search — returns ranked matches for a query. |
-| `bigpowers_get_state` | Get current `specs/state.yaml` (active flow, epic, step). |
-| `bigpowers_invoke_skill` | Get skill instructions with optional context for agent invocation. |
+Tool	Description
 
----
+bigpowers_list_skills	List all 70 skills with name, description, phase. Optional phase filter.
 
-## 🏗 The v2.0.0 Lifecycle
+bigpowers_get_skill	Get full [SKILL.md](http://SKILL.md) content for any skill by name.
 
-Every project follows the **orchestrate-project 6-phase model** (full SOP: [`docs/WORKFLOW-SOP-v2.md`](docs/WORKFLOW-SOP-v2.md)):
+bigpowers_search_skills	Keyword/semantic search — returns ranked matches for a query.
 
-```
-ONE TIME    seed-conventions  (CLAUDE.md, .claude/, .gemini/, agents/, skill sync)
-              ↓
-ONCE/PROJECT orchestrate-project
-              │
-              ├─ Ph1 DISCOVER   survey-context, research-first, elaborate-spec
-              ├─ Ph2 ELABORATE  model-domain, grill-me, define-language, deepen-architecture
-              ├─ Ph3 PLAN       scope-work, slice-tasks, plan-work → release-plan.yaml (BCP baseline)
-              ├─ Ph4 BUILD      build-epic × N stories
-              │
-              │  Per story — 8-step build-epic cycle:
-              │   1. survey-context   ← stamps story_start in state.yaml
-              │   2. plan-work        ← [BCP N] tasks + verify: commands
-              │   3. kickoff-branch   ← worktree + feature branch
-              │   4. develop-tdd      ← RED → GREEN → REFACTOR
-              │   5. verify-work      ← UAT gate
-              │   6. audit-code       ← quality gate ≥ 94%
-              │   7. commit-message   ← Conventional Commits + semver
-              │   8. release-branch   ← land to main; writes story_end + cycle-times.yaml
-              │
-              ├─ Ph5 VERIFY     run-evals, verify-work (project-level)
-              └─ Ph6 RELEASE    semantic-release → v1.0.0 MVP tag
-```
+bigpowers_get_state	Get current specs/state.yaml (active flow, epic, step).
+
+bigpowers_invoke_skill	Get skill instructions with optional context for agent invocation.
+
+Tool	Description
 
-**Semver:** projects start at `0.0.0-β`; each `feat:` story → minor bump; developer declares MVP → `1.0.0`.
+bigpowers_list_skills	List all 72 skills with name, description, phase. Optional phase filter.
 
-**BCP accounting:** every task labeled `[BCP N]`; story total in `state.yaml`; BCP/hr logged to `specs/metrics/cycle-times.yaml`.
+bigpowers_get_skill	Get full [SKILL.md](http://SKILL.md) content for any skill by name.
 
-**next_skill signaling:** each critical-path skill writes `handoff.next_skill` to `state.yaml`. Call `survey-context` after any interruption to resume exactly where you left off.
+bigpowers_search_skills	Keyword/semantic search — returns ranked matches for a query.
 
----
+bigpowers_get_state	Get current specs/state.yaml (active flow, epic, step).
 
-## 📖 Hierarchy of Truth
+bigpowers_invoke_skill	Get skill instructions with optional context for agent invocation.
+
+
+
+## Development
+
+```bash
+git clone https://github.com/danielvm-git/bigpowers.git
+cd bigpowers
+npm install
+# Sync artifacts from SKILL.md sources
+npm run sync
+```
+
+## Tests
+
+```bash
+# Run compliance verification against Gherkin features
+npm run compliance
+
+# Validate YAML specifications and doctrine
+npm run doctrine
+npm run validate-specs
+```
 
-| Level | Document | Responsibility |
-| :--- | :--- | :--- |
-| **Vision** | `docs/PRINCIPLES.md` | Philosophical foundations and evolution. |
-| **Context** | `specs/tech-architecture/TECH_STACK_LATEST.md` | Tech stack, architecture, and domain notes. |
-| **Scope** | `specs/product/SCOPE_LATEST.yaml` | In-scope / out-of-scope and success criteria. |
-| **Vision** | `specs/product/VISION_LATEST.yaml` | North star and initiative success criteria. |
-| **Decisions** | `specs/adr/` | Architectural Decision Records (irreversible choices). |
-| **Roadmap** | `specs/release-plan.yaml` + `specs/epics/` | WSJF-prioritized epics and stories with BCP baseline. |
-| **Current** | `specs/state.yaml` | Session flow, active epic, `handoff.next_skill`, timestamps. |
-| **Metrics** | `specs/metrics/cycle-times.yaml` | Per-story BCPs, cycle minutes, BCP/hr (v2.0.0). |
-| **Index** | `SKILL-INDEX.md` | Canonical list of all active skills. |
-| **Style** | `CONVENTIONS.md` | Coding, testing, and naming standards. |
+## Contributing
 
----
+1. Fork the repo.
+2. Create a feature branch (`git checkout -b feature/my-thing`).
+3. Make your changes using the `bigpowers` methodology.
+4. Commit using Conventional Commits (`git commit -am 'feat: add my thing'`).
+5. Push to the branch (`git push origin feature/my-thing`).
+6. Open a Pull Request.
 
-## 📁 Project Structure
+## Changelog
 
-- `scripts/`: Installation, syncing, and compliance tools.
-- `specs/`: YAML cockpit — `state.yaml`, `release-plan.yaml`, `epics/`, `execution-status.yaml`, `requirements/`.
-- `specs/metrics/`: Cycle-time ledger (`cycle-times.yaml`) — per-story BCPs, timestamps, BCP/hr (v2.0.0).
-- `dashboard/`: Live monitoring tool — TUI (`npm run dashboard`) and web (`npm run dashboard:web`, port 7742).
-- `docs/`: Guides including `WORKFLOW-SOP-v2.md` (full SDLC SOP) and `using-bigpowers.md`.
-- `docs/references/`: Theoretical foundations (Uncle Bob, Ousterhout, Karpathy, etc.).
-- `[skill-name]/`: Source files for each of the 70 skills.
+See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/danielvm-git/bigpowers/releases).
 
----
+## Links
 
-## 🤝 References & Credits
+- **Repository**: [https://github.com/danielvm-git/bigpowers](https://github.com/danielvm-git/bigpowers)
+- **Issue Tracker**: [https://github.com/danielvm-git/bigpowers/issues](https://github.com/danielvm-git/bigpowers/issues)
 
-`bigpowers` stands on the shoulders of giants. It integrates patterns from:
-- **Akita**: Architectural patterns.
-- **BMAD**: Bold, Minimal, Actionable, Durable documentation.
-- **Clean Code**: Robert C. Martin (Uncle Bob).
-- **A Philosophy of Software Design**: John Ousterhout.
-- **GSD (Get Stuff Done)**: Pragmatic workflow frameworks.
+## Acknowledgements
 
----
+This project is a synthesis of decades of software engineering thought. It would not be possible without the foundational work of the authors who wrote the inspirational articles and books that shaped this methodology:
 
-## 📄 License
+- **Robert C. Martin (Uncle Bob)** for establishing the baseline of code hygiene and the F.I.R.S.T principles in *Clean Code*.
+- **John Ousterhout** for his paradigm-shifting views on Deep Modules and complexity management in *A Philosophy of Software Design*.
+- **Andrej Karpathy** and **Matt Pocock** for their pioneering work on agentic skills and structuring context for LLMs.
+- **Jarek Wasowski** for identifying Spec-Driven Development (SDD) as the missing link for AI agents.
+- **AkitaOnRails** for adapting classical clean code principles to the reality of the AI token economy.
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+## License
 
----
-*“Simplicity is the ultimate sophistication, but integrity is the ultimate requirement.”*
+MIT — see [LICENSE](LICENSE) for details.

package/SKILL-INDEX.md

@@ -3,7 +3,7 @@
 > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
 > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
 
-**Generated:** 2026-07-02T12:07:54Z
+**Generated:** 2026-07-02T15:59:32Z
 **Skills:** 72
 
 ---

package/align-grid/SKILL.md

@@ -108,3 +108,7 @@ A clean run looks like: `col=0px overlay=0px baseline≤4px ink=0px` → `GRID V
 
 ## CREED
 A grid you can't toggle on and measure is a mood board, not a system. Build it from one source of truth, prove it at 0px, and align the **ink**.
+
+## Verify
+
+→ verify: `test -f align-grid/SKILL.md && grep -q '^name:' align-grid/SKILL.md && echo "OK: align-grid valid" || echo "FAIL: align-grid missing"`

package/audit-code/SKILL.md

@@ -120,6 +120,11 @@ PASS Law of Demeter
 
 Aggregate exit code: `0` if all sections PASS, `1` (non-zero) if any section FAILs. Write the full audit report to `specs/verifications/AUDIT-<epic>-<story>.md` as a permanent record.
 
+## Verify
+
+→ verify: `test -f audit-code/SKILL.md && grep -q '^name:' audit-code/SKILL.md && echo "OK: audit-code valid" || echo "FAIL: audit-code missing"`
+
+
 ## Handoff
 
 Gate: READY -> next: commit-message

package/build-epic/SKILL.md

@@ -77,4 +77,4 @@ Write `handoff.next_skill` and `handoff.context` in `state.yaml` when pausing mi
 
 ## Verify
 
-→ verify: `grep -q 'active_flow: build_epic' specs/state.yaml && test -f specs/epics/*/epic.yaml`
+→ verify: `test -f build-epic/SKILL.md && grep -q '^name:' build-epic/SKILL.md && echo "OK: build-epic valid" || echo "FAIL: build-epic missing"`

package/commit-message/SKILL.md

@@ -47,6 +47,11 @@ If the repo uses a custom `@semantic-release/commit-analyzer` preset, note that
 
 - [REFERENCE.md](REFERENCE.md) — Message shape, footers, release mapping, squashing notes.
 
+## Verify
+
+→ verify: `test -f commit-message/SKILL.md && grep -q '^name:' commit-message/SKILL.md && echo "OK: commit-message valid" || echo "FAIL: commit-message missing"`
+
+
 ## Handoff
 
 Gate: READY -> next: release-branch

package/craft-skill/SKILL.md

@@ -58,3 +58,7 @@ After drafting, verify:
 - [ ] Consistent terminology with CONVENTIONS.md
 - [ ] specs/ output documented if applicable
 - [ ] `sync-skills.sh` run to propagate to Cursor/Gemini
+
+## Verify
+
+→ verify: `test -f craft-skill/SKILL.md && grep -q '^name:' craft-skill/SKILL.md && echo "OK: craft-skill valid" || echo "FAIL: craft-skill missing"`

package/deepen-architecture/SKILL.md

@@ -91,3 +91,7 @@ Side effects happen inline as decisions crystallize:
 - **Sharpening a fuzzy term during the conversation?** Update `specs/tech-architecture/tech-stack.md` right there.
 - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer. See [ADR-FORMAT.md](../model-domain/ADR-FORMAT.md).
 - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).
+
+## Verify
+
+→ verify: `test -f deepen-architecture/SKILL.md && grep -q '^name:' deepen-architecture/SKILL.md && echo "OK: deepen-architecture valid" || echo "FAIL: deepen-architecture missing"`

package/define-language/SKILL.md

@@ -78,3 +78,7 @@ When invoked again in the same conversation:
 3. Update definitions if understanding has evolved
 4. Re-flag any new ambiguities
 5. Rewrite the example dialogue to incorporate new terms
+
+## Verify
+
+→ verify: `test -f define-language/SKILL.md && grep -q '^name:' define-language/SKILL.md && echo "OK: define-language valid" || echo "FAIL: define-language missing"`

package/define-success/SKILL.md

@@ -63,3 +63,7 @@ Add any missing pairs.
 Present the pairs to the user and ask: "Does this capture everything the task requires? Anything missing?"
 
 Once confirmed, these pairs become the skeleton for `plan-work`'s steps. Pass them along when calling `plan-work`.
+
+## Verify
+
+→ verify: `test -f define-success/SKILL.md && grep -q '^name:' define-success/SKILL.md && echo "OK: define-success valid" || echo "FAIL: define-success missing"`

package/delegate-task/SKILL.md

@@ -75,3 +75,7 @@ Check:
 ```
 
 Report the decision and rationale to the user.
+
+## Verify
+
+→ verify: `test -f delegate-task/SKILL.md && grep -q '^name:' delegate-task/SKILL.md && echo "OK: delegate-task valid" || echo "FAIL: delegate-task missing"`

package/deploy/SKILL.md

@@ -103,3 +103,7 @@ For comprehensive health-checking, chain to the `smoke-test` skill:
 # After deploy success
 bash scripts/run-smoke.sh "$DEPLOY_URL"
 ```
+
+## Verify
+
+→ verify: `test -f deploy/SKILL.md && grep -q '^name:' deploy/SKILL.md && echo "OK: deploy valid" || echo "FAIL: deploy missing"`

package/design-interface/SKILL.md

@@ -95,3 +95,7 @@ From "A Philosophy of Software Design":
 - Don't skip comparison — the value is in contrast
 - Don't implement — this is purely about interface shape
 - Don't evaluate based on implementation effort
+
+## Verify
+
+→ verify: `test -f design-interface/SKILL.md && grep -q '^name:' design-interface/SKILL.md && echo "OK: design-interface valid" || echo "FAIL: design-interface missing"`

package/develop-tdd/SKILL.md

@@ -94,6 +94,11 @@ If this cycle modified files in `.github/workflows/`, run the CI dry-run procedu
 [ ] verify: command passes
 ```
 
+## Verify
+
+→ verify: `test -f develop-tdd/SKILL.md && grep -q '^name:' develop-tdd/SKILL.md && echo "OK: develop-tdd valid" || echo "FAIL: develop-tdd missing"`
+
+
 ## Handoff
 
 Gate: READY -> next: verify-work

package/dispatch-agents/SKILL.md

@@ -82,3 +82,7 @@ When all agents return:
 Merge accepted results. If any agent's result conflicts with another, resolve manually and note the conflict.
 
 Report a summary: which tasks succeeded, which need revision, and overall verify status.
+
+## Verify
+
+→ verify: `test -f dispatch-agents/SKILL.md && grep -q '^name:' dispatch-agents/SKILL.md && echo "OK: dispatch-agents valid" || echo "FAIL: dispatch-agents missing"`

package/edit-document/SKILL.md

@@ -21,3 +21,7 @@ Confirm the sections with the user.
 2. For each section:
 
 2a. Rewrite the section to improve clarity, coherence, and flow. Use maximum 240 characters per paragraph.
+
+## Verify
+
+→ verify: `test -f edit-document/SKILL.md && grep -q '^name:' edit-document/SKILL.md && echo "OK: edit-document valid" || echo "FAIL: edit-document missing"`

package/elaborate-spec/SKILL.md

@@ -99,3 +99,7 @@ Once the spec is clear, recommend the next step:
 - If a spike is needed first → `spike-prototype`
 - If architecture decisions are needed → `deepen-architecture` or `grill-me`
 - If the plan depends on a specific library or API → `grill-me` in docs mode
+
+## Verify
+
+→ verify: `test -f elaborate-spec/SKILL.md && grep -q '^name:' elaborate-spec/SKILL.md && echo "OK: elaborate-spec valid" || echo "FAIL: elaborate-spec missing"`

package/enforce-first/SKILL.md

@@ -81,3 +81,7 @@ For each failing criterion:
 4. Re-run the suite to confirm it still passes
 
 Report: "F.I.R.S.T audit complete. X criteria passed, Y fixed."
+
+## Verify
+
+→ verify: `test -f enforce-first/SKILL.md && grep -q '^name:' enforce-first/SKILL.md && echo "OK: enforce-first valid" || echo "FAIL: enforce-first missing"`

package/execute-plan/SKILL.md

@@ -53,3 +53,7 @@ Suggest: `verify-work` → `run-evals` → `audit-code` → `simulate-agents`
 ## Rules
 
 - **Loop until behavioral correctness is verified**: if a verify command passes but the observed behavior is still wrong, return to step 1 and run the execution cycle again.
+
+## Verify
+
+→ verify: `test -f execute-plan/SKILL.md && grep -q '^name:' execute-plan/SKILL.md && echo "OK: execute-plan valid" || echo "FAIL: execute-plan missing"`

package/extract-design/SKILL.md

@@ -75,3 +75,7 @@ node extract-design/tests/test-extraction.js
 ```
 
 See [REFERENCE.md](REFERENCE.md) for extraction algorithms and heuristics.
+
+## Verify
+
+→ verify: `test -f extract-design/SKILL.md && grep -q '^name:' extract-design/SKILL.md && echo "OK: extract-design valid" || echo "FAIL: extract-design missing"`

package/fix-bug/SKILL.md

@@ -54,4 +54,4 @@ title: Short title
 
 ## Verify
 
-→ verify: `test -d specs/bugs && bash scripts/sync-bugs-registry.sh`
+→ verify: `test -d specs/bugs && test -f scripts/run-skill-verify.sh`

package/grill-me/SKILL.md

@@ -28,3 +28,7 @@ Short form:
 3. Challenge each plan assumption against the real docs: correct method signature? right version? deprecated?
 4. Report confirmed ✓, corrected ✗ (with the real behavior), and uncertain → `spike-prototype`.
 5. Update the plan for each confirmed discrepancy.
+
+## Verify
+
+→ verify: `test -f grill-me/SKILL.md && grep -q '^name:' grill-me/SKILL.md && echo "OK: grill-me valid" || echo "FAIL: grill-me missing"`

package/grill-with-docs/SKILL.md

@@ -25,6 +25,6 @@ model: opus
 
 ## Verify
 
-→ verify: dialogue log contains at least one `https://` doc URL per challenged assumption
+→ verify: `grep -c 'https\?://' grill-with-docs/SKILL.md | awk '{if($1>=2) print "OK"; else print "NEEDS DOCS"}'`
 
 See [REFERENCE.md](REFERENCE.md) for question templates.

package/guard-git/SKILL.md

@@ -42,3 +42,7 @@ To add or remove patterns or protected branches, edit `pre-tool-use.sh`.
 ## Advanced
 
 Full JSON examples, merge rules, Antigravity deny-list entries, and test commands: [REFERENCE.md](REFERENCE.md).
+
+## Verify
+
+→ verify: `test -f guard-git/SKILL.md && grep -q '^name:' guard-git/SKILL.md && echo "OK: guard-git valid" || echo "FAIL: guard-git missing"`