@jaybeeuu/agent-cortex 1.20.0

package/skills/style/style-documentation/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: style-documentation
+description: Defines what to document, what to skip, and how to structure documentation for TypeScript projects. Use BEFORE writing or updating any documentation (READMEs, doc comments, guides), when reviewing existing docs for drift, or when setting up "documentation conventions".
+---
+
+# Documentation Style
+
+## When to use
+
+- Deciding whether to write or update documentation.
+- Reviewing existing documentation for drift or completeness.
+- Asked for a "docs review", "what should I document", or "documentation conventions".
+
+## When NOT to use
+
+- General writing tone, structure, and concision — use `style-comms` instead. This skill layers on top of it.
+- Writing API reference docs that describe how a function works — that belongs in code comments, not a doc.
+
+## Philosophy / rationale
+
+- **The code is the documentation.** Written docs exist to capture what the code cannot communicate on its own. A reader who can read the code should not need the docs to understand *how* something works — only a brief orientation, *why* it works that way, what decisions shaped it, and how the pieces fit together at a high level.
+- **Sparse docs maintained well beat comprehensive docs that drift.** Every word that falls out of sync with reality actively misleads. Fewer words, kept accurate, is a winning strategy.
+- **Docs need grooming like code.** Each doc is a commitment to maintain. Prune outdated content, update what changed, delete what no longer serves. A doc that does not earn its keep should be removed.
+- **Gift future engineers a starting point.** Write docs that point to the code and explain the journey that led to it, not that restate it.
+
+## Workflow
+
+1. **Find what already exists.** Search the project and wider knowledge base for relevant documentation — ADRs, READMEs, inline docs, `docs/` directories, and any team Confluence pages. A surprising number of documentation changes are updates to documents you forgot existed.
+
+2. **Decide what action is needed.** Evaluate the subject against these criteria:
+   - **Nothing changed, nothing missing** — leave it. Doing nothing is often the correct outcome.
+   - **Something changed** — update the existing document. Add a sentence noting what changed and why.
+   - **Existing doc is stale or misleading** — prune the outdated parts or delete it outright. Stale docs actively mislead; a deleted doc leaves a clean gap that someone will fill correctly.
+   - **No documentation exists and a criterion below is met** — create something new.
+
+   Only create new documentation when at least one of these is true:
+   - A decision was made — why this approach over a reasonable alternative.
+   - Macro behaviour changed — what the system now does that it didn't before, at a level above the code.
+   - A constraint exists that isn't visible in the code — a trade-off, an upstream dependency, a known limitation.
+   - No orientation exists for this area — add a brief overview covering intent, purpose, and how it fits into the wider system.
+
+3. **Choose the smallest viable change.** The order of preference is:
+   - Update an existing document.
+   - Add a single well-placed sentence.
+   - Add a paragraph.
+   - Add a new section.
+   - Create a new file (last resort — only when no suitable home exists).
+
+4. **Write for the reader who knows the code.** Provide a brief orientation, explain the decisions, show how the pieces fit. Do not restate implementation detail — the code already does that.
+
+5. **Keep it concise.** Use plain prose. Reserve bullet points for genuinely enumerable items. Do not use headings for documents shorter than three sections.
+
+6. **Check tone and structure.** Invoke `style-comms` for guidance on tone, concision, and document structure. This skill governs *what* and *whether* to document; style-comms governs the *how*.
+
+7. **Scan for secrets.** Run `review-security` before committing to catch any credentials, tokens, or real values that leaked into examples or sample configs.
+
+## Red Flags
+
+- **Documenting implementation detail.** If a reader can learn it in under a minute by reading the code, it doesn't belong in a doc.
+- **Writing speculatively.** Decisions that haven't been made yet are aspirations, not documentation. They capture a wish, not reality.
+- **Creating a new file unnecessarily.** A sentence in an existing document is cheaper to find, read, and maintain than a new file that fragments knowledge.
+- **Documenting for the sake of it.** Docs, like code, carry a maintenance cost. Every doc must earn its place — and once written, it must be groomed, pruned, and kept accurate. A doc that drifts from reality is worse than no doc at all.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "I'll add docs later" | If the context is fresh now, it's fresh. Later you will have forgotten the nuance. Write it now or don't. |
+| "More docs is always better" | Every word that drifts from reality actively misleads. Sparse accurate docs beat comprehensive drift. |
+| "This is obvious from the code" | Then do not write it. The code is the documentation — let it do the work. |
+| "This doc is harmless even if it drifts" | Drift is not harmless — it erodes trust. Every stale sentence makes the reader wonder what else is wrong. Prune or update instead. |
+
+## Cross-skill references
+
+| When you need… | Use this skill |
+|---|---|
+| Tone, structure, and concision for writing | `style-comms` |
+| Code-level conventions and inline comments | `style-code` |
+| Secrets and credential scanning before committing | `review-security` |
+
+## Examples
+
+### Decision documented vs aspirational
+
+| Instead of… | Write… |
+|---|---|
+| "We may want to migrate to Kafka in the future." | "We chose RabbitMQ over Kafka because our throughput fits the simpler model and operational overhead was critical. See ADR-004 for the full tradeoff." |
+
+### Brief orientation vs implementation restatement
+
+| Instead of… | Write… |
+|---|---|
+| Three paragraphs on how `calculateFees` iterates over transactions and applies each rate tier | "Fees are computed per-transaction using tiered rates defined in `src/fees/rates.ts`. See the module docs for the exact logic." |
+
+### Maintenance first
+
+| Instead of… | Write… |
+|---|---|
+| Writing a new `docs/deployment-kubernetes.md` repeating steps already in `README.md` | Searching first, then adding a sentence to the existing "Deployment" section linking to the K8s manifests |
+| Leaving a stale ADR that references a replaced approach | Pruning the outdated decision record or marking it superseded with a link to the replacement |
+| Adding a new doc for a concept already partially covered in three places | Consolidating into one well-maintained location, deleting the others |
+
+## Verification checklist
+
+- [ ] Searched for existing documentation on the subject before writing
+- [ ] Stale or misleading content was pruned or updated, not left to rot
+- [ ] Documentation passes the "code can't communicate this on its own" test
+- [ ] No implementation detail restated from the code
+- [ ] No speculative or aspirational content about undecided features
+- [ ] Uses the smallest viable change (existing doc → sentence → paragraph → section → new file)
+- [ ] Tone and structure checked against `style-comms`
+- [ ] Staged changes scanned with `review-security` for leaked secrets

