@jaybeeuu/agent-cortex 1.20.0

package/skills/planning/create-task/templates/fix.md

@@ -0,0 +1,27 @@
+## Project context
+<bd prime output — verbatim>
+
+## Task
+<bd show <id> output — verbatim>
+
+## Files to update
+<FILES_CHANGED from the previous coder/fixer's REPORT>
+
+## Progress log
+Write progress to: `.agent-cortex/ralph/ralph-<bead-id>.log`
+Log stage start, test results, build errors, and stage complete (see Progress Logging in run-pipeline-stage skill).
+
+## Instructions
+Invoke the `style-code` skill before making any code changes.
+
+Apply only the changes described in the Task section above. Do not make any other modifications.
+
+**Use context7** when working with any third-party library — fetch live docs to ensure you use the correct, up-to-date API for the version in this project.
+
+End your response with a ---REPORT--- block:
+---REPORT---
+BEAD_ID: <id>
+STAGE_COMPLETED: fixing
+SUMMARY: <2–3 sentence summary of what was changed>
+FILES_CHANGED: <comma-separated list, or "none">
+---

package/skills/planning/create-task/templates/review.md

@@ -0,0 +1,36 @@
+## Project context
+<bd prime output — verbatim>
+
+## Task
+<bead description — verbatim>
+
+## What was implemented
+<SUMMARY from the coder/fixer's REPORT block>
+
+## Files changed
+<FILES_CHANGED from the coder/fixer's REPORT block>
+
+## Progress log
+Write progress to: `.agent-cortex/ralph/ralph-<bead-id>.log`
+Log stage start, security scan result, review outcome, and stage complete (see Progress Logging in run-pipeline-stage skill).
+
+## Instructions
+**First**, invoke the `review-security` skill and run the scan against the changes. If the
+verdict is FAIL, set `REVIEW_OUTCOME: CHANGES_REQUESTED` immediately and list each finding
+as a required change — do not proceed with the quality review.
+
+**Then**, review the implementation for correctness, quality, and alignment with the task
+description and project conventions. Only flag genuine correctness issues or clear deviations
+from stated requirements — not stylistic preferences.
+
+End your response with a ---REPORT--- block:
+---REPORT---
+BEAD_ID: <id>
+STAGE_COMPLETED: reviewing
+SUMMARY: <2–3 sentence summary of what you reviewed>
+FILES_CHANGED: none
+REVIEW_OUTCOME: <APPROVED|CHANGES_REQUESTED>
+CHANGES_REQUESTED:       ← include only if REVIEW_OUTCOME is CHANGES_REQUESTED
+1. <required change>
+2. <required change>
+---

package/skills/planning/create-task/templates/verify.md

@@ -0,0 +1,43 @@
+## Project context
+<bd prime output — verbatim>
+
+## Task
+<bead description — verbatim>
+
+## What was implemented
+<SUMMARY from the coder/fixer's REPORT block>
+
+## Files changed
+<FILES_CHANGED from the coder/fixer's REPORT block>
+
+## Progress log
+Write progress to: `.agent-cortex/ralph/ralph-<bead-id>.log`
+Log stage start, each command run, test/lint result, and stage complete (see Progress Logging in run-pipeline-stage skill).
+
+## Instructions
+Discover and run the project's test and lint commands, then report the outcome.
+
+**Step 1 — Discover commands** (check in this order, stop at the first match):
+1. `package.json` `scripts` — look for keys named `test`, `lint`, `check`, `typecheck`, or similar.
+2. `Makefile` — look for targets named `test`, `lint`, `check`.
+3. Other well-known config files (e.g. `pyproject.toml`, `Cargo.toml`) — look for test/lint targets.
+4. If no commands are found, report PASS with summary "No test or lint commands found".
+
+**Step 2 — Run each discovered command** in the project root. Capture stdout and stderr.
+
+**Step 3 — Evaluate**:
+- If all commands exit 0: `VERIFY_OUTCOME: PASS`.
+- If any command exits non-zero: `VERIFY_OUTCOME: FAIL`. List each failure concisely.
+
+Do not fix failures — report them only.
+
+End your response with a ---REPORT--- block:
+---REPORT---
+BEAD_ID: <id>
+STAGE_COMPLETED: verifying
+SUMMARY: <what commands were run and overall outcome>
+FILES_CHANGED: none
+VERIFY_OUTCOME: <PASS|FAIL>
+VERIFY_FAILURES:          ← only if VERIFY_OUTCOME is FAIL
+- <test/lint failure summary>
+---

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

@@ -0,0 +1,227 @@
+---
+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.
+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.
+
+## 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".
+
+## 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`.
+
+## 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
+  ralph-plan reviews once at the end, not piecemeal through intermediaries.
+
+## Workflow
+
+### 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.
+
+### 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.
+
+### Phase 3 — Create epics (one per phase)
+
+9. Create epics in dependency order (blockers first) so you can reference real bead IDs.
+
+   ```bash
+   bd create "<Phase Title>" --type epic \
+     --description "<epic body from template below>"
+   ```
+
+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
+    ```
+
+### 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
+      ```
+
+### 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"
+```
+
+## 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.
+
+## 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. |
+
+## 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
+  descriptions.
+
+## Phase-gate checklist
+
+- [ ] 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.
+
+## 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).

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

@@ -0,0 +1,62 @@
+---
+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.
+---
+
+# Record Idea
+
+Capture a not-ready idea into `docs/ideas` after a short, high-level interview that pressure-tests the concept.
+
+## 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.

package/skills/planning/record-idea/scripts/new-idea.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  echo "Usage: $0 --title <idea title> [--complex]"
+  exit 1
+}
+
+title=""
+complex="false"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --title)
+      shift
+      [[ $# -gt 0 ]] || usage
+      title="$1"
+      ;;
+    --complex)
+      complex="true"
+      ;;
+    *)
+      usage
+      ;;
+  esac
+  shift
+done
+
+[[ -n "$title" ]] || usage
+
+slug="$(printf '%s' "$title" \
+  | tr '[:upper:]' '[:lower:]' \
+  | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')"
+
+if [[ -z "$slug" ]]; then
+  echo "Error: title produced an empty slug after normalization." >&2
+  exit 1
+fi
+
+base_dir="docs/ideas"
+if [[ "$complex" == "true" ]]; then
+  file_path="${base_dir}/${slug}/${slug}.md"
+else
+  file_path="${base_dir}/${slug}.md"
+fi
+
+mkdir -p "$(dirname "$file_path")"
+
+if [[ -e "$file_path" ]]; then
+  echo "Error: file already exists: $file_path" >&2
+  exit 1
+fi
+
+created_on="$(date -u +%Y-%m-%d)"
+
+cat > "$file_path" <<EOF
+# Idea: ${title}
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+${created_on}
+
+## Problem
+TODO
+
+## Who benefits
+TODO
+
+## Proposed outcome
+TODO
+
+## Validity check
+- Evidence we already have: TODO
+- Riskiest assumption: TODO
+- What would invalidate this idea: TODO
+
+## Constraints
+TODO
+
+## Next validation step
+TODO
+
+## Notes
+TODO
+EOF
+
+printf '%s\n' "$file_path"

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

@@ -0,0 +1,73 @@
+---
+name: request-refactor-plan
+description: Create a detailed refactor plan with tiny commits via user interview, then file it as a bead. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
+---
+
+This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.
+
+1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
+
+2. Explore the repo to verify their assertions and understand the current state of the codebase.
+
+3. Ask whether they have considered other options, and present other options to them.
+
+4. Interview the user about the implementation. Be extremely detailed and thorough.
+
+5. Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change.
+
+6. Look in the codebase to check for test coverage of this area of the codebase. If there is insufficient test coverage, ask the user what their plans for testing are.
+
+7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice to "make each refactoring step as small as possible, so that you can always see the program working."
+
+8. Create a bead with the refactor plan. Invoke the `create-task` skill, passing:
+   - **title**: a concise name for the refactor
+   - **description**: the refactor plan formatted using the template below
+   - **priority**: P2
+
+   **Always use `create-task`** — never call `bd create` directly for tasks. `create-task` classifies the bead and expands AFK tasks into pipeline stage children that ralph can execute.
+
+<refactor-plan-template>
+
+## 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. Write the plan in plain English, breaking down the implementation 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.
+
+</refactor-plan-template>

package/skills/planning/write-a-prd/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: write-a-prd
+description: Create a PRD through user interview, codebase exploration, and module design, then file as a bead. Use when user wants to write a PRD, create a product requirements document, or plan a new feature.
+---
+
+This skill will be invoked when the user wants to create a PRD. You may skip steps if you don't consider them necessary.
+
+1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
+
+2. Explore the repo to verify their assertions and understand the current state of the codebase.
+
+3. Interview the user relentlessly about every aspect of this plan until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.
+
+4. Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation.
+
+A deep module (as opposed to a shallow module) is one which encapsulates a lot of functionality in a simple, testable interface which rarely changes.
+
+Check with the user that these modules match their expectations. Check with the user which modules they want tests written for.
+
+5. Once you have a complete understanding of the problem and solution, use the template below to write the PRD. Create a bead for it using `bd create` with type `epic` and priority P1, passing the rendered PRD template as the description.
+
+<prd-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+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 PRD.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</prd-template>