AI Dev Assistant

Use when a framework task requires specialized guide content — delegates to the dev-guides-navigator plugin for online guide discovery with caching and disambiguation.

Use when converting a flat task into an epic folder with children, promoting a subtask to a sub_epic, or expanding an existing epic with more children. Runs the 8-step transactional migration via scripts/migrate-to-epic.sh. Supports --dry-run for preflight plan. Never leaves half-migrated state on disk.

Use when a development task needs recipe + guide discovery — matches 0..N agentic recipes for the task, unions the guides and plays they require, runs residual guide-search over uncovered aspects, and emits a ranked coverage map (aspect → recipe/guide/play; uncovered flagged). Delegates ALL fetching to the dev-guides-navigator plugin; never re-implements the fetcher and never extends guides-matcher. Invoked by the phase flow or an orchestrator at the front of a task.

Use during implementation to enforce TDD - reminds test-first, validates the Red-Green-Refactor cycle, integrates with superpowers:test-driven-development. Trigger: 'test first', 'write tests', 'Red Green Refactor', 'TDD workflow'. MUST be active during all Phase 3 implementation. NEVER write implementation code before tests. Stack-neutral; the framework test types come from the resolved implement recipe.

Use when determining task phase - analyzes task file to identify Phase 1, 2, or 3 for a specific task

Use when finishing a task — moves the v3.0.0 task folder to completed/, updates project_state.md, suggests next task. Runs all 5 quality gates and blocks completion if any gate fails. Trigger: 'finish task', 'done with task', 'move to completed'.

Use when an orchestrator must run the autonomous per-task run-loop behind the gate floor — the thin native glue (③ lifecycle_controls). Resumes from disk (L1-light), drives a ready-queue over the work-orders (a WO is ready when all blocked_by are done), dispatches ONE build atom per WO in clean context, runs /review --headless + the work-order-critique rung per WO, owns EVERY WO status transition via wo-compile.sh set-status, bounds the verify→fix loop with a crash-safe retry cap (wo-run-state.sh), and at the end opens a PR through the wo-pr-open.sh choke point that re-runs the merge gate and NEVER merges. Reads every decision from disk; treats builder transcripts as untrusted data; honors a budget/kill-switch call-site. MUST be invoked inline (never Task-dispatched). Prints a ready-to-paste /goal string; never runs /goal itself.

Use when a framework command needs to parse a task's alignment.md (the scope contract — Goal / Expected result / Success criteria / Non-goals per section). Reads defensively via scripts/alignment-read.sh and returns structured JSON with warnings. Never blocks on malformed input.

Use when a phase command (research/design/implement) needs to load methodology references, online dev-guides, and project playbooks before task work begins. **v4.10.0+: hybrid detection** — a deterministic phase-aware methodology floor + lexical catalog candidates via scripts/dev-guides-detect.sh, plus semantic matches from the guides-matcher agent. Delegates guide fetching to dev-guides-navigator. Loads playbook layers via scripts/playbook-load-deterministic.sh. Cross-references conflicts. Records loaded guide IDs into session_context.json loadedGuides[] to prevent re-loads.

Use when an orchestrator must build exactly ONE contract-conformant work-order in clean context — gates it through wo-compile.sh assert-dispatchable (fail-closed; never spawn on a non-zero gate), checkpoints the shared code worktree, spawns one fresh standard Task-tool subagent whose prompt is the self-contained work-order body, treats the collected transcript as untrusted data, commits the worktree only if it shows changes, and returns the disk-derived collect-handle JSON. A per-work-order atom: no loop, no verdict, no /review; read-only on the work-order BODY, and its ONLY status write is the `ready→in_progress` flip (after its re-gate, before it commits — the crash-safety hinge). Invoked per-WO by the lifecycle_controls loop; runs in the orchestrator's main context (its single Task spawn is the one supported depth-1 level).

Use when needing the framework's canonical implementation example for a pattern - searches the framework's own source for the pattern and returns file-path references

Use when starting a new development project — creates memory folder structure with project_state.md (including codePath), architecture scaffolding, and registers project. Accepts optional code_path argument.

Use when starting implementation of a task - loads architecture files, referenced patterns, relevant guides, and task file into context

Use when a /design-complete ai-dev-assistant task must become N self-contained, gate-verifiable work-orders — decomposes architecture.md Components into units, attaches falsifiable Current/Target/Acceptance + [CATEGORY]-NN requirement IDs, derives dependency edges, slices the coverage-map per unit, inlines the load-bearing build context, and emits each work-order to the task's work-orders/ folder (wo-NN-{slug}.md) against the frozen schema_version 1.0 contract. The judgment lives here; all determinism (SCC/acyclicity, fail-closed verified, drift-guard, lockfile SHA, frontmatter emit) delegates to the wo-compile.sh kernel. Invoked by an orchestrator or the /compile-work-orders command, never typed by a user.

