@jaybeeuu/agent-cortex 1.38.1 → 1.40.0

package/skills/engineering/technical-direction/SKILL.md

@@ -1,86 +1,79 @@
 ---
 name: technical-direction
-description: Drive collaborative technical design by challenging assumptions, mapping constraints, comparing alternatives, and producing a justified recommendation. Use when user wants to decide technical direction after PRD, evaluate architecture/technology choices, or asks to design a solution with tradeoff analysis.
+description: Challenge assumptions, map constraints, compare options, and justify the choice. Use when deciding technical direction, choosing architecture or technology, or designing a solution with tradeoffs.
 ---
 
 # Technical Direction
 
-Act like a pragmatic, challenging staff engineer: constructive, direct, evidence-driven.
+Act as a pragmatic, challenging staff engineer: constructive, direct, and evidence-driven. The deliverable is a justified recommendation, not consensus.
+
+## When to use
+
+- "Decide technical direction" for a change with real architectural weight.
+- Evaluating architecture or technology choices that carry tradeoffs.
+- A PRD or brief is approved and the solution shape is still open.
+- "Design a solution" where alternatives need mapping and comparison before picking one.
+
+## When NOT to use
+
+- Stress-testing an existing plan or sharpening domain language — use `grill-with-docs`.
+- Scoping a feature into PRD and tasks — use `plan` before direction makes sense.
+- Exploring a codebase for refactoring opportunities — use `improve-codebase-architecture`.
+- Reversible decisions with no meaningful tradeoffs — a memo costs more than it saves.
 
 ## Workflow
 
