bigpowers 2.2.0 → 2.4.0

package/.pi/skills/wire-observability/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: wire-observability
+description: "Add structured JSON logging, observability commands, and idempotent setup scripts to a project. Use when a project needs production-readiness instrumentation, when user wants structured logging, or as a production-readiness gate at any phase of development."
+---
+
+
+# Wire Observability
+> **HARD GATE** — **HARD GATE** — Observability is not optional. Before shipping, verify: structured logging is in place, key metrics are instrumented, error cases emit signals. 'We'll add metrics later' becomes 'never.'
+
+
+Add structured logging, observability commands, and idempotent setup scripts. Can be invoked at any phase — recommended at the end of the first working slice, before the first deploy.
+
+## What this sets up
+
+1. **Structured JSON logging** — machine-readable logs for debugging and observability
+2. **Observability commands** — how to check the system's health documented in CLAUDE.md
+3. **Idempotent setup scripts** — scripts that can be run repeatedly without side effects
+
+## Process
+
+### 1. Assess current state
+
+Check what's already in place:
+- Is there a logging library? (pino, winston, structlog, zap, slog, etc.)
+- Is logging JSON or plain text?
+- Is there a health check endpoint or command?
+- Are there setup scripts? Are they idempotent?
+
+### 2. Add structured JSON logging
+
+**For user-facing CLI output:** plain text is fine.
+**For everything else:** structured JSON.
+
+Structured log entry format:
+```json
+{
+  "level": "info",
+  "timestamp": "2025-01-15T10:23:45.123Z",
+  "message": "User created",
+  "userId": "usr_abc123",
+  "requestId": "req_xyz789"
+}
+```
+
+Guidelines:
+- Include `level`, `timestamp`, `message` in every entry
+- Add context fields relevant to the operation (userId, requestId, traceId)
+- Log at boundaries: HTTP requests in/out, DB queries, external API calls, background job start/end
+- Log errors with stack traces: `logger.error({ err, context }, "Operation failed")`
+- **Never log secrets, passwords, tokens, or PII**
+
+### 3. Document observability commands in CLAUDE.md
+
+Add an "Observability" section to the project's CLAUDE.md:
+
+```markdown
+## Observability
+
+| What | Command |
+|------|---------|
+| View logs | `<log tail command>` |
+| Health check | `<health check command>` |
+| Check DB connection | `<db ping command>` |
+| View metrics | `<metrics command>` |
+```
+
+### 4. Write idempotent setup scripts
+
+An idempotent script can be run multiple times and always produces the same result (no errors on re-run).
+
+Pattern: check if the thing already exists before creating it.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Idempotent: only create if not exists
+if ! psql -c "SELECT 1 FROM pg_database WHERE datname = 'myapp'" | grep -q 1; then
+  createdb myapp
+  echo "Database created"
+else
+  echo "Database already exists, skipping"
+fi
+```
+
+Place setup scripts in `scripts/setup.sh` (or language-appropriate equivalent). Document the command in CLAUDE.md under Commands.
+
+### 5. Verify
+
+- [ ] Run the app and confirm JSON logs appear in the correct format
+- [ ] Run `scripts/setup.sh` twice — second run should produce no errors
+- [ ] Health check command returns success
+- [ ] No sensitive data in log output

package/.pi/skills/write-document/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: write-document
+description: "Write, organize, and sync high-integrity technical documents using the BMAD methodology. Ensures every document is Bold, Minimal, Actionable, and Durable. Use when creating architectural docs, technical guides, or organizing the specs/ directory."
+---
+
+
+# Write Document (BMAD)
+
+Create high-signal technical documentation that serves as an expert collaborator for both humans and AI. This skill enforces the BMAD principles to prevent context rot and ensure architectural durability.
+
+**Distinct from `edit-document`:** Use this skill to create a document that does not yet exist. Use `edit-document` when a document already exists and needs restructuring, clarity, or prose improvements.
+
+> **HARD GATE** — Every document must have a clear "Reason for Existence." If a document doesn't provide actionable leverage for a caller or test, do not create it.
+
+## The BMAD Principles
+
+| Principle | Execution |
+| :--- | :--- |
+| **B**old | Make strong assertions. Define clear boundaries and "Never" rules. No "it might" or "usually." |
+| **M**inimal | High-density, low-filler. **Circuit Breaker**: If the file exceeds 300 lines or the session exceeds 20 turns, you MUST run `terse-mode` and compact state before saving. |
+| **A**ctionable | Link every doc to a verifiable outcome. **Architectural Docs**: Verify via Gherkin features (`specs/verifications/features/`) or grep-based structure checks (`grep -c "pattern" file`) that prove the design's *constraints* are present. |
+| **D**urable | Design for the long-term. **Scalability**: Use "Nested Indexing"—root files link to module-level `GEMINI.md` indexes; do not list individual sub-files in the root. |
+
+## Process
+
+### 1. Identify the Artifact Type & Scope
+
+Choose the correct BMAD-BigPowers artifact:
+- **Decision Record (ADR)**: For "Why" decisions (saved to `specs/adr/`).
+- **Context Map**: For system-wide architectural mapping (`specs/tech-architecture/tech-stack.md`).
+- **Technical Guide**: For "How-to" with verification (saved to `<module>/REFERENCE.md`).
+- **Behavioral Feature**: Gherkin-style compliance specs (saved to `specs/verifications/features/`).
+- **Project README**: Project-facing documentation (saved to `README.md` at project root).
+
+**Cross-Cutting Concerns**: If a doc affects multiple modules, place the authoritative source in the lowest common ancestor directory and use "Delegates" (one-line pointers) in sub-directories to maintain the Single Source of Truth without violating the Stepdown Rule.
+
+### 2. Draft with Semantic Velocity
+
+> **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent.
+
+Write the document focusing on "Expert Collaboration":
+- **Instructions over Descriptions**: Tell the reader (human or AI) exactly how to interact with the system.
+- **Provenance Links**: Link to ADRs, Issues, or Commits to preserve intent.
+- **The Stepdown Rule**: Information should descend exactly one level of abstraction. If a root doc needs to explain a leaf-level detail, it must point to a sub-index first.
+
+### Quick README (Project READMEs only)
+
+1. Ask: "Project name? One-sentence description?"
+2. Generate `README.md` at project root using the template in [REFERENCE.md](REFERENCE.md) — no TOC, no second interview round.
+3. Fill gaps from `CLAUDE.md` commands if available; use `TODO` markers otherwise.
+4. Output and suggest `edit-document` for polish.
+
+→ verify: `grep -c "^## " README.md | awk '{if($1>=7) print "OK"}'`
+
+### 3. Apply the 94% Quality Gate
+
+Before finalizing, audit the document against these red flags:
+- [ ] **Filler Language**: Are there pleasantries or "I hope this helps"? (Delete them).
+- [ ] **Ambiguity**: Are there "usually," "often," or "it depends" without specific conditions?
+- [ ] **Dead Ends**: Does the document end without a "Next Step" or "Verification" command?
+- [ ] **Shallow Content**: Does it restate the code without explaining the *intent* or *contracts*?
+
+### 4. Sync and Organize
+
+- **Big Powers Hierarchy**: Place the document in the correct tier (Global -> Project -> Sub-directory). Project READMEs are an exception — they go to project root (`README.md`), not `specs/`.
+- **Nested Indexing**: If adding a module-level doc, ensure the module's `GEMINI.md` is updated. If the module's index is new, add it to the root `GEMINI.md`.
+- **Sync**: Run `scripts/sync-skills.sh` if the document is a `SKILL.md` or affects generated artifacts.
+
+## Rules
+
+- **Minimalism is a requirement**: If a document can be a 5-line table, do not make it a 5-line essay.
+- **Verifiable outcomes**: Every technical document must include at least one `verify:` command. For architecture, this can be a `grep` or `run_shell_command` that validates the existence of required files or patterns.
+- **No speculative docs**: Do not write documentation for features that do not exist yet unless explicitly doing `elaborate-spec`.
+
+
+Suggest next skill: `audit-code` or `sync-skills.sh`.
+
+---
+
+# Project README Template
+
+Combined from dbader/readme-template and jehna/readme-best-practices. No TOC.
+
+## Sections
+
+### 1. Title + Badges
+
+```markdown
+# Project Name
+
+![License](https://img.shields.io/badge/License-MIT-yellow.svg)
+![npm version](https://img.shields.io/npm/v/your-package.svg)
+
+```
+
+Fill badges from CLAUDE.md stack info if available. Default to license + version badges.
+
+### 2. Tagline
+
+```markdown
+> One-line description of what this project does and why it matters.
+```
+
+### 3. Description
+
+2-3 paragraphs: what problem it solves, who it's for, and what makes it different.
+
+### 4. Prerequisites
+
+```markdown
+## Prerequisites
+
+- **Runtime**: Node.js v18+ (from CLAUDE.md)
+- **Package manager**: npm (or pnpm/yarn)
+```
+
+Auto-fill from CLAUDE.md commands section when possible.
+
+### 5. Installation
+
+```markdown
+## Installation
+
+```bash
+npm install -g your-package
+# or
+npx your-package
+```
+```
+
+Prefer npx one-shot if applicable; list global install as alternative.
+
+### 6. Usage
+
+```markdown
+## Usage
+
+```bash
+your-command --help
+your-command do-something
+```
+```
+
+Include the most common 1-2 commands. Link to full docs if they exist.
+
+### 7. Features
+
+```markdown
+## Features
+
+- Feature 1: short description
+- Feature 2: short description
+```
+
+3-6 bullet points of what the project does. Derived from the project's purpose.
+
+### 8. Configuration
+
+```markdown
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VAR_NAME` | `value` | What it controls |
+```
+
+Use `TODO` markers if unknown.
+
+### 9. Development Setup
+
+```markdown
+## Development
+
+```bash
+git clone <repo-url>
+cd project
+npm install
+```
+```
+
+Auto-fill from CLAUDE.md `Run` and `Build` commands.
+
+### 10. Running Tests
+
+```markdown
+## Tests
+
+```bash
+npm test
+npm run lint
+```
+```
+
+Auto-fill from CLAUDE.md `Test` and `Lint` commands.
+
+### 11. Contributing
+
+```markdown
+## Contributing
+
+1. Fork the repo.
+2. Create a feature branch (`git checkout -b feature/my-thing`).
+3. Commit changes (`git commit -am 'Add my thing'`).
+4. Push (`git push origin feature/my-thing`).
+5. Open a Pull Request.
+```
+
+### 12. Changelog
+
+```markdown
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/releases).
+```
+
+### 13. Links
+
+```markdown
+## Links
+
+- Repository: https://github.com/user/repo
+- Issue tracker: https://github.com/user/repo/issues
+```
+
+### 14. License
+
+```markdown
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+```
+
+Detect from CLAUDE.md or project LICENSE file.
+
+### 15. Credits (optional)
+
+```markdown
+## Credits
+
+Built with [bigpowers](https://github.com/danielvm-git/bigpowers).
+```
+
+## Verify
+
+After generation, run: `grep -c "^## " README.md` — expect ≥ 7 section headings.

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [2.4.0](https://github.com/danielvm-git/bigpowers/compare/v2.3.0...v2.4.0) (2026-06-18)
+
+
+### Features
+
+* **skills:** add pi manifest to root package.json for npm/git distribution ([d69af7c](https://github.com/danielvm-git/bigpowers/commit/d69af7c235c48222b6e188dcc44b21627dfd8f9b))
+
+# [2.3.0](https://github.com/danielvm-git/bigpowers/compare/v2.2.0...v2.3.0) (2026-06-18)
+
+
+### Features
+
+* **skills:** add pi agent harness as target platform ([#18](https://github.com/danielvm-git/bigpowers/issues/18)) ([768d911](https://github.com/danielvm-git/bigpowers/commit/768d911ba5a980eb2dcb11ce85a4d0a1813d243b))
+
 # [2.2.0](https://github.com/danielvm-git/bigpowers/compare/v2.1.3...v2.2.0) (2026-06-13)
 
 

package/README.md

@@ -6,7 +6,7 @@
 
 **61 agent skills for high-integrity, spec-driven, test-first software development by solo developers.**
 
-`bigpowers` provides a prescriptive, vertical-slice methodology for building software with AI agents (Claude Code, Gemini CLI, Cursor). It bridges the gap between raw LLM capabilities and professional engineering standards.
+`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.
 
 Published on npm: [bigpowers@2.0.0](https://www.npmjs.com/package/bigpowers)
 
@@ -48,6 +48,7 @@ npm run sync
   - [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
 
 ---
 
@@ -96,6 +97,31 @@ bigpowers
 
 ---
 
+## 🔌 pi Support
+
+bigpowers generates pi Agent Skills and prompt templates alongside Cursor and Gemini artifacts via `sync-skills.sh`.
+
+### Install as a pi package
+
+```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 .
+
+# 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
+
+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.
+
 ## 🏗 The v2.0.0 Lifecycle
 
 Every project follows the **orchestrate-project 6-phase model** (full SOP: [`docs/WORKFLOW-SOP-v2.md`](docs/WORKFLOW-SOP-v2.md)):

package/deepen-architecture/SKILL.md

@@ -8,6 +8,8 @@ description: Find deepening opportunities in a codebase, informed by the domain
 
 Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
 
+**Distinct from `define-language` and `model-domain`:** Use this skill to find module-level refactoring opportunities in the codebase. Use `define-language` to produce a canonical glossary of terms. Use `model-domain` to stress-test a plan through a domain-model interview.
+
 > **HARD GATE** — Deep modules must solve a forcing function, not just be "nice abstractions." If you cannot articulate why the abstraction exists, it is premature.
 
 ## Glossary

package/define-language/SKILL.md

@@ -8,6 +8,8 @@ description: Extract a DDD-style ubiquitous language glossary from the current c
 
 Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to `specs/UBIQUITOUS_LANGUAGE.md`.
 
+**Distinct from `model-domain` and `deepen-architecture`:** Use this skill to produce a canonical glossary of terms (words and definitions). Use `model-domain` to stress-test a plan through an interview that resolves domain model decisions. Use `deepen-architecture` to find module-level refactoring opportunities in the codebase.
+
 > **HARD GATE** — Ubiquitous language is NOT optional. Every term in the domain that could be misunderstood must be glossed. Ambiguity = rework.
 
 ## Process

package/diagnose-root/SKILL.md

@@ -6,6 +6,8 @@ model: sonnet
 
 # Diagnose Root
 
+**Boundary**: Canonical, reusable 4-phase RCA engine. Invoked by `investigate-bug` (as step 2 of the end-to-end flow) and by `fix-bug` (when no bug file exists). Does not write the bug file — that is `investigate-bug`'s responsibility.
+
 Four phases — do not skip. Update the active `specs/bugs/BUG-*.md` file at each phase.
 
 ## Phases

package/edit-document/SKILL.md

@@ -6,6 +6,8 @@ description: Edit and improve documents by restructuring sections, improving cla
 
 # Edit Document
 
+**Distinct from `write-document`:** Use this skill when the document already exists and needs restructuring, clarity, or prose improvements. Use `write-document` to create a document from scratch.
+
 > **HARD GATE** — Document edits must preserve intent and accuracy. Do NOT remove or contradict existing content without understanding why it was written. Check git history for context.
 
 ## Process

package/fix-bug/SKILL.md

@@ -6,13 +6,15 @@ description: Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-
 
 # Fix Bug
 
+**Boundary**: Orchestrator flow — chains `investigate-bug` (entry point + RCA via `diagnose-root`) → `develop-tdd` → `validate-fix`. Does not implement RCA or write bug files directly.
+
 Orchestrates **fix_bug** flow without mixing epic build state.
 
 > **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug`.
 
 ## Process
 
-1. If no `specs/bugs/BUG-*.md`, run `investigate-bug` first (YAML frontmatter + fix plan in file).
+1. If no `specs/bugs/BUG-*.md`, run `investigate-bug` first — it handles history check, RCA (via `diagnose-root`), fix approach, and writes the bug file.
 2. `develop-tdd` against the bug file's verify steps.
 3. `validate-fix` — re-run failing test, full suite, lint.
 4. `bash scripts/sync-bugs-registry.sh` — refresh `specs/bugs/registry.yaml`.

package/grill-me/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: grill-me
 model: sonnet
-description: Stress-test a plan or design through relentless questioning until every decision is resolved. Two modes: Design (default Q&A on decisions) and Docs (grounds every challenge in real library or API documentation). Use when user wants to challenge a plan, validate API assumptions, or mentions "grill me" or "grill me with docs".
+description: Interactive assumption-surfacing Q&A that stress-tests a plan through relentless questioning until every decision is resolved. Use when user wants to challenge a plan, validate decisions from conversation/context, or mentions "grill me". For doc-grounded variant, use grill-with-docs.
 ---
 
 # Grill Me
 
+> **Use this vs grill-with-docs:** `grill-me` surfaces assumptions from the conversation and context alone — no documentation fetching. Use `grill-with-docs` (the doc-grounded variant) when the plan relies on a specific library or external API and every challenge must cite a real doc URL.
+
 Two modes. Default is **Design**. Switch to **Docs** by saying "grill me with docs" or when the plan relies on a specific library or external API.
 
 > **HARD GATE** — Do NOT accept a design until every hard decision has been stress-tested. "Seems right" is not a decision. Grilling must identify and resolve tensions before build begins.

package/grill-with-docs/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: grill-with-docs
-description: Stress-test plan assumptions grounded in real library or API documentation URLs. Use when the plan depends on a specific library or external API, or as a docs-grounded variant of grill-me.
+description: Doc-grounded variant of grill-me — stress-tests plan assumptions by fetching and citing real library or API documentation. Every challenge must cite a real URL. Use when the plan depends on a specific library or external API.
 model: opus
 ---
 
 # Grill With Docs
 
+> **Use this vs grill-me:** `grill-with-docs` is the doc-grounded variant of `grill-me`. Use it when the plan relies on external libraries or APIs and every challenge must be grounded in and cite a real documentation URL. Use `grill-me` for context-only assumption surfacing without fetching docs.
+
 > **HARD GATE** — Every challenge must cite a real documentation URL. No hallucinated APIs.
 
 ## Process

package/investigate-bug/SKILL.md

@@ -6,6 +6,8 @@ description: Investigate a bug or issue by exploring the codebase to find root c
 
 # Investigate Bug
 
+**Boundary**: End-to-end bug entry point — history check → RCA (via `diagnose-root`) → fix approach → TDD plan → bug file. Delegates the 4-phase RCA to `diagnose-root`; does not re-implement it.
+
 Investigate a reported problem, find its root cause, and write a TDD fix plan to `specs/bugs/BUG-*.md`. This is a mostly hands-off workflow — minimize questions to the user.
 
 ## Process
@@ -26,23 +28,15 @@ Do NOT ask follow-up questions yet. Start investigating immediately.
 
 ### 2. Explore and diagnose (4-phase RCA)
 
-Use the Agent tool with subagent_type=Explore to investigate the codebase. Run these phases in order:
-
-**Phase 1 — Reproduce**: Confirm the failure is consistent. Document exact inputs, environment, and observed vs. expected output. Do not proceed until you can reproduce reliably.
-
-**Phase 2 — Isolate**: Trace the code path from entry point to failure. Binary-search the call stack to find which layer first produces wrong output. Target: a single function or module where the wrong behavior first appears.
-
-**Phase 3 — Hypothesize**: Write a falsifiable hypothesis: "The bug occurs because [condition] causes [behavior] instead of [expected]." Generate at least 2 alternatives. Rank by probability.
-
-**Phase 4 — Verify**: Add a targeted assertion or log that fires if your top hypothesis is correct. Run the reproduction case. If confirmed, document the root cause. If not, return to Phase 3 with new evidence.
-
-> **HARD GATE** — Do NOT proceed to Step 3 (Fix Approach) until Phase 4 produces a verified root cause. "It probably is X" is not verified.
+Run the 4-phase root-cause analysis via the `diagnose-root` skill (Reproduce → Isolate → Hypothesize → Verify). That skill is the canonical RCA engine — do not re-implement the phases here.
 
 Also look at:
 - Recent changes to affected files (`git log --oneline <file>`)
 - Existing tests (what's tested, what's missing)
 - Similar patterns elsewhere in the codebase that work correctly
 
+> **HARD GATE** — Do NOT proceed to Step 3 (Fix Approach) until `diagnose-root` Phase 4 produces a verified root cause. "It probably is X" is not verified.
+
 ### 3. Identify the fix approach
 
 Based on your investigation, determine:

package/map-codebase/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: map-codebase
 model: sonnet
-description: "High-fidelity codebase surveying — analyzes stack, architecture, and gray areas (error handling, API shapes) and persists them into specs/tech-architecture/tech-stack.md. Goes beyond survey-context by identifying 'signals' for planning."
+description: "Derives the tech-stack doc from scratch by scanning the codebase — analyzes stack, architecture, and gray areas (error handling, API shapes) and persists findings into specs/tech-architecture/tech-stack.md. Run when the tech doc doesn't exist yet; use survey-context to consume it once it does."
 ---
 
 # Map Codebase
 
 Perform a deep architectural and structural analysis of the codebase. Unlike `survey-context` which identifies "where we are", `map-codebase` identifies "what we are dealing with" and "how things are done".
 
+> **Use this vs survey-context:** `map-codebase` BUILDS the tech-stack doc by scanning the codebase from scratch. `survey-context` READS existing specs/tech-architecture docs without re-deriving them. Run `map-codebase` when `specs/tech-architecture/tech-stack.md` doesn't exist yet; run `survey-context` when it does.
+
 > **HARD GATE** — Cold analysis only. Do NOT assume architectural patterns without reading the code. If the codebase structure surprises you, call out the delta.
 
 ## Process

package/model-domain/SKILL.md

@@ -6,6 +6,8 @@ description: Grilling session that challenges your plan against the existing dom
 
 # Model Domain
 
+**Distinct from `define-language` and `deepen-architecture`:** Use this skill to stress-test a plan through a grilling interview that resolves domain model decisions and captures invariants. Use `define-language` to produce a canonical glossary of terms. Use `deepen-architecture` to find module-level refactoring opportunities in code.
+
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
 
 > **HARD GATE** — Capture invariants (what MUST always be true) and state machines (what transitions are legal) for core entities. If these are fuzzy, design will fail.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "61 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {
@@ -22,8 +22,17 @@
     "claude",
     "development",
     "spec-driven",
-    "test-first"
+    "test-first",
+    "pi-package"
   ],
+  "pi": {
+    "skills": [
+      "./.pi/skills"
+    ],
+    "prompts": [
+      "./.pi/prompts"
+    ]
+  },
   "author": "Daniel",
   "license": "MIT",
   "homepage": "https://github.com/danielvm-git/bigpowers#readme",

package/plan-release/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: plan-release
 model: sonnet
-description: Convert elaborated specs into a structured release plan with Gherkin acceptance criteria and WSJF-sorted epics. Produces specs/release-plan.yaml and epic capsule directories (specs/epics/eNN-slug/) with epic.yaml manifests, countable-story-format .md specs, and decoupled -tasks.yaml files. Use when a spec is clear and ready to plan, after elaborate-spec, or when the user wants a release plan broken into epics and stories.
+description: "RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/release-plan.yaml with WSJF ordering and BCP baselines. NOT a planning-spine substitute: it does not scope work (scope-work) or write story tasks (plan-work). Use after elaborate-spec when the user wants a versioned release index of epics."
 ---
 
 # Plan Release

package/plan-work/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: plan-work
 model: opus
-description: Write detailed implementation tasks into the active epic capsule directory (specs/epics/eNN-slug/). Produces decoupled story .md specs (countable-story-format) and runnable -tasks.yaml files. Every task must include a runnable verify command. Use when user needs step-by-step plan with evidence, or after plan-release.
+description: "PLANNING SPINE STEP 3 of 3 — Plan the work: write detailed implementation tasks into the active epic capsule (specs/epics/eNN-slug/). Produces countable-story-format .md specs and runnable -tasks.yaml files. Use after slice-tasks (step 2). Not a substitute for scope-work (step 1) or slice-tasks (step 2)."
 ---
 
 # Plan Work
 
+> **Spine position:** Step 3 — scope-work → slice-tasks → plan-work.
+
 Produce a detailed, verifiable implementation plan in the **active epic capsule directory** (`specs/epics/eNN-slug/`). Output: a story spec `.md` file (countable-story-format) and a decoupled `eNNsYY-tasks.yaml` with runnable verify commands. "I think it works" is not a step.
 
 > **HARD GATE** — Do NOT proceed with a plan until the task's success criteria are clear. If success is ambiguous, run `define-success` first to convert the task into "step → verify: <cmd>" pairs.

package/release-branch/SKILL.md

@@ -16,10 +16,12 @@ Finalize a completed feature branch: verify coverage gates, integrate onto `main
 
 ## Integrate mode
 
+Read `specs/state.yaml` key `workflow_mode` first (`team-pr` | `solo-git`). Fall back to sniffing `profiles/solo-git.md` only when the key is absent.
+
 | Mode | When | Ship path |
 |------|------|-----------|
-| **solo-local** | `profiles/solo-git.md` active | `bash scripts/land-branch.sh <branch> "<conventional message>"` |
-| **team-pr** | Default / remote CI required | `gh pr create` → `gh pr merge --squash` |
+| **solo-local** | `workflow_mode: solo-git` (or `profiles/solo-git.md` present as fallback) | `bash scripts/land-branch.sh <branch> "<conventional message>"` |
+| **team-pr** | `workflow_mode: team-pr` (default) | `gh pr create` → `gh pr merge --squash` |
 
 If unsure and working alone, prefer **solo-local**.
 

package/run-planning/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: run-planning
 model: sonnet
-description: Advance discover-phase workflows and update specs/planning-status.yaml. Use for survey, scope, research, plan-release chain without touching build epics.
+description: "DISCOVER-PHASE ADVANCER — Drive the discover-phase checklist (specs/planning-status.yaml) through survey-context → scope-work → research-first → elaborate-spec → plan-release → slice-tasks. NOT a duplicate of plan-work or the planning spine; it orchestrates the pre-coding discover phase only."
 ---
 
 # Run Planning
-> **HARD GATE** — **HARD GATE** — Before running planning skills, confirm the epic capsule exists and the active story is clear. Planning without a target is noise.
+> **HARD GATE** — Before running planning skills, confirm the epic capsule exists and the active story is clear. Planning without a target is noise.
 
+> **Role:** DISCOVER-PHASE ADVANCER — orchestrates the discover-phase sequence; hands off to the scope-work → slice-tasks → plan-work spine for implementation planning.
 
 Updates `specs/planning-status.yaml` as discover-phase skills complete.