package/skills/style/style-tests/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: style-tests
+description: Defines this project's test-writing conventions — assertion strategy, mock discipline, and what to test. Use BEFORE writing or editing any test and when reviewing tests — consult it whenever you add or change test files rather than choosing an approach ad hoc. Also for a "test review", "mock strategy", or deciding "what to test".
+---
+
+# Test Style
+
+## When to use
+
+- Writing new tests, reviewing existing tests, or debugging a failing test suite.
+- Deciding between unit, integration, or e2e for a given behaviour.
+- Asked for a "test review", "what should I test", or "is this test well-written".
+
+## When NOT to use
+
+- The red-green-refactor development loop — use `tdd` instead.
+- Code-level style and conventions — use `style-code`.
+
+## Philosophy / rationale
+
+- **Test behaviour, not implementation.** A passing test should survive a refactor that does not change observable behaviour. If a test fails after a refactor that preserved behaviour, the test was wrong.
+- **Prefer sociable tests over mockery.** Favour integration tests over unit tests. Reserve unit tests for complex functional logic that benefits from tight isolation. Use e2e smoke tests to prove the system hangs together. This is the testing trophy, not the testing pyramid.
+- **Every test has a cost.** Time to write, run, and maintain. Only write a test when its value exceeds its weight. Each behaviour should be covered at least once — ideally only once.
+
+## Workflow
+
+1. **Determine the test level.** Can you test this behaviour through the module's public API or interface? Prefer integration-level tests. Reserve unit tests for complex functional logic that genuinely benefits from tight isolation. Use a small number of e2e smoke tests to prove the system hangs together.
+
+2. **Decide what to mock.** Mock as little as possible. A useful mental model: mock what is **above** the module under test in the dependency tree, not below it. At the integration level, mock only genuine external systems. At e2e, mock almost nothing.
+
+3. **Write the test structure.** Use a `describe` block per module or function; use `it` per behaviour. Name tests descriptively — the name should communicate what the system does, not how. The relationship between setup, action, and assertion should be self-evident.
+
+4. **Set up data.** Inline what matters — any value that is asserted on or establishes the test condition must appear inline in the test body. Use factory/builder helpers for complex objects with sensible defaults, but any value that changes the test condition must be an explicit override, never buried in a default. Avoid `before`/`after` hooks for shared state; they are acceptable only for expensive, non-observable infrastructure setup (e.g. starting a server or database).
+
+5. **Write targeted assertions.** Prefer `toMatchObject` over asserting every property. Multiple assertions are fine when they all verify the same behaviour. Avoid asserting call counts when asserting call arguments already covers the behaviour.
+
+6. **Review against the checklist below.** Read the test as if you are seeing the codebase for the first time.
+
+## Red Flags
+
+- **Mocking implementation details.** Hooking into internal module structure ties tests to code shape, not behaviour. Mock the module's public interface instead.
+- **Duplicating type or lint coverage.** Types and linting already provide those guarantees. Repeating them with assertions adds maintenance cost for zero value.
+- **Skipping flaky tests.** A flaky test is a broken test. Fix it or delete it. Skipping normalises unreliability across the suite.
+- **Sharing state via hooks.** Tests must be fully independent. `before`/`after` hooks that set up shared mutable state create order-dependent failures.
+- **`any` or unsafe casts in test code.** Test code is production code. Be strict with types — no `any`, no unsafe casts, no cutting corners.
+- **Skipping a failing test.** A failing test means behaviour broke. Investigate and fix it — do not paper over it.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "It passed locally" | CI is the only truth. If a test is flaky, it is broken — fix or delete. |
+| "I'll mock this to keep the test simple" | Over-mocking hides integration bugs. Mock the boundary, not the internals. |
+| "I'll fix the flake later" | No you will not. Fix it now or delete it. |
+| "This test is too small for that pattern" | Small tests benefit from structure too. Consistency beats shortcuts. |
+| "I'll skip this failing test and come back" | A skipped test is a blind spot. The failure is telling you something — listen to it. |
+
+## Cross-skill references
+
+| When you need… | Use this skill |
+|---|---|
+| Red-green-refactor development loop | `tdd` |
+| Code-level style and conventions | `style-code` |
+| Secrets and credential scanning | `review-security` |
+
+## Examples
+
+### Mock boundaries
+
+| Instead of… | Write… |
+|---|---|
+| Mocking the internal database driver to verify a query was called | Testing through the repository interface with a test double at that boundary |
+| Mocking `fetch` in a unit test for an API client | Testing the client with a real HTTP stub that returns controlled responses |
+
+### Targeted assertions
+
+| Instead of… | Write… |
+|---|---|
+| `expect(result).toEqual(fullExpectedObject)` with every field asserted | `expect(result).toMatchObject({ status: "success", id: expect.any(String) })` |
+| `expect(mockSave).toHaveBeenCalledTimes(1)` and then `expect(mockSave).toHaveBeenCalledWith(data)` | Just the call-args assertion — count is redundant |
+
+### Factory overrides
+
+| Instead of… | Write… |
+|---|---|
+| `const user = createUser();` where the test needs `isAdmin: true` but the default happens to set it | `const user = createUser({ isAdmin: true });` — explicit override visible in the test body |
+
+## Verification checklist
+
+- [ ] Test verifies behaviour, not implementation structure
+- [ ] No mocking of internal module details — only public interfaces
+- [ ] No `before`/`after` hooks for shared test state (infrastructure setup only)
+- [ ] Assertions are targeted — no over-asserting or redundant checks
+- [ ] No skipped or commented-out tests
+- [ ] No flaky tests — all deterministic
+- [ ] No `any` or unsafe casts in test code
+- [ ] No duplication of type or linting coverage