-1. **Anchor on problem context**
-   - Start from PRD or user brief
-   - Confirm technical goals, non-goals, and decision horizon
-
-2. **Discover constraints from codebase first**
-   - Investigate architecture, existing interfaces, deployment/runtime constraints, data model boundaries, and team conventions
-   - Note unknowns and risks
-
-3. **Challenge loop (one question at a time)**
-   - Ask focused, high-leverage questions
-   - Challenge vague claims and hidden assumptions
-   - Require explicit justification for each major decision
-   - Keep drilling until constraints and tradeoffs are concrete
-
-4. **Generate options**
-   - Always include Option A (extend current approach), Option B (moderate architectural shift), and Option C (stronger alternative using new tech/pattern)
-   - For each option: feasibility, complexity, migration cost, operational impact, testability, performance, and failure modes
-
-5. **Use web research when needed**
-   - Do this autonomously when codebase evidence is insufficient or a high-impact decision needs external comparison
-   - Prefer authoritative sources (official docs, maintainers, widely adopted production guidance)
-   - Bring findings back as tradeoffs, and retain source links as references
-
-6. **Converge on a recommendation**
-   - Select the best-fit option for current constraints
-   - Explicitly explain why alternatives were not chosen
-   - List decision triggers that would justify revisiting later
-
-7. **Write decision memo**
-   - Ensure `docs/technical-direction/` exists
-   - Save to `docs/technical-direction/<feature-slug>.md` using this template:
-
-```md
-# Technical Direction: <Feature Name>
-## Problem and target outcome
-- What we are solving
-- Why this matters now
-## Current-state constraints
-- Architecture and integration constraints
-- Team/runtime/operational constraints
-- Unknowns and assumptions
-## Options considered
-### Option A: <name>
-- Approach
-- Pros
-- Cons
-- Risks
-### Option B: <name>
-...
-### Option C: <name>
-...
-## Recommendation
-- Chosen approach
-- Why this is best under current constraints
-- Why alternatives were not selected
-## Tradeoffs accepted
-- Explicit compromises and consequences
-## Validation plan
-- Fastest experiments/spikes to de-risk decision
-- Success/failure signals
-## Revisit triggers
-- Conditions that should force re-evaluation
-## References
-- Web sources used for decisions (title + URL)
-- Code evidence links (repo path + line range, and permalink URL when available)
-```
-
-## Rules
-
-- Ask questions one at a time.
-- If the answer exists in the codebase, investigate before asking.
-- Be challenging but collaborative; do not optimize for agreement.
-- Avoid premature implementation details until direction is selected.
-- Every recommendation must include explicit constraints and tradeoffs.
-- When web or code sources materially inform decisions, include them in `## References`.
+1. **Anchor on problem context.** Start from the PRD or user brief. Confirm goals, non-goals, and the decision horizon (how long this choice must hold).
+2. **Discover constraints from the codebase first.** Investigate architecture, existing interfaces, deployment and runtime constraints, data-model boundaries, and team conventions using {{TOOL:rg}}, {{TOOL:view}}, and {{TOOL:glob}}. Record unknowns and risks explicitly.
+3. **Run the challenge loop, one question at a time.** Ask focused, high-leverage questions. Challenge vague claims and hidden assumptions; require explicit justification for each major decision. Keep drilling until constraints and tradeoffs are concrete. If an answer exists in the codebase, find it before asking.
+4. **Generate options.** Always include Option A (extend the current approach), Option B (moderate architectural shift), and Option C (a stronger alternative using new tech or patterns). Evaluate each on feasibility, complexity, migration cost, operational impact, testability, performance, and failure modes.
+5. **Use web research when the codebase is insufficient.** Do this autonomously for high-impact decisions needing external comparison. Prefer authoritative sources (official docs, maintainers, widely adopted production guidance) via {{TOOL:web_fetch}}; bring findings back as tradeoffs with source links.
+6. **Converge on a recommendation.** Select the best-fit option under current constraints. Explain explicitly why each alternative was not chosen. List decision triggers that would justify revisiting.
+7. **Write the decision memo.** Ensure `docs/technical-direction/` exists and save `docs/technical-direction/<feature-slug>.md` using the template in [FORMAT.md](FORMAT.md).
+
+## Red Flags
+
+- Red flag: proposing options before constraints are mapped — alternatives become uncomparable.
+- Red flag: asking a question the codebase can answer without looking first.
+- Red flag: optimising for agreement instead of surfacing hard tradeoffs.
+- Red flag: recommending direction without stated tradeoffs, revisit triggers, or validation signals.
+- Red flag: sliding into premature implementation details before direction is selected.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "We already know the answer" | Stated answers often rest on unstated assumptions. Test the recommendation against the constraints before accepting it. |
+| "The tradeoffs are obvious" | Obvious today is forgotten in a month. The memo exists so reversible choices stay reversible and irreversible ones are signposted. |
+| "Web research is overkill" | For high-impact choices with insufficient codebase evidence, external comparison is the cheapest way to kill a plausible-but-wrong option. |
+| "One option is clearly right" | A single option is a statement, not a decision. Alternatives and their failure modes are what justify the choice. |
+
+## Philosophy / rationale
+
+- **Constraints first, options second.** Options only compare against the constraints that bound them, so map the codebase and decision horizon before generating alternatives.
+- **Challenge is the deliverable.** The value of a direction session is the assumptions it surfaces and kills. Optimising for agreement produces a recommendation nobody tested.
+- **Every recommendation carries its tradeoffs.** A choice without documented tradeoffs, revisit triggers, and validation signals cannot be revisited intelligently later.
+
+## Cross-skill references
+
+- `write-a-prd` produces the input brief when no PRD exists yet.
+- `grill-with-docs` sharpens contested terminology and stress-tests the memo against domain docs.
+- `design-an-interface` structures the option-generation step when the decision is about interface shape.
+- `style-documentation` governs the memo's what/whether criteria before writing.
+
+## Examples
+
+Input: "Decide on the write-path storage for the events service."
+Output: a decision memo at `docs/technical-direction/events-write-path.md` covering constraints, three options scored against them, a justified recommendation, tradeoffs accepted, a validation plan, revisit triggers, and references. See [FORMAT.md](FORMAT.md) for the full template.
+
+## Verification checklist
+
+- [ ] Goals, non-goals, and decision horizon confirmed before options were generated
+- [ ] Codebase constraints explored before asking questions; unknowns and risks recorded
+- [ ] Questions asked one at a time; nothing answerable from the codebase asked of the user
+- [ ] At least three options considered, including an extend-current approach and a stronger alternative
+- [ ] Each option scored on feasibility, complexity, migration cost, operational impact, testability, performance, and failure modes
+- [ ] Recommendation states why alternatives were not chosen and lists revisit triggers
+- [ ] Decision memo saved to `docs/technical-direction/<feature-slug>.md` using the FORMAT.md template
+- [ ] Tradeoffs accepted, validation plan, and references (web and code, with links) included
+- [ ] No premature implementation detail in the memo — direction only

package/skills/planning/classify-bead/SKILL.md

@@ -5,63 +5,87 @@ description: Classify a bead as AFK or HITL and apply the implementation-type la
 
 # Classify Bead
 
-Determine whether a bead requires human action (HITL) or can be completed autonomously by an agent (AFK), then persist the result as a label.
+Determine whether a bead requires human action (HITL) or can be completed autonomously by an agent (AFK), then persist the result as an `implementation-type` label.
 
 ## When to use
 
-- When picking up a bead that is missing the `implementation-type` label.
-- Immediately after creating a new bead, before claiming or scheduling it.
-- Any time you are unsure of a bead's classification.
+- A bead is missing its `implementation-type` label and you are about to pick it up.
+- A skill has just created a new bead and needs it classified before claiming or scheduling.
+- You are unsure of a bead's classification and want to resolve it deterministically.
+
+## When NOT to use
+
+- The bead already carries an `implementation-type` label — check `bd label list <id>` before invoking, and never re-classify a labelled bead.
+- You are creating a new task — `create-task` classifies internally; do not spawn this skill separately.
+- The work item is not a bead (e.g. a Jira ticket or plain code task) — use `write-a-ticket` or start the work directly.
 
 ## Invocation
 
-**Always run this skill as a subagent** (background `general-purpose` agent, `model: haiku`) to avoid loading bead content into the calling agent's context. Classification is a rubric lookup, not code generation, so the smaller/cheaper model is sufficient. Pass the bead ID and the `bd prime` output. The subagent runs the procedure below and reports back the classification and the `bd tag` command it applied.
+Run this skill as a background subagent via {{TOOL:task}} so bead content never loads into the calling agent's context. Classification is a rubric lookup, not code generation — a small, cheap model is sufficient. Pass the bead ID and the `bd prime` output; the subagent runs the workflow below and reports back the classification plus the `bd tag` command it applied.
+
+Only run inline when no task-spawning capability exists in the current environment.
+
+**Callers should check `bd label list <id>` themselves first.** If `implementation-type` is already present, skip spawning this skill entirely — spawning a subagent purely to re-read a label that already exists wastes a full agent call.
+
+## Workflow
+
+1. **Check for an existing label.**
 
-Only run inline (without a subagent) if no task-spawning capability is available in the current environment.
+   ```bash
+   bd label list <id>
+   ```
 
-**Callers should check `bd label list <id>` themselves first.** If `implementation-type` is already present, skip spawning this skill entirely — spawning a subagent purely to re-read a label that's already there wastes a full agent call.
+   - `implementation-type:afk` present → classification is **AFK**. Stop here.
+   - `implementation-type:hitl` present → classification is **HITL**. Stop here.
 
-## Procedure
+2. **Check the `## Type` field (back-compat).**
 
-### 1. Check for an existing label
+   ```bash
+   bd show <id>
+   ```
 
-```bash
-bd label list <id>
-```
+   Locate the `## Type` section in the bead body. `HITL` or `AFK` (case-insensitive) determines the classification; continue to step 4. This field predates the label system, so treat it as authoritative when present.
 
-- If `implementation-type:afk` is present → classification is **AFK**. Stop here.
-- If `implementation-type:hitl` is present → classification is **HITL**. Stop here.
+3. **Classify from first principles** — only when neither the label nor the `## Type` field is present. Read the full bead body and apply the rubric:
 
-### 2. Check the `## Type` field (back-compat)
+   **HITL** — the bead requires a human if at least one of the following is true:
+   - The outcome cannot be verified by an agent (e.g. visual review, stakeholder sign-off, UX judgement call).
+   - A manual action only a human can perform is required (e.g. credential setup, secrets management, external service configuration, infrastructure provisioning outside the codebase).
+   - A decision must be made that the agent cannot make unilaterally (e.g. architectural choice between equally valid options, regulatory or legal sign-off).
 
-```bash
-bd show <id>
-```
+   **AFK** — the agent can implement, verify, and complete the task autonomously, and all acceptance criteria are machine-checkable.
 
-Locate the `## Type` section in the bead body.
+4. **Apply the label.**
 
-- If the value is `HITL` (case-insensitive) → classification is **HITL**. Proceed to step 4.
-- If the value is `AFK` (case-insensitive) → classification is **AFK**. Proceed to step 4.
+   ```bash
+   bd tag <id> implementation-type:afk    # or implementation-type:hitl
+   ```
 
-### 3. Classify from first principles
+5. **Return the classification.** Report `AFK` or `HITL` so the calling skill or agent can act on it.
 
-If neither the label nor the `## Type` field is present, read the full bead body and apply this rubric:
+## Red Flags
 
-**HITL** — the bead requires a human if at least one of the following is true:
-- The outcome cannot be verified by an agent (e.g. visual review, stakeholder sign-off, UX judgement call).
-- The work requires a manual action only a human can perform (e.g. credential setup, secrets management, external service configuration, infrastructure provisioning outside the codebase).
-- A decision must be made that the agent cannot make unilaterally (e.g. architectural choice between equally valid options, regulatory or legal sign-off).
+- Classifying a bead without the caller-side `bd label list` check — you either overwrite a recorded decision or waste an agent spawn re-reading a label that already exists.
+- Defaulting to HITL for a complex task whose acceptance criteria are machine-checkable — complexity alone is not a criterion.
+- Choosing a class without reading the bead body when neither the label nor `## Type` is present.
 
-**AFK** — the agent can implement, verify, and complete the task autonomously, and all acceptance criteria are machine-checkable.
+## Common Rationalizations
 
-Prefer AFK. Do not classify as HITL just because the task is complex — only when the agent genuinely cannot complete or verify it without human involvement.
+| Rationalization | Rebuttal |
+|---|---|
+| "This task is complex, so it must be HITL" | Complexity is not a criterion. HITL applies only when a human is genuinely required to complete or verify. |
+| "I'll mark it HITL to be safe" | HITL consumes scarce human attention. Prefer AFK — ralph's review gates still catch agent mistakes. |
+| "The label is probably already there, I'll skip the check" | One `bd label list` command settles it. Skipping it either overwrites a decision or spawns an agent to re-read a label. |
 
-### 4. Apply the label
+## Philosophy / rationale
 
-```bash
-bd tag <id> implementation-type:afk    # or implementation-type:hitl
-```
+- Classification gates automation against human attention: AFK beads feed ralph's autonomous pipeline, HITL beads are routed to a person. We prefer AFK because human time is the scarce resource, and later review gates still catch agent mistakes — escalate only when completion or verification genuinely requires a human.
+- The rubric is deterministic, so this skill is a lookup rather than deep reasoning — which is why a cheap subagent suffices and the step 1 early exit exists.
 
-### 5. Return the classification
+## Verification checklist
 
-Report back `AFK` or `HITL` so the calling skill or agent can act on it.
+- [ ] `bd label list <id>` was checked before any other step.
+- [ ] Classification followed the precedence order: existing label → `## Type` → first-principles rubric.
+- [ ] The full bead body was read before classifying from first principles (step 3).
+- [ ] `bd tag <id> implementation-type:<afk|hitl>` was applied.
+- [ ] The calling skill or agent received the classification in the report.

package/skills/planning/create-task/REFERENCE.md

@@ -0,0 +1,40 @@
+# Create Task — Reference
+
+Detail behind `skills/planning/create-task/SKILL.md`. The script (`scripts/create-chores.ts`) is the source of truth for this contract; this document mirrors it for verification.
+
+## Script invocation
+
+```
+tsx create-chores.ts --parent <bead-id> [--priority <0-4>]
+```
+
+- Reads `<skill>/pipeline.json`; creates each stage chore via `bd create` and wires dependencies via `bd dep add`.
+- Prints a JSON object mapping each stage ID to its chore bead ID, plus `featurePrReview` for the PR gate.
+
+## Stage chore beads
+
+One per stage in `pipeline.json` (currently `code`, `verify`, `review`, `document`):
+
+- **Type**: `chore`
+- **Title**: `[<parent-id>] <stage title>` (e.g. `[abc-123] Code`)
+- **Labels**: `stage:<id>` (e.g. `stage:code`, `stage:verify`)
+- **Dependencies**: `parent-child` to the parent bead; `blocks` between stages per each stage's `dependsOn` (the script requires `dependsOn` targets to appear earlier in `pipeline.json`).
+
+## PR gate bead (`featurePrReview`)
+
+- **Type**: `task`
+- **Title**: `[<parent-id>] PR Review and Merge`
+- **Labels**: `implementation-type:hitl`, `lifecycle:feature-pr`
+- **Dependencies**: `parent-child` to the parent bead; `blocks` on the final document stage chore (`document`, falling back to the last stage in `pipeline.json`).
+- **Purpose**: human review of the agent PR (agent branch → feature branch) before the feature closes.
+
+## Current pipeline stages
+
+| id | title | dependsOn |
+|---|---|---|
+| code | Code | — |
+| verify | Verify | code |
+| review | Review | verify |
+| document | Document | review |
+
+`maxFixRounds: 4` — the maximum fix-retry rounds allowed for a stage's verify loop before the PR gate. Adjust stages only in `pipeline.json`; the script and templates follow it.

package/skills/planning/create-task/SKILL.md

@@ -1,96 +1,100 @@
 ---
 name: create-task
-description: Create a bead, classify it, and if AFK expand it into pipeline stage child beads plus a HITL PR gate task. Use when creating a new task that should be tracked and moved through implementation and human review gates.
+description: Create a task bead, classify it as AFK or HITL, and if AFK expand it into pipeline stage chores plus a HITL PR gate. Use when starting tracked work with implementation and review gates — "create a task for this", "track this end-to-end", or "get this into the ralph pipeline".
 ---
 
 # Create Task
 
-Create a bead, classify it via `classify-bead`, and — if AFK — expand it into child chore beads for each pipeline stage plus a child HITL PR gate task bead.
+Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or human-in-the-loop (HITL) execution, and — when AFK — expand it into the standard pipeline: one chore bead per stage plus a HITL PR gate task so a human always reviews the finished branch. Parameters: `title` (required), `description` (required), `priority` (0–3, default 2), `parent` (epic bead ID, optional — sets a `parent-child` dependency).
 
-## Inputs
+## When to use
 
-| Parameter   | Required | Description                          |
-|-------------|----------|--------------------------------------|
-| title       | yes      | Task title                           |
-| description | yes      | Task description                     |
-| priority    | no       | 0–3 (default 2)                      |
-| parent      | no       | Parent bead ID for `parent-child` dep |
+- Starting new tracked work that must move through implementation, verification, and review gates — user phrases like "create a task for this", "track this work end-to-end", or "get this into the ralph pipeline".
+- A caller (`prd-to-tasks`, `ralph-plan`) needs one task bead with the full child-chore structure.
 
-## Procedure
+## When NOT to use
 
-### 1. Create the bead
+- Work that is only a raw idea, not ready to build — use `record-idea`.
+- A feature that needs specification first — use `write-a-prd`, or `prd-to-tasks` to break an approved PRD into epics and tasks (`prd-to-tasks` calls this skill per task itself).
+- A ticket for an external issue tracker aimed at human engineers — use `write-a-ticket`.
+- A refactor that needs an incremental migration plan — use `request-refactor-plan`.
 
-```bash
-bd create "<title>" --description "<description>" --priority <priority>
-```
+## Workflow
 
-If a `parent` was provided, add a `parent-child` dependency:
+1. **Create the parent bead.**
 
-```bash
-bd dep add <new-id> <parent> --type parent-child
-```
+   ```bash
+   bd create "<title>" --description "<description>" --priority <priority>
+   ```
 
-Record the new bead ID.
+   If a `parent` epic was provided, record the dependency:
 
-### 2. Classify the bead
+   ```bash
+   bd dep add <new-id> <parent> --type parent-child
+   ```
 
-Invoke the `classify-bead` skill on the new bead (as a subagent per that skill's invocation instructions). It returns `AFK` or `HITL`.
+2. **Check for an existing classification label.** Run `bd label list <id>`. If `implementation-type` is already present, skip step 3 — re-classifying a labelled bead wastes a subagent call.
 
-### 3. Branch on classification
+3. **Classify the bead.** Delegate to the `classify-bead` skill as a subagent via {{TOOL:task}} — do not classify inline. It returns `AFK` or `HITL` and applies the `implementation-type` label.
 
-**If HITL**: stop. Report the bead ID and classification to the caller. No further action.
+4. **Branch on classification.**
+   - **HITL** — stop here. Report the bead ID and classification to the caller. Do not create pipeline chores: a human drives the work, so the chore tree does not apply.
+   - **AFK** — continue to step 5.
 
-**If AFK**: continue to step 4.
+5. **Expand into pipeline stage chores.** Run the `create-chores` script, which reads this skill's `pipeline.json` and deterministically creates all stage chores plus the PR gate bead in one shot:
 
-### 4. Expand into pipeline stage chores
+   ```bash
+   # Run from the TARGET project's directory — bd resolves its beads DB from cwd;
+   # the skill's own location or `pnpm --prefix <scripts>` would target the wrong tree.
+   <skill-scripts>/node_modules/.bin/tsx \
+     <skill-scripts>/create-chores.ts \
+     --parent <parent-id> [--priority <priority>]
+   ```
 
-Run the `create-chores` script, which reads `pipeline.json` and deterministically creates all
-stage chores in one shot. They are plain (non-ephemeral) chores — `bd ready` must surface
-them without `--include-ephemeral` for ralph to discover them:
+   `<skill-scripts>` is the absolute path to this skill's own `scripts/` directory, resolved from wherever this skill was loaded — it varies by harness and install location, so never hardcode one harness's path.
 
-```bash
-# Run from the TARGET project's directory (cwd must be inside the target's
-# .beads tree) — bd resolves its beads DB from cwd, not from the skill's
-# location. Do NOT use `pnpm --prefix <scripts> exec`, which changes cwd to
-# the scripts dir and makes bd pick the skill repo's own .beads instead of
-# the target project's.
-<skill-scripts>/node_modules/.bin/tsx \
-  <skill-scripts>/create-chores.ts \
-  --parent <parent-id> \
-  --priority <priority>
-```
+6. **Report.** Return the parent bead ID, the classification (`AFK`), and the created child bead IDs from the script output (including `featurePrReview`).
+
+## Red Flags
+
+- **Running the script from the wrong directory.** Chores land in whatever `.beads` tree `bd` resolves from cwd — the target project's root is the only safe cwd.
+- **Classifying inline.** The `classify-bead` rubric is a subagent's job (with a label short-circuit); inlining yours means re-reading bead content and drifting from the rubric.
+- **Expanding an HITL bead.** If classification is HITL, stop — creating a chore tree for human-driven work is wrong.
+- **Hardcoding `<skill-scripts>`.** The install path differs per harness (plugin cache, installed-plugins, dev checkout); resolve it at runtime.
+
+## Common Rationalizations
 
-Where `<skill-scripts>` is the absolute path to this skill's own `scripts/` directory —
-resolve it from wherever this skill was actually loaded from (it varies by harness and
-install location; e.g. a Claude Code plugin cache dir vs. a Copilot
-`~/.copilot/installed-plugins/...` install vs. a local dev checkout). Do not hardcode
-one harness's path.
+| Rationalization | Rebuttal |
+|---|---|
+| "I know this task is AFK — I'll skip the classify-bead call" | Classification is a rubric check against the full bead body; assumptions masked by familiarity cause mislabelled work to hit the wrong queue. |
+| "I'll create the chores by hand instead of running the script" | The script is the single source of truth for titles, labels, dep chains, and the PR gate. Hand-created chores drift silently. |
+| "The pipeline is overkill for this small task" | If the work is worth tracking at all, the stage chore tree is what lets ralph execute and gate it. Not ready for that? Use `record-idea`. |
 
-The script outputs a JSON object mapping stage IDs to chore bead IDs, plus a HITL PR gate task bead ID, e.g.:
+## Philosophy / rationale
+
+- **The script owns the expansion contract.** Pipeline stages, titles, labels, dependency chains, and the PR gate are deterministic — a one-shot script keeps every chore identical to the contract and reproducible across runs.
+- **The PR gate is a hard human checkpoint.** Every AFK task ends with a `featurePrReview` task that blocks the final document stage, so automated work never merges without a human reviewing the branch.
+
+## Cross-skill references
+
+- `classify-bead` — classify the new bead via subagent (step 3).
+
+## Examples
+
+Input: title `Add export API to invoices`, description `…`, priority `2`, parent `epic-456`. Output: the parent bead ID plus the script's JSON mapping stage IDs → chore bead IDs, with `featurePrReview` as the HITL PR gate:
 
 ```json
-{
-  "code": "abc123",
-  "verify": "def456",
-  "review": "ghi789",
-  "document": "jkl012",
-  "featurePrReview": "bd-mno345"
-}
+{"code": "abc123", "verify": "def456", "review": "ghi789", "document": "jkl012", "featurePrReview": "bd-mno345"}
 ```
 
-Each stage chore is created with:
-- **type**: `chore`
-- **Title pattern**: `[<parent-id>] <stage title>` (e.g. `[abc-123] Code`)
-- **Labels**: `stage:<id>` (e.g. `stage:code`, `stage:verify`)
-- **Dependencies**: `parent-child` to parent bead; `blocks` between stages per `dependsOn`
-
-The PR gate bead is created with:
-- **type**: `task`
-- **Title**: `[<parent-id>] PR Review and Merge`
-- **Labels**: `implementation-type:hitl`, `lifecycle:feature-pr`
-- **Dependencies**: `parent-child` to parent bead; `blocks` on the final document stage chore
- - **Purpose**: human review of the agent PR (agent-branch → feature branch)
+The full bead-property contract (titles, labels, dependencies per chore and for the PR gate) is in `REFERENCE.md`.
 
-### 5. Report
+## Verification checklist
 
-Return the parent bead ID, classification (`AFK`), and the list of created child bead IDs (including `featurePrReview`).
+- [ ] Parent bead exists with the correct title, description, and priority.
+- [ ] `parent-child` dependency added when a parent epic was supplied.
+- [ ] `implementation-type` label present on the parent bead (`bd label list <id>`).
+- [ ] HITL path: no pipeline chores created, caller told the classification. AFK path: script ran from the target project's cwd and its JSON contains every stage ID plus `featurePrReview`.
+- [ ] Chore titles/labels/dependencies match the contract (`[<parent-id>] <stage title>`, `stage:<id>`, `parent-child` to parent, `blocks` per `dependsOn`), verified against `REFERENCE.md`.
+- [ ] PR gate task exists with `implementation-type:hitl` + `lifecycle:feature-pr` labels and blocks the final document stage chore.
+- [ ] Report returned the parent bead ID, classification, and all child bead IDs.

package/skills/planning/create-task/scripts/create-chores.ts

@@ -39,8 +39,13 @@ function parseArgs(args: string[]): { parentId: string; priority: string } {
 
 // ─── Exec ─────────────────────────────────────────────────────────────────────
 
+// BD_PATH env override lets machines where bd is not on PATH pin a location.
+// Defaults to `bd`, resolved via PATH.
+const BD_PATH = process.env.BD_PATH || 'bd';
+
 function run(args: string[]): string {
-  return execSync(args.join(' '), { encoding: 'utf-8' }).trim();
+  const cmd = args[0] === 'bd' ? [BD_PATH, ...args.slice(1)] : args;
+  return execSync(cmd.join(' '), { encoding: 'utf-8' }).trim();
 }
 
 // ─── Main ─────────────────────────────────────────────────────────────────────

package/skills/planning/create-task/scripts/node_modules/.bin/tsc

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/skills/planning/create-task/scripts/node_modules/.bin/tsserver

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/typescript@5.9.3/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/skills/planning/create-task/scripts/node_modules/.bin/tsx

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules/tsx/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/tsx@4.22.4/node_modules:/home/runner/work/agent-cortex/agent-cortex/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../tsx/dist/cli.mjs" "$@"
+else
+  exec node  "$basedir/../tsx/dist/cli.mjs" "$@"
+fi