bigpowers 2.1.3 → 2.3.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.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)
+
+
+### Features
+
+* **skills:** enforce tiered SKILL.md size cap (Epic 4) ([5b66257](https://github.com/danielvm-git/bigpowers/commit/5b66257bcb7c5c01246e8cbf02e6cb701120eae0))
+
 ## [2.1.3](https://github.com/danielvm-git/bigpowers/compare/v2.1.2...v2.1.3) (2026-06-12)
 
 

package/CLAUDE.md

@@ -21,7 +21,7 @@ Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code,
 
 ## Architecture
 
-Collection of 61 verb-noun skills, each with a SKILL.md source file and supporting documentation. Runtime specs live in `specs/state.yaml`, `specs/release-plan.yaml`, and `specs/execution-status.yaml`; intent in `specs/requirements/`; epic shards in `specs/epics/`. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning output goes to specs/ at the project root.
+Collection of 61 verb-noun skills, each with a SKILL.md source file and supporting documentation. Runtime specs live in `specs/state.yaml`, `specs/release-plan.yaml`, and `specs/execution-status.yaml`; intent in `specs/product/`; epic shards in `specs/epics/`. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning output goes to specs/ at the project root.
 
 ## Conventions
 

package/CONVENTIONS.md

@@ -59,7 +59,13 @@ Every skill that produces written output writes to `specs/` at the project root.
 
 ### BCP accounting mandate (v2.0.0)
 
-Every task written by `plan-work` MUST be labeled `[BCP N]` where N is the estimated Build Commit Points for that task. The story total is summed and written to `state.yaml` as `epic_cycle.story_bcps`. The BCP baseline for each story MUST appear in `specs/release-plan.yaml` before implementation begins. `release-branch` automatically appends a row to `specs/metrics/cycle-times.yaml` with the final BCP/hr after the story lands.
+**BCP = Business Complexity Points** — a pre-build story size, not a per-task annotation. Canonical method: [`docs/references/bcp.md`](docs/references/bcp.md) (sourced from `flow-ciandt/bcp-agent`).
+
+- **Sizing (plan-release):** Every story in `specs/release-plan.yaml` MUST have a `bcps:` field set via the 6-step BCP sizing method before implementation begins. No story enters the build queue without a BCP baseline.
+- **Session state:** `plan-work` confirms the BCP size and writes it to `specs/state.yaml` as `epic_cycle.story_bcps`.
+- **Velocity (release-branch):** After landing, `release-branch` appends a row to `specs/metrics/cycle-times.yaml` with `bcp_per_hour = story_bcps / cycle_minutes * 60`.
+
+BCP is a **story-level** size. Per-task `[BCP N]` annotations are not part of the canonical method.
 
 ### Timestamp mandate (v2.0.0)
 
@@ -76,9 +82,9 @@ Every critical-path skill (survey-context, plan-work, kickoff-branch, develop-td
 
 | Question | File | Format |
 |----------|------|--------|
-| What should the product do? | `specs/requirements/SCOPE_LATEST.yaml` | YAML |
-| North star / initiative | `specs/requirements/VISION_LATEST.yaml` | YAML |
-| Glossary | `specs/requirements/GLOSSARY_LATEST.yaml` | YAML |
+| What should the product do? | `specs/product/SCOPE_LATEST.yaml` | YAML |
+| North star / initiative | `specs/product/VISION_LATEST.yaml` | YAML |
+| Glossary | `specs/product/GLOSSARY_LATEST.yaml` | YAML |
 | What ships in this release, in what order? | `specs/release-plan.yaml` | YAML |
 | How to implement an epic/story? | `specs/epics/eNN-*.yaml` or `specs/epics/eNN-*/stories/` | YAML + MD |
 | Where are we in the session? | `specs/state.yaml` | YAML |
@@ -87,7 +93,7 @@ Epic IDs: `e01`, `e30`. Story IDs: `e01s01`. One FR in SCOPE may span multiple e
 
 ### Frozen release (ex-baseline)
 
-When planning closes, copy to `specs/requirements/snapshots/release-<version>/` (`release-plan.yaml`, `SCOPE_LATEST.yaml`, `VISION_LATEST.yaml`). No separate `baselines/` folder.
+When planning closes, copy to `specs/product/snapshots/release-<version>/` (`release-plan.yaml`, `SCOPE_LATEST.yaml`, `VISION_LATEST.yaml`). No separate `baselines/` folder.
 
 ### Semantic-release — three places
 
@@ -99,11 +105,11 @@ When planning closes, copy to `specs/requirements/snapshots/release-<version>/`
 
 | Document | Path |
 |----------|------|
-| Stack / architecture | `specs/plans/TECH_STACK_LATEST.md` |
-| Security / test / design plans | `specs/plans/*_PLAN_LATEST.md` |
-| Domain context + ADRs | `specs/plans/TECH_STACK_LATEST.md` or legacy `specs/CONTEXT.md` + `specs/adr/` |
+| Stack / architecture | `specs/tech-architecture/TECH_STACK_LATEST.md` |
+| Security / test / design plans | `specs/tech-architecture/*_PLAN_LATEST.md` |
+| Domain context + ADRs | `specs/tech-architecture/TECH_STACK_LATEST.md` or legacy `specs/CONTEXT.md` + `specs/adr/` |
 | Bug investigation | `specs/bugs/BUG-*.md` + `specs/bugs/registry.yaml` (generated) |
-| Refactor / impact | `specs/plans/REFACTOR_LATEST.md`, `specs/plans/IMPACT_LATEST.md` |
+| Refactor / impact | `specs/tech-architecture/REFACTOR_LATEST.md`, `specs/tech-architecture/IMPACT_LATEST.md` |
 | Legacy markdown | `specs/archive/` after `bash scripts/convert-legado.sh` |
 
 Validate YAML layout: `bash scripts/validate-specs-yaml.sh`. Patch runtime keys: `bash scripts/bp-yaml-set.sh specs/state.yaml git.branch feat/foo`.
@@ -114,7 +120,7 @@ Validate YAML layout: `bash scripts/validate-specs-yaml.sh`. Patch runtime keys:
 |-----|-----|
 | `specs/STATE.md` | `specs/state.yaml` |
 | `specs/RELEASE-PLAN.md` | `specs/release-plan.yaml` + `specs/epics/` |
-| `specs/SCOPE.md` | `specs/requirements/SCOPE_LATEST.yaml` |
+| `specs/SCOPE.md` | `specs/product/SCOPE_LATEST.yaml` |
 
 ## Code Style
 

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)):
@@ -137,9 +163,9 @@ ONCE/PROJECT orchestrate-project
 | Level | Document | Responsibility |
 | :--- | :--- | :--- |
 | **Vision** | `docs/PRINCIPLES.md` | Philosophical foundations and evolution. |
-| **Context** | `specs/plans/TECH_STACK_LATEST.md` | Tech stack, architecture, and domain notes. |
-| **Scope** | `specs/requirements/SCOPE_LATEST.yaml` | In-scope / out-of-scope and success criteria. |
-| **Vision** | `specs/requirements/VISION_LATEST.yaml` | North star and initiative success criteria. |
+| **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. |

package/build-epic/SKILL.md

@@ -30,7 +30,7 @@ Orchestrates the **build** flow for a single epic: survey → plan tasks → kic
 ## Process
 
 1. Read `specs/state.yaml`, `specs/execution-status.yaml`, `specs/release-plan.yaml`, active `specs/epics/eNN-slug/epic.yaml`.
-2. **BCP Tracking (Step 2):** After `plan-work` completes, read the `bcps:` count from the epic capsule and carry it into `state.yaml` as `epic_cycle.story_bcps = N`.
+2. **BCP Tracking (Step 2):** After `plan-work` completes, read the `bcps:` count (Business Complexity Points story size) from the epic capsule and carry it into `state.yaml` as `epic_cycle.story_bcps = N`.
 3. If `epic_cycle.step` missing, set to `1`.
 4. Run **only the current step** (resume mode) unless user asked for full auto-run.
 5. After step verify passes, increment `epic_cycle.step` in `state.yaml` (or `bash scripts/bp-yaml-set.sh` if available).

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/develop-tdd/REFERENCE.md

@@ -0,0 +1,61 @@
+# Develop TDD — Reference
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" — treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things rather than user-facing behavior
+- Tests become insensitive to real changes
+
+**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+> The Red Flags table lives in [SKILL.md](SKILL.md#red-flags) — it is core behavioral guidance, not reference detail.
+
+## TDD Phases (Detail)
+
+### Red Phase
+
+Write a failing test first:
+- Test describes the desired observable behavior through the public interface
+- Run the test to confirm it fails for the right reason (not a syntax error, not a typo)
+- Commit: `git commit -m "test(<scope>): <description>"`
+
+### Green Phase
+
+Write the minimum code to make the test pass:
+- No extra logic, no anticipated future cases, no premature optimization
+- Focus only on making the current test pass
+- Commit: `git commit -m "feat(<scope>): <description>"` or `"fix(<scope>): <description>"`
+
+### Refactor Phase
+
+Improve structure without changing behavior:
+- Extract duplication, apply SOLID principles where natural, deepen modules
+- Run tests after each refactor step to ensure behavior is preserved
+- Commit: `git commit -m "refactor(<scope>): <description>"`
+- Apply the Boy Scout Rule: leave the code cleaner than you found it
+
+## Visual Slices (UI Alternate Workflow)
+
+For UI components (SwiftUI, React, Flutter) where behavioral unit testing is brittle or low-signal:
+
+1. **Test-First Logic**: Extract logic (state transitions, formatting, validation) into a Controller, ViewModel, or Hook. This logic MUST follow pure TDD.
+2. **Visual Verification**: For the View/Component itself:
+   - **RED**: Write the component signature and a basic preview/snapshot that fails (or displays placeholder).
+   - **GREEN**: Implement the UI and verify visually via manual run, preview, or snapshot test.
+   - **REFINE**: Adjust styling and layout until it matches the design.
+3. **COMMIT**: `git commit -m "feat(ui): <component name> visual slice verified"`