package/skills/workflow/git-workflow/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: git-workflow
+description: "Enforces git discipline: feature branches over direct pushes, git worktrees for isolation, and GitHub PRs for all changes. Use when making any change to a codebase — this is the default workflow."
+---
+
+# Git Workflow
+
+Follow this workflow when asked to make changes unattended (AFK-mode). When
+collaborating with a human on the same branch, work in their workspace —
+do not create a separate worktree that splits attention.
+
+If unsure whether you're working solo or collaboratively, ask.
+
+## Rules
+
+### 1. Feature branches — always
+
+Never commit directly to `main` or `master`. Every change gets a feature branch.
+
+```
+❌ git commit -m "fix"          # on main — never
+✅ git checkout -b feat/my-thing
+```
+
+Branch naming:
+- `feat/<description>` — new features
+- `fix/<description>` — bug fixes
+- `refactor/<description>` — refactoring
+- `chore/<description>` — tooling, config, CI, docs
+
+### 2. Git worktrees — for unattended solo work
+
+Use `git worktree add` to create an isolated working directory instead of
+stashing or switching branches in-place. Worktrees let you work on multiple
+branches simultaneously without interference.
+
+```bash
+git worktree add ../my-repo-feat-branch feat/my-branch
+```
+
+Worktrees are cheaper than clones (shared object store) and safer than
+stashing — **but only when you're working solo**. If the human is also
+working on the same thing, use a shared branch and workspace instead.
+
+**When collaborating**: ask the human what workspace/branch they're on. Do
+not spin up a separate worktree — work in the same checkout so you both see
+the same state.
+
+### 3. Pull requests for review
+
+Every feature branch ends in a GitHub PR. Open the PR early (draft if unfinished) so the diff is visible.
+
+```bash
+gh pr create --title "..." --body "..."
+gh pr create --draft  # early
+```
+
+### 4. Sync before branching
+
+Before creating a feature branch, sync with upstream:
+
+```bash
+git checkout main
+git pull
+```
+
+This avoids avoidable merge conflicts.
+
+### 5. Worktree lifecycle
+
+After the PR is merged or closed, clean up the worktree:
+
+```bash
+cd /path/to/main/repo
+git worktree remove ../my-repo-feat-branch
+git branch -d feat/my-branch
+```
+
+## When NOT to use
+
+- **Collaborating with a human** on the same code — use their workspace,
+  not a separate worktree.
+- Single-character typo fixes that are already on a branch.
+- Emergency hotfixes to production that bypass normal process (rare, explicit).
+- **If unsure** whether you're working solo or alongside a human: ask.

package/skills/workflow/hitl-collab/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: hitl-collab
+description: Coordinates HITL collaboration by producing a handoff document and optionally updating the HITL bead with a summary and doc link. Use when a task requires human review/approval, manual steps, or PR handoff collaboration.
+---
+
+# HITL Collab
+
+## Quick start
+
+1. Run `bd show <bead-id>` (bead ID is required).
+2. Create `.agent-cortex/working-docs/hitl/<bead-id>/handoff.md`.
+3. If the bead lacks **PR/branch links + manual steps + acceptance criteria**, add a short note with those details and the handoff doc path via `bd update <bead-id> --notes "<text>"`.
+
+## Handoff doc template
+
+- **Summary**
+- **Why HITL**
+- **PR/branch links**
+- **Acceptance criteria**
+- **Manual steps**
+- **Verification checklist**
+- **References** (optional)
+
+## Workflow
+
+1. Gather context from the bead description and any referenced PRs/branches.
+2. Write the handoff doc using the template above. Use the `style-comms` skill for tone.
+3. Use `.agent-cortex/working-docs/hitl/<bead-id>/` as the home for any additional notes, scripts, screenshots, or logs needed for collaboration.
+4. Only update the bead if it is missing **PR/branch links**, **manual steps**, or **acceptance criteria**. Include the handoff doc path in the note.

package/skills/workflow/plan/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: plan
+description: Guide a feature from first discussion through PRD and task breakdown to classified beads ready for execution, then produce a handoff bead for ralph. Use when starting a new feature, scoping work to hand off to ralph, investigating a codebase change and structuring the work, or saying "plan this" or "get this ready for ralph".
+argument-hint: Feature description, PRD draft, or goal you want to plan.
+---
+
+# Plan
+
+Orchestrate the full ideate → specify → decompose → classify → handoff workflow. Produces a complete bead tree (epics + classified tasks with pipeline stages) and a top-level bead ID to pass to a separate agent running the `ralph` skill.
+
+Covers everything needed to prepare work for autonomous execution: understand the problem, write a PRD, break it into vertical-slice tasks, classify each one, and expand AFK tasks into pipeline-stage chore beads. Stops before execution — the user reviews the plan, then hands off a bead ID to ralph.
+
+## When to use
+
+- "Plan this feature for me"
+- "Get this ready for ralph"
+- "I need to investigate a codebase change, scope the work, and set up the beads"
+- User wants the full flow: investigation → PRD → task breakdown → classified beads → handoff
+- User has an existing PRD and wants to skip to the breakdown and bead creation (step in at Phase 2)
+
+## When NOT to use
+
+- User already has a PRD and just needs it broken into tasks — use `prd-to-tasks` directly.
+- Single well-understood task that just needs a bead — use `create-task`.
+- Raw idea not ready for implementation planning — use `record-idea`.
+- Detailed refactor plan with commit-level steps — use `request-refactor-plan`.
+- Beads already exist and just need execution — use `ralph` directly.
+
+## Workflow
+
+### Phase 1 — Understand and specify
+
+Establish what needs to be built through investigation and collaborative design.
+
+1. Ask the user to describe the problem, goal, or feature in their own words. Listen for what currently exists, what is missing, and what success looks like.
+
+2. Explore the codebase to verify the user's assertions and understand the current state of the relevant areas. Investigate:
+   - Existing architecture and data models
+   - Similar features already implemented
+   - Integration points (APIs, databases, third-party services)
+   - Test patterns and coverage conventions
+
+3. Interview the user relentlessly about every aspect of the plan until reaching shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. Cover:
+   - Scope boundaries — what is in and what is explicitly out
+   - Key data models and their relationships
+   - Module boundaries and interfaces
+   - Technical constraints and trade-offs
+   - How each change will be verified
+
+4. Sketch the major modules that will be built or modified. Look for opportunities to extract deep modules — ones that encapsulate significant behaviour behind a simple, testable interface.
+
+5. Draft a PRD using the template from `write-a-prd`. Include:
+   - Problem statement and solution summary
+   - Numbered user stories covering all aspects
+   - Implementation decisions (modules, interfaces, technical clarifications)
+   - Out-of-scope items
+
+6. Present the PRD to the user for review. Iterate until they approve it.
+
+7. Create an epic bead from the approved PRD:
+   ```bash
+   bd create "<Feature Title> — PRD" --type epic \
+     --description "<rendered PRD as markdown>" --priority p2
+   bd tag <epic-id> workflow:plan
+   ```
+
+#### Phase 1 gate
+
+- [ ] Codebase explored and assertions verified
+- [ ] Design decisions resolved through interview
+- [ ] Modules sketched and reviewed with the user
+- [ ] PRD drafted and approved by the user
+- [ ] Epic bead created from approved PRD
+
+### Phase 2 — Break into tasks
+
+Take the approved PRD and produce a set of epics and tasks using tracer-bullet vertical slices.
+
+8. Review the user stories and implementation decisions from the PRD. Identify natural phase boundaries — each phase should be a thin end-to-end slice through all layers (schema, API, logic, UI, tests) that is demoable on its own.
+
+9. For each phase, define:
+   - **Title**: short descriptive name
+   - **User stories covered**: which PRD stories this phase addresses
+   - **What to build**: end-to-end behaviour description
+   - **Acceptance criteria**: verifiable outcomes
+
+10. If the work is small enough for a single epic (one phase, a few tasks), skip epics and proceed directly to Phase 3. A single epic with a few tasks dispatches through ralph more efficiently than creating unnecessary epic hierarchy. If the work has multiple distinct phases, create epics:
+    ```bash
+    bd create "<Phase Title>" --type epic \
+      --description "<epic body with scope, criteria, dependencies>" --priority <same as parent>
+    bd tag <epic-id> workflow:plan
+    bd dep add <epic-id> <parent-epic-id> --type parent-child
+    ```
+
+11. Present the proposed phase/task breakdown to the user. Ask:
+    - Does the granularity feel right?
+    - Should any phases be merged or split?
+    - Are the dependency relationships correct — can any run in parallel?
+
+12. Iterate until the user approves the breakdown. Every phase and task must represent a thin vertical slice.
+
+#### Phase 2 gate
+
+- [ ] Phases identified as vertical slices (not horizontal layers)
+- [ ] Each phase has documented acceptance criteria
+- [ ] Breakdown approved by the user
+
+### Phase 3 — Create and classify beads
+
+For each task (within each epic), create a bead, classify it, and expand AFK tasks into pipeline-stage chore beads.
+
+13. For each task in dependency order (blockers first), create the task bead via `create-task`:
+    ```bash
+    # create-task handles: bead creation → classify → AFK: expand into pipeline stages → HITL: stop
+    ```
+    Pass the parent epic ID (if epics are used) so tasks are nested under their epic.
+
+14. After all tasks in an epic are created, tag the parent epic with the aggregate classification:
+    - If **any** task is HITL: `bd tag <epic-id> implementation-type:hitl`
+    - If **all** tasks are AFK: `bd tag <epic-id> implementation-type:afk`
+
+15. Present the full bead tree to the user:
+    ```
+    Epic: "Phase 1 Title" (#epic-abc)
+      ├── Task 1: "..." (#task-123) — AFK
+      ├── Task 2: "..." (#task-456) — HITL (visual review)
+      └── Task 3: "..." (#task-789) — AFK
+    Epic: "Phase 2 Title" (#epic-def)
+      ├── ...
+    ```
+
+#### Phase 3 gate
+
+- [ ] All tasks created via `create-task`
+- [ ] All tasks classified (AFK or HITL)
+- [ ] AFK tasks expanded into pipeline-stage chore beads plus PR gate
+- [ ] Parent epics tagged with aggregate `implementation-type`
+- [ ] Full bead tree presented to the user
+
+### Phase 4 — Prepare handoff to ralph
+
+Deliver a handoff bead and instructions for running ralph.
+
+16. Determine the entry point:
+    - **Single epic**: the epic ID is the handoff bead.
+    - **Multiple independent epics**: create a parent meta-epic that groups them:
+      ```bash
+      bd create "<Feature Title> — Implementation" --type epic \
+        --description "Meta-epic grouping all phases for execution. See child epics for detail." \
+        --priority <same>
+      bd dep add <epic-1> <meta-epic> --type parent-child
+      bd dep add <epic-2> <meta-epic> --type parent-child
+      ```
+      The meta-epic ID is the handoff bead.
+    - **Sequentially dependent epics**: the first unblocked epic is the handoff bead — ralph will discover the rest via `bd ready` as dependencies clear.
+
+17. Tag the handoff bead for ralph's discovery:
+    ```bash
+    bd tag <handoff-id> workflow:ralph
+    ```
+
+18. Push the bead state:
+    ```bash
+    bd dolt push
+    ```
+
+19. Present the handoff summary:
+    ```
+    ✅ Plan complete. Ready for ralph.
+
+    Handoff bead: #<handoff-id>
+
+    To execute, tell an agent:
+
+        Use the ralph skill. Start from bead #<handoff-id>.
+
+    Full bead tree:
+
+    | Bead ID | Title | Type | Classification |
+    |---------|-------|------|---------------|
+    | #epic   | Phase 1 | epic | AFK |
+    | #task   | Task 1 | task | AFK (4 chore beads + PR gate) |
+    | #task   | Task 2 | task | HITL |
+    | ...     | ...    | ...  | ... |
+    ```
+
+#### Phase 4 gate
+
+- [ ] Handoff bead identified and tagged `workflow:ralph`
+- [ ] Bead state pushed with `bd dolt push`
+- [ ] Handoff summary presented with the exact instruction to give an agent
+
+## Phase-gate checklist
+
+- [ ] Phase 1: PRD drafted and approved, epic bead created
+- [ ] Phase 2: Task breakdown approved, epics created (if needed)
+- [ ] Phase 3: All tasks created, classified, expanded, tree presented
+- [ ] Phase 4: Handoff bead prepared, state pushed, summary delivered
+
+## Red Flags
+
+- **Skipping the codebase investigation.** Surface-level understanding produces PRDs that miss integration constraints, existing patterns, or prior art. Always explore before designing.
+- **Skipping the user interview.** The agent has incomplete context. The interview resolves ambiguities that would otherwise surface mid-execution as rework.
+- **Creating horizontal slices.** "All the DB work first, then all the API work" is not tracer bullets. Every task must deliver end-to-end value.
+- **Moving past Phase 2 without user approval.** The task breakdown shapes the entire execution. Do not create beads until the breakdown is approved.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "I know what needs to be built, I don't need a PRD" | A written PRD is the shared contract between the user, the planner, and the executor. It catches unstated assumptions. |
+| "I'll refine the tasks as I go" | The plan phase is the right time to refine. Mid-execution task changes cause rework in the bead dependency graph and confuse ralph's stage tracking. |
+| "This is a small change, I can just hand it straight to ralph" | For genuinely small changes — a single well-understood task — use `create-task` directly and skip this skill. This skill is for work that needs scoping. |
+| "I already know the phases, skip the quiz" | The quiz is where edge cases surface. Present the proposed breakdown for quick confirmation rather than skipping. |
+
+## Philosophy / rationale
+
+- **Tracer-bullet vertical slices** mean each completed task is independently demoable and verifiable. This avoids the "everything works but nothing is finished" trap.
+- **The bead graph is the plan.** By storing scope, dependencies, and classification in beads, there is no separate document to drift. The handoff is just a bead ID.
+- **Planning and execution are separate concerns.** The plan skill works with the user to get the right scope and structure. Ralph then executes autonomously within that structure. Separating them means the user reviews once, not piecemeal.
+- **AFK by default.** Classify tasks as AFK unless a human is genuinely required. Agent capability grows over time — tasks that feel HITL today may be AFK tomorrow.
+
+## Cross-skill references
+
+- `write-a-prd` — PRD template and interview workflow for Phase 1 (this skill incorporates the approach inline rather than delegating, to maintain a single coherent conversation).
+- `prd-to-tasks` — For the task breakdown step in Phase 2. If the PRD is already written and only decomposition is needed, use that skill directly.
+- `create-task` — Invoked in Phase 3 for each task. Handles bead creation, classification via `classify-bead`, and pipeline expansion for AFK tasks.
+- `classify-bead` — Invoked internally by `create-task`; not invoked directly by this skill.
+- `ralph` — The downstream skill that consumes the handoff bead. Run a separate agent with "Use the ralph skill. Start from bead #<handoff-id>."
+- `record-idea` — Use this instead if the idea is not ready for implementation planning.
+- `style-comms` — Invoke during Phase 1 if the user stories or implementation decisions need clearer writing.
+- `style-documentation` — Invoke during Phase 1 to align PRD documentation conventions with project standards.
+
+## Examples
+
+**Input:** "Plan this for me — I want to add a webhook notification system so external services can subscribe to order events."
+
+**Output after Phase 4:**
+```
+✅ Plan complete. Ready for ralph.
+
+Handoff bead: #epic-abc123
+
+To execute, tell an agent:
+
+    Use the ralph skill. Start from bead #epic-abc123.
+
+Full bead tree:
+
+| Bead ID | Title | Type | Classification |
+|---------|-------|------|---------------|
+| #epic-abc123  | Webhook Notification System — PRD | epic | AFK |
+| #task-456 | Create webhook subscription schema + API | task | AFK (4 chore beads + PR gate) |
+| #task-789 | Implement event dispatch and retry logic | task | AFK (4 chore beads + PR gate) |
+| #task-012 | Build subscriber management UI | task | HITL (visual review) |
+```
+
+## Verification checklist
+
+- [ ] Codebase was explored before drafting the PRD
+- [ ] User interview completed — each design branch resolved before moving to the next
+- [ ] PRD written with user stories and implementation decisions
+- [ ] PRD approved by the user before bead creation
+- [ ] Epic bead created from the approved PRD body
+- [ ] Task breakdown uses vertical slices (each task covers all layers — schema, API, logic, UI if applicable, tests)
+- [ ] Task breakdown approved by the user before moving to Phase 3
+- [ ] All tasks created via `create-task` (which handles classification, pipeline expansion, and PR gate creation)
+- [ ] Parent epics tagged with aggregate `implementation-type` (AFK if all children AFK, HITL if any child is HITL)
+- [ ] Full bead tree presented to the user before handoff
+- [ ] Handoff bead tagged `workflow:ralph`
+- [ ] Bead state pushed with `bd dolt push`
+- [ ] Handoff summary includes the exact instruction to give an agent