Use when an orchestrator must run the opt-in adversarial-critique rung on ONE built work-order — the absent-human review layered ABOVE the deterministic gates. Derives the work-order's risk tier (wo-risk-classify.sh), decides whether critique is required (forced-on for high-risk-unattended; else the per-task/per-project dial), spawns risk-scaled INDEPENDENT fresh-context wo-critic agents that re-derive the verdict from artifacts (git diff + gate envelopes), aggregates fail-closed (wo-critique-aggregate.sh) into a per-WO _critique.json, and writes a wo-NN.HALT marker when blocking. Fan-out is the unattended primitive; never edits /review's _review.json. A judgment layer, not a gate — gates always run first.

Use before committing code - validates code against SOLID, DRY, security, and purposeful-code principles (stack-neutral). Trigger: 'check code quality', 'pre-commit check', 'validate standards', 'review this'. Use proactively before any commit. The concrete stack linters are the code-quality-tools plugin's job; the framework-specific implementation rules come from the resolved implement recipe.

Use when a framework command needs project-level metadata (codePath, playbookSets, userPlaybook, playbookResolutions, project_name). Reads project_state.md defensively via scripts/project-state-read.sh and returns structured JSON with warnings. Never blocks on malformed input.

Use when migrating existing single-file tasks to folder-based structure - preserves content, creates organized folders, backs up originals

Use when a lifecycle orchestrator reaches a phase boundary and needs the framework-specific process recipe that drives that phase. Checks project_state first (a recorded source is the memory of the prior decision and resolves directly); on a miss resolves by source order (repo-local, machine-local, dev-guides) and on a true miss returns action:ask-user for the orchestrator to ask the user. Tags provenance strictly (verified:true only for dev-guides upstream), records the source choice in project_state.md, and reports a body_path the orchestrator reads alongside a structured JSON report. Delegates ALL fetching and store operations to the dev-guides-navigator plugin; never touches the navigator plugin's filesystem directly.

Requirements Gatherer

Use when a framework command has resolved the active project and/or task and needs to persist that context for hooks. Writes per-workspace session_context.json so compaction hooks and the context-reminder hook can restore the right project/task context. Preserves loadedGuides[], lastPhase, and currentEpic across writes.

Use when a framework command needs to inspect the project's visual-regression baseline store — the codePath-native tests/visual/ snapshot tree. Reads the store defensively via scripts/screenshot-store-read.sh and returns structured JSON. Never blocks on malformed input.

Use when a framework command needs to read the hierarchy metadata of a task — parses the YAML frontmatter block at the top of task.md and returns structured data (id, kind, parent, children, blocks, blocked_by, external_ids, derived status) plus any warnings. Defensive: never blocks on malformed input; absent frontmatter yields kind=flat. Delegates to scripts/fm-read.sh.

Use when an orchestrator must run a task's work-orders CONCURRENTLY behind the same gate floor as the sequential loop — the DB-free parallel sibling of work-order-loop. Each round it reconciles from disk (L1-light), selects a disjoint-file ready batch (wo-parallel-batch.sh), builds every batched WO at once in its OWN ephemeral git worktree branched off the integration HEAD (N parallel build atoms in ONE message), runs /review --headless + the work-order-critique rung per worktree, derives every verdict from disk, and merges each CLEAN WO back into the integration branch with a LOCAL git merge (wo-merge-back.sh — NOT a PR merge), pruning each ephemeral worktree after its verdict. The per-WO retry cap stays the SOLE responsibility of wo-run-state.sh dispatch; terminal-HALT precedence, disk-is-truth, and no-auto-merge are preserved verbatim. At the end it runs ONE integrated /review on the integration branch and opens ONE PR through wo-pr-open.sh (re-runs the merge gate, NEVER merges). MUST be invoked inline (ne

Use when a development task needs the project's own prior art searched before any external prior-art search. Matches the task's capability aspects against the project's own task record (completed and in-progress) and the code at codePath, returns reuse / extend / supersede per hit with the cost dimensions it compared, and writes the internal prior-art research subject. Invoked by the research phase before the external prior-art dispatch; records per-source "not searched, and why" rather than reporting a clean result. Never installs, runs, or maintains a code map.

Use when breaking down a component for implementation - creates task file in implementation_process/in_progress/ with TDD steps and acceptance criteria