@jaybeeuu/agent-cortex 1.38.1 → 1.39.0

package/skills/planning/prd-to-tasks/SKILL.md

@@ -1,40 +1,35 @@
 ---
 name: prd-to-tasks
-description: Break a PRD into phased epics and task beads using tracer-bullet vertical slices. Use when a PRD is approved and you need to create the executable backlog, or when ralph-plan encounters a large workstream.
+description: Break a PRD into phased epics and task beads using tracer-bullet vertical slices. Use when a PRD is approved and you need to create the executable backlog, when the user says "break this into tasks", "phase this PRD", or "create epics from this spec", or when ralph-plan encounters a large workstream.
 argument-hint: "Break down <PRD or epic description> into epics and tasks"
 ---
 
 # PRD to Tasks
 
-Take a PRD (or equivalent specification) and produce a complete set of epics and task beads,
-ready for ralph to execute. The epic bead is the source of truth — no intermediate plan file.
-
-Designed to be invoked by `ralph-plan` (when the input is a PRD or a large workstream) or
-directly by a user who has a clear spec.
+Take an approved PRD and produce a complete set of epics and task beads, ready for ralph to
+execute. The epic bead is the source of truth — no intermediate plan file.
 
 ## When to use
 
 - A PRD has been written and approved — time to break it into executable chunks.
-- `ralph-plan` receives a PRD as input (step 1) or encounters a large workstream (step 6).
-- You have a well-understood feature and want to create the full bead tree in one pass.
-- The user says "break this into tasks", "phase this PRD", "create epics from this spec".
+- `ralph-plan` receives a PRD as input or encounters a large workstream.
+- You have a well-understood feature and want the full bead tree created in one pass.
+- The user says "break this into tasks", "phase this PRD", or "create epics from this spec".
 
 ## When NOT to use
 
-- The work is a single self-contained task — use `create-task` instead.
-- The feature is not yet specified — use `write-a-prd` or the `strategy` agent first.
-- You only need to record a raw idea — use `record-idea`.
-- The task is a bug fix — file directly with `create-task`.
+- A single self-contained task — use `create-task` instead.
+- A feature that is not yet specified — use `write-a-prd` or the `strategy` agent first.
+- A raw idea that needs capturing — use `record-idea`.
+- A bug fix — file it directly with `create-task`.
 
 ## Philosophy / rationale
 
-- **Epics are the source of truth.** The epic bead body contains the phase scope,
-  acceptance criteria, and dependencies. No intermediate plan file means no drift between
-  what was planned and what is tracked.
-- **Tracer-bullet vertical slices.** Each task is a thin end-to-end path through all layers
-  (schema, API, logic, UI, tests). A completed task is demoable alone. Prefer many thin
-  slices over few thick ones.
-- **One pass, complete output.** This skill produces the entire bead tree. The user or
+- **Epics are the source of truth.** Each epic bead body carries the phase scope, acceptance
+  criteria, and dependencies; no plan file means no drift between planned and tracked.
+- **Tracer-bullet vertical slices.** Each task is a thin end-to-end path through every layer
+  (schema, API, logic, UI, tests), demoable alone. Prefer many thin slices over few thick ones.
+- **One pass, complete output.** Produce the whole bead tree in one pass; the user or
   ralph-plan reviews once at the end, not piecemeal through intermediaries.
 
 ## Workflow
@@ -42,186 +37,107 @@ directly by a user who has a clear spec.
 ### Phase 1 — Understand the PRD
 
 1. Confirm the PRD is in context (conversation, bead description, or file).
-2. If you haven't explored the relevant codebase area, do so now — understand current
-   architecture, existing patterns, and integration layers.
-3. Identify durable architectural decisions that will apply across all phases.
-   Examples:
-   - Route structures / URL patterns
-   - Database schema shape
-   - Key data models
-   - Authentication / authorisation approach
-   - Third-party service boundaries
-   Add others relevant to the project — the goal is a shared skeleton every phase
-   can reference.
-4. Record these in a holding note — they inform every phase.
+2. Explore the relevant codebase area if you have not already — current architecture and
+   integration layers.
+3. Record the durable architectural decisions that apply across all phases, as examples
+   not an exhaustive list: route structures or URL patterns, database schema shape, key
+   data models, auth approach, third-party service boundaries. This shared skeleton informs
+   every phase.
 
 ### Phase 2 — Draft the phase breakdown
 
-5. Break the PRD into phases. Each phase is a **tracer-bullet vertical slice**:
-   - Thin but complete path through ALL integration layers.
-   - Demoable or verifiable on its own.
-   - Covers a specific set of user stories from the PRD.
-
-6. 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 (not layer-by-layer).
-   - **Acceptance criteria**: verifiable outcomes.
-
-7. Present the proposed phases 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?
-
-8. Iterate until the user approves the breakdown.
+4. Break the PRD into phases. Each phase is a **tracer-bullet vertical slice**: thin but
+   complete through all integration layers, demoable or verifiable on its own, and
+   covering a specific set of user stories.
+5. For each phase define its **title**, **user stories covered**, **what to build**
+   (end-to-end behaviour, not layer-by-layer), and **acceptance criteria**.
+6. Present the proposed phases and ask about granularity, merges or splits, and which
+   phases can run in parallel. Iterate until the user approves.
 
 ### Phase 3 — Create epics (one per phase)
 
-9. Create epics in dependency order (blockers first) so you can reference real bead IDs.
+7. Create epics in dependency order (blockers first) so you can reference real bead IDs,
+   using the epic body template in [REFERENCE.md](./REFERENCE.md):
 
    ```bash
-   bd create "<Phase Title>" --type epic \
-     --description "<epic body from template below>"
+   bd create "<Phase Title>" --type epic --description "<epic body from REFERENCE.md>"
    ```
 
-10. Tag each epic with a priority:
-    ```bash
-    bd tag <epic-id> priority:p3   # default for feature work; adjust if P4/P5
-    ```
-    If running in the context of ralph-plan or ralph, also tag with:
-    ```bash
-    bd tag <epic-id> workflow:ralph
-    ```
+8. Tag each epic with a priority (`p3` default; adjust for p4/p5), and `workflow:ralph`
+   when running under ralph-plan or ralph.
 
 ### Phase 4 — Create tasks within each epic
 
-11. For each epic, break it into task-sized vertical slices. Each task is independently
-    grabbable — a single agent (or person) can pick it up and complete it.
-
-12. For each task, invoke `create-task`:
-    ```bash
-    # create-task handles classification (AFK/HITL) and pipeline expansion
-    # Pass title, description (use template below), priority (inherit from epic or adjust),
-    # and parent epic ID
-    ```
-
-13. After all tasks are created, tag the parent epic with the aggregate classification:
-    - If **any** task is HITL, the epic is HITL:
-      ```bash
-      bd tag <epic-id> implementation-type:hitl
-      ```
-    - If **all** tasks are AFK:
-      ```bash
-      bd tag <epic-id> implementation-type:afk
-      ```
+9. Break each epic into task-sized vertical slices that are independently grabbable, then
+   invoke `create-task` for each — it handles AFK/HITL classification and pipeline
+   expansion. Pass the task body template from REFERENCE.md, the priority, and the parent
+   epic ID.
+10. Once all tasks exist, tag the epic with the aggregate classification: HITL if any task
+    is HITL, otherwise AFK.
 
 ### Phase 5 — Report
 
-14. Present the full bead tree:
-    ```
-    Epic: "Phase 1 Title" (#123)
-      ├── Task 1 (#124) — AFK
-      ├── Task 2 (#125) — HITL (visual review)
-      └── Task 3 (#126) — AFK
-    Epic: "Phase 2 Title" (#127)
-      ├── ...
-    ```
-
-15. If invoked by `ralph-plan`, signal completion so ralph-plan can proceed to the
-    agree-with-user step. If invoked directly by a user, summarise the bead tree and
-    confirm they're happy before finishing.
-
-## Epic body template
-
-```markdown
-## Source
-
-PRD: <brief reference>
-
-## Summary
-
-A concise description of this phase. Scope and goal, not implementation details.
-
-## What to build
-
-End-to-end behaviour for this phase. What a demo would show.
-
-## Acceptance criteria
-
-- [ ] Criterion 1
-- [ ] Criterion 2
-
-## Blocked by
-
-- Blocked by #<epic-id> (if any) — or "None — can start immediately"
-```
-
-## Task body template (passed to `create-task`)
-
-```markdown
-## Epic
-
-#<epic-id> — <Epic Title>
-
-## What to build
-
-This vertical slice: end-to-end behaviour, not layer-by-layer implementation.
-
-## Acceptance criteria
-
-- [ ] Criterion 1
-- [ ] Criterion 2
-
-## Blocked by
-
-- Blocked by #<task-id> (if any) — or "None — can start immediately"
-```
+11. Present the full bead tree: each epic with its tasks, classifications, and IDs.
+12. If invoked by `ralph-plan`, signal completion so it can proceed; if invoked directly,
+    summarise the tree and confirm the user is happy before finishing.
 
 ## Red Flags
 
-- **Skipping the user quiz.** The phase breakdown needs human approval before creating
-  beads. Do not skip Phase 2 step 7-8.
-- **Creating horizontal slices.** "All the database work first, then all the API work" is
-  not tracer bullets. Every task must deliver end-to-end value.
-- **Fat tasks.** If a task would take a full agent session to implement, slice thinner.
-  A task should be a few RED-GREEN cycles, not a week of work.
-- **Letting the plan file drift.** Epics are the SOT. Do not also write a plan file —
-  the epic bead body is the plan.
+- **Skipping the phase approval step.** The breakdown needs human sign-off (Phase 2 step 6)
+  before any bead is created.
+- **Creating horizontal slices.** "All the database work, then all the API work" is not a
+  tracer bullet — every task must deliver end-to-end value.
+- **Fat tasks.** If a task would take a full agent session, slice thinner. A task is a few
+  RED-GREEN cycles, not a week of work.
+- **Letting a plan file drift in.** The epic bead is the plan — a separate file creates
+  drift and is ignored by ralph.
 
 ## Common Rationalizations
 
 | Rationalization | Rebuttal |
 |---|---|
-| "I'll create the epics now and the tasks later" | The user has approved the phases. Create everything in one pass — that's the point of this skill. |
-| "I'll write a plan file first, then convert" | The epic bead IS the plan. Writing a separate file creates drift. |
-| "This phase is too small for acceptance criteria" | If it's too small for criteria, merge it with another phase. Every deliverable needs a definition of done. |
-| "I know what the tasks should be, I don't need to check with the user" | The phase breakdown needs approval. The epic-level approval implies task-level trust, but you still present the full tree in Phase 5. |
+| "I'll create the epics now and the tasks later" | Phases are already approved — create everything in one pass. |
+| "I'll write a plan file first, then convert" | The epic bead IS the plan. A separate file creates drift. |
+| "This phase is too small for acceptance criteria" | If it is too small for criteria, merge it with another phase. Every deliverable needs a definition of done. |
+| "I know the tasks — no need to check with the user" | The phase breakdown still needs approval, and the full tree is presented in Phase 5. |
 
 ## Cross-skill references
 
-- **`create-task`** — invoked in Phase 4 for each task bead. Handles classification and
-  pipeline expansion.
-- **`write-a-prd`** — use this first if the feature isn't specified yet.
-- **`classify-bead`** — not needed; `create-task` handles classification internally.
-- **`style-comms`** — invoke before Phase 2 if you need help writing clear phase
+- **`create-task`** — invoked for every task bead; handles classification and pipeline
+  expansion.
+- **`write-a-prd`** — use first when the feature is not yet specified.
+- **`style-comms`** — invoke before Phase 2 when you need help writing clear phase
   descriptions.
 
-## Phase-gate checklist
+## Examples
+
+Input: an approved PRD with a numbered list of user stories.
+Output: a dependency-ordered tree of epic and task beads:
+
+```
+Epic: "Phase 1 — Auth" (#123) — HITL
+  ├── Task 1 (#124) — AFK
+  ├── Task 2 (#125) — HITL (visual review)
+  └── Task 3 (#126) — AFK
+Epic: "Phase 2 — Dashboard" (#127) — AFK (blocked by #123)
+```
+
+## Phase-gate checklists
 
-- [ ] Phase 1 (Understand): architectural decisions captured, codebase explored.
-- [ ] Phase 2 (Breakdown): phases drafted and user-approved.
-- [ ] Phase 3 (Epics): all epic beads created, tagged with `workflow:ralph` and
-      `priority:<p3|p4|p5>`.
-- [ ] Phase 4 (Tasks): all task beads created via `create-task`, epic tagged with
-      aggregate `implementation-type`.
-- [ ] Phase 5 (Report): full bead tree presented.
+- [ ] Phase 1 complete: PRD confirmed, codebase explored, architectural decisions captured.
+- [ ] Phase 2 complete: phases drafted and approved by the user.
+- [ ] Phase 3 complete: epics created in dependency order and tagged (priority, plus
+      `workflow:ralph` under ralph-plan/ralph).
+- [ ] Phase 4 complete: tasks created via `create-task`; epics carry the aggregate
+      `implementation-type` tag.
+- [ ] Phase 5 complete: full bead tree presented and confirmed.
 
 ## Verification checklist
 
-- [ ] Every phase is a vertical slice (covers all layers), not a horizontal layer.
-- [ ] Every task is independently grabbable (one agent can complete without others).
-- [ ] All epics are tagged with `workflow:ralph` and a priority.
-- [ ] All tasks are classified (AFK/HITL) via `create-task`.
-- [ ] Parent epics have aggregate `implementation-type` tags.
-- [ ] No intermediate plan file was created — epics are the SOT.
-- [ ] Full bead tree was presented to the user (or to ralph-plan for step 7).
+- [ ] Every phase is a vertical slice covering all layers, not a horizontal layer.
+- [ ] Every task is independently grabbable by a single agent.
+- [ ] All epics are tagged with a priority (and `workflow:ralph` when under ralph).
+- [ ] All tasks are classified AFK/HITL via `create-task`.
+- [ ] Parent epics carry the aggregate `implementation-type` tag.
+- [ ] No intermediate plan file was created — epics are the source of truth.
+- [ ] The full bead tree was presented to the user, or to ralph-plan for its next step.

package/skills/planning/record-idea/FORMAT.md

@@ -0,0 +1,44 @@
+# Idea Record Format
+
+`scripts/new-idea.sh` generates this scaffold into `docs/ideas/<slug>.md` (or `docs/ideas/<slug>/<slug>.md` with `--complex`). Fill every section — a record with unfilled sections has not been captured.
+
+## Scaffold
+
+```md
+# Idea: <title>
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+<YYYY-MM-DD>
+
+## Problem
+<What problem does this idea address?>
+
+## Who benefits
+<Who benefits and what improves for them?>
+
+## Proposed outcome
+<What the idea would deliver, at a capability level — not implementation detail>
+
+## Validity check
+- Evidence we already have: <what supports this idea>
+- Riskiest assumption: <the assumption most likely to be wrong>
+- What would invalidate this idea: <the signal that kills it>
+
+## Constraints
+<Hard limits: tech, process, scope, resourcing>
+
+## Next validation step
+<The cheapest next thing that would firm up or kill the idea>
+
+## Notes
+<Anything worth keeping for future prioritisation or review>
+```
+
+## Guidance per section
+
+- Keep the record decision-oriented and scannable — it will be read during future prioritisation.
+- `Validity check` is mandatory: evidence grounds the idea, the riskiest assumption marks where it is weakest, and the invalidation signal tells you when to drop it.
+- `Next validation step` should be concrete enough to act on without re-deriving the context.

package/skills/planning/record-idea/SKILL.md

@@ -1,62 +1,79 @@
 ---
 name: record-idea
-description: Capture early-stage ideas into a structured backlog record, including a high-level validity check before implementation planning. Use when the user shares a new idea that is not ready to build yet and wants it written to the ideas backlog.
+description: Capture an early-stage idea into a structured backlog record with a short interview and validity check before any implementation planning. Use when the user says "capture this idea", "file this under ideas", or shares an idea that is "not ready to build".
 ---
 
 # Record Idea
 
-Capture a not-ready idea into `docs/ideas` after a short, high-level interview that pressure-tests the concept.
+Capture an idea that is not implementation-ready into `docs/ideas/`, pressure-testing it with a short high-level interview so the backlog stores a direction, not a slogan.
+
+## When to use
+
+- The user shares a new idea and wants it written down without scoping it yet ("capture this idea", "file this under ideas", "get this out of my head").
+- A discussion surfaces an idea that should not be planned today.
+- Asked to "add this to the ideas backlog" or "record an idea".
+
+## When NOT to use
+
+- The idea is ready to build and needs a requirements document — run `write-a-prd` instead.
+- The user wants an executable task created now — run `create-task` instead.
+- The idea needs an end-to-end feature plan — run `plan` instead.
 
 ## Workflow
 
-1. **Interview at high level (one question at a time)**
-   - Why might it be useful? Who benefits and what improves?
-   - How might we do it? Sketch the rough approach — no implementation detail.
-   - When should we think about it? Are there triggers, dependencies, or timing signals?
-   - What priority does this feel like relative to current work?
-2. **Pressure-test briefly**
-   - Challenge weak points (scope, feasibility, opportunity cost).
-   - Keep discussion strategic; do not drift into implementation detail.
-3. **Choose record shape**
-   - **Simple idea**: `docs/ideas/<idea-name>.md`
-   - **Complex idea**: `docs/ideas/<idea-name>/<idea-name>.md` with optional supporting docs in the same folder.
-4. **Create the record file**
-   - Run:
-     ```bash
-     bash skills/record-idea/scripts/new-idea.sh --title "<idea title>" [--complex]
-     ```
-5. **Write the idea record**
-   - Fill the scaffold with concise content from the interview.
-   - Keep it decision-oriented and easy to scan later.
-
-## Idea Record Template
-
-```md
-# Idea: <title>
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Why it might be useful
-<Who benefits and what improves?>
-
-## How we might do it
-<Rough approach — no implementation detail>
-
-## When to think about it
-<Triggers, dependencies, or timing signals that would make this timely>
-
-## Priority
-<Relative priority and reasoning>
-
-## Notes
-<Anything worth keeping for future prioritisation/review>
-```
-
-## Output
-
-Return:
-
-1. The file path created.
-2. A 2–3 sentence summary of the recorded idea.
-3. The suggested priority and when it might become timely.
+1. **Interview at a high level, one question at a time.** Ask what problem it solves and who benefits, how it might be done (rough approach only — no implementation detail), what would make it timely (triggers, dependencies, timing signals), and what priority it feels like relative to current work. Keep this short — it is a capture step, not a requirements session.
+
+2. **Pressure-test briefly.** Challenge weak points such as scope, feasibility, and opportunity cost. The goal is a validity signal for the backlog, not a polished pitch.
+
+3. **Choose the record shape.**
+   - Simple idea: a single file `docs/ideas/<idea-name>.md`.
+   - Complex idea: a folder `docs/ideas/<idea-name>/<idea-name>.md` with supporting docs alongside.
+
+4. **Create the record file.** Run this skill's `scripts/new-idea.sh` helper with {{TOOL:bash}}:
+
+   ```bash
+   bash <skill-scripts>/new-idea.sh --title "<idea title>" [--complex]
+   ```
+
+   Resolve `<skill-scripts>` as the absolute path to this skill's own `scripts/` directory — it sits next to this `SKILL.md`, and the install location varies by harness, so do not hardcode a repo path. The script generates the scaffold, prints the file path, and errors if the file already exists or the title normalises to an empty slug.
+
+5. **Fill the scaffold.** Write concise, decision-oriented content from the interview into every section — see `FORMAT.md` for the section list. Leave no `TODO`: the validity check specifically needs evidence, the riskiest assumption, and what would invalidate the idea.
+
+6. **Report back.** Return the file path, a 2–3 sentence summary of the recorded idea, and the suggested priority with its likely timing signal.
+
+## Red Flags
+
+- Drifting into implementation detail during the interview — the record captures a direction, not a design.
+- Skipping the pressure-test because the idea sounds good — weak points are cheapest to find here.
+- Leaving scaffold `TODO`s unfilled — an incomplete validity check is no check at all.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "It's just an idea — write it down, don't interview me" | The two-minute interview is what makes the row reusable later; without it you store a slogan, not an idea. |
+| "The user already knows what they want" | Knowing the direction is not the same as pressure-testing it. The validity check exists to catch what enthusiasm hides. |
+
+## Philosophy / rationale
+
+- **Capture before it becomes plan-shaped.** Scoping too early forces decisions the idea has not earned yet; a backlog note keeps the option open at minimal cost. The validity check is what stops the backlog from filling with confident, doomed ideas.
+
+## Cross-skill references
+
+- When an idea passes its validity check and becomes implementation-ready, run `write-a-prd` to scope it properly.
+- For a full feature pipeline from idea to task breakdown, run `plan`.
+
+## Examples
+
+Input: "I keep accidentally committing secrets — capture that idea."
+Output: `docs/ideas/secret-scanning-gate.md` — a filled idea record with a validity check, priority, and next validation step. See `FORMAT.md` for the scaffold sections.
+
+## Verification checklist
+
+- [ ] Interview covered who benefits, rough approach, timing, and priority.
+- [ ] Idea was pressure-tested; weak points were challenged.
+- [ ] Record file exists at `docs/ideas/<slug>.md` (script printed the path).
+- [ ] Every scaffold section is filled — no `TODO` left in the record.
+- [ ] Validity check records evidence, the riskiest assumption, and what would invalidate the idea.
+- [ ] Record contains no implementation detail.
+- [ ] Report returned the file path, summary, and suggested priority.

package/skills/planning/request-refactor-plan/FORMAT.md

@@ -0,0 +1,45 @@
+# Refactor Plan Template
+
+Format the `description` passed to `create-task` using the template below. Write the plan in plain English. Keep the Decision Document at the level of decisions — do not include specific file paths or code snippets, which go stale quickly.
+
+## Problem Statement
+
+The problem that the developer is facing, from the developer's perspective.
+
+## Solution
+
+The solution to the problem, from the developer's perspective.
+
+## Commits
+
+A long, detailed implementation plan in plain English, broken into the tiniest commits possible. Each commit should leave the codebase in a working state.
+
+## Decision Document
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this refactor.
+
+## Further Notes (optional)
+
+Any further notes about the refactor.