// Generate step-by-step implementation plans with verification criteria. Use when the user asks 'how should we do this', 'make a plan', 'break this down into steps', 'what's the approach', or needs a roadmap before implementation.
| name | plan |
| description | Generate step-by-step implementation plans with verification criteria. Use when the user asks 'how should we do this', 'make a plan', 'break this down into steps', 'what's the approach', or needs a roadmap before implementation. |
| model_tier | heavy |
| auto_delegatable | false |
| triggers | {"keywords":{"zh":["计划","方案","规划","实现步骤","怎么做","出方案","拆步骤"],"en":["plan","approach","implementation steps","how to implement","design plan","break down"]},"phrases":{"zh":["出个计划","制定方案","怎么实现","拆成步骤","做个规划","重新规划","换个方案"],"en":["generate a plan","make an implementation plan","how should we implement this","break it into steps","replan"]},"disambiguate":"Core intent: generate or regenerate an actionable implementation plan (.plan.md). User asks HOW to implement something → plan. User asks WHAT to implement → target. User asks to INVESTIGATE options → research.\n"} |
| arguments | [{"name":"--generate","description":"Generate or regenerate the implementation plan (flag, no value). Default behavior when invoked — the flag exists for explicitness in auto mode commands","required":false},{"name":"--refine","description":"Append a refinement to existing plan (used by agent during plan-refinement phase). Requires a quoted string value, e.g., --refine \"description\"","required":false}] |
Generate an implementation plan from .target.md. Annotation processing is handled by the annotate sub-command.
Path Rule: All system files (
.status.json,.target.md,.plan.md, etc.) are in$TASKAI_WORK_DIR/(=$NB_WORK_DIR/.working/), NOT in$NB_WORK_DIR/directly. Seecommands/task-ai.md§System File Path Rule.
# Generate mode: create/regenerate plan
/task-ai:plan [--generate]
# Refine mode: append refinement (agent calls this during conversation)
/task-ai:plan --refine "Add caching layer between API and database"
Notebook auto-detection: The notebook is automatically resolved from CWD (.status.json) or the current git branch (task/<notebook>). No manual notebook parameter needed.
--generate is the default behavior — the flag exists for explicitness when invoked from auto mode or scripts. Omitting it has the same effect.
After plan generation, the agent monitors conversation for plan refinements:
.status.json to confirm status: planning/task-ai:plan --refine "content"/task-ai:execThe agent maintains phase awareness via .status.json (see Phase Awareness Protocol in commands/task-ai.md).
.target.md for requirements. Stage awareness: read .status.json stage field (default { current: 1, history: [] } if missing). If stage.current > 1 (multi-stage mode):
[ACTIVE] stage's Objective/Requirements/Constraints from .target.md — plan scope is limited to the current stagestage.history from .status.json — get each completed stage's name, convergence score, and commit SHA
1.2. Read prior [COMPLETE] stages' ### Results sections from .target.md — what was delivered
1.3. Read .deliverables/ — inspect actual files/code produced by Stage 1..N-1
1.4. Read latest .analysis/*-convergence.md — which R# are met (ci=1.0) vs partially met vs unmet
1.5. Read prior stage reports if available (.analysis/ files) — known issues, workarounds, architectural decisionsstage.current == 1: read entire .target.md as before (backward compatible).target.md has no objective items with [CONFIRMED] or [PROCESSED] markers AND no ## Stage sections exist, REJECT with error: "Cannot generate plan — no confirmed objectives. Run /task-ai:target to confirm at least one objective item first." (Plan only covers [CONFIRMED] items; unconfirmed items are excluded from scope).convergence-baseline.md from .working/ directory for requirement coverage mapping. This file contains numbered requirements (R1, R2, ...) extracted by target from the convergence baseline:
.convergence-baseline.md exists → parse the R# requirement list for use in plan step annotation (step 16).convergence-baseline.md does not exist → warn ("convergence baseline not found — skipping R# coverage mapping") and continue. This is backward compatible — older targets may not have generated itresearch sub-command. Invocation method: in auto mode, Read skills/research/SKILL.md and execute its numbered steps inline. In manual/standalone mode, use Skill tool to invoke /task-ai:research. See skills/research/SKILL.md and references/type-profiling.md for details:
draft/planning, no existing .plan.md):
.target.md contains ## Research Insights section (indicates research --caller target was already run)## Research Insights present: invoke research with --scope gap --caller plan — target research already provided comprehensive coverage, only fill plan-specific gaps## Research Insights: invoke research with --scope full --caller plan — full collection (backward compatible, works when user skips target research)re-planning/review/executing): invoke research with --scope gap --caller plan — incremental type refinement and reference collection.type-profile.md — research has created or updated this. Verify the type classification makes sense in context. If plan disagrees with research's classification, update .type-profile.md with rationale and adjust type in .status.json[a-zA-Z0-9_:-]+, full field matches ^[a-zA-Z0-9_:-]+(\|[a-zA-Z0-9_:-]+)*$ (no leading/trailing/consecutive pipes). Ensure type in .status.json is set.summary.md if exists (condensed context from prior runs — primary context source).analysis/ latest file only if exists (address check feedback from NEEDS_REVISION).bugfix/ latest file only if exists (address most recent issue from mid-exec or post-exec REPLAN).test/ latest criteria and results files if exists (incorporate lessons learned)commands/references/changelog-consumption-protocol.md)$NB_WORKSPACES_LIBRARY/.memory/.experiences/<type>/.summary.md if exists — condensed cross-task experience from completed tasks of the same domain type (apply directory-safe transform: : → - in type for directory name, e.g., science:astro → science-astro). For hybrid types (A|B), read summary files for all pipe-separated segments. If summary references specific entries relevant to current task, read those $NB_WORKSPACES_LIBRARY/.memory/.experiences/<type>/<module>.md files for detail
.plan.md under ## Adopted Experiences (append if section exists). Format: - <lesson summary> ← .experiences/<type>/<source-file>.md. This enables downstream adoption tracking by highlight and report/task-ai:library search "<keywords>" with domain keywords from .target.md and .type-profile.md. Library search handles index reading, keyword matching, and relevance scoring internally — read matched files (Layer 3) for domain knowledge needed during planning. Best Practice: prefer library search over direct file reads for multi-factor scoring, graph recommendations, and token budget control.notes/ latest file only if exists (prior research findings and experience)re-planning or review/executing transitioning to re-plan): archive existing .plan.md — rename to .plan-superseded.md (append numeric suffix if already exists, e.g., .plan-superseded-2.md). This prevents exec from reading outdated steps alongside the new plan.convergence-baseline.md was loaded in step 2, annotate each plan step with a Covers: R#, R# line indicating which baseline requirements that step addresses. Example:
## Step 3: Implement JWT middleware
Covers: R1, R5
- Verify token signatures...
- Rate limiting logic...
Covers: lines and cross-check against the full R# list from .convergence-baseline.md. If any R# is not covered by any step → add warning in plan notes section: "Uncovered requirements: R3, R7 — verify these are intentionally deferred or covered implicitly". This is a soft check (warning, not blocking) — the hard check is done by check --checkpoint post-plan.analysis/ file's findings. After generating the new plan, verify each finding is addressed: for each issue flagged by check, confirm the new .plan.md contains the corrective content (contract test: grep for expected content). Log unaddressed findings as warnings in the step 28 report.plan.md), follow auto/references/plugin-delegation.md to attempt matching the brainstorm capability slot. If matched, invoke via Task subagent — exploration results serve as supplementary planning input. No match or failure → continue normally.plan.md in the task module.test/<YYYY-MM-DD>-plan-criteria.md with domain-appropriate verification criteria: acceptance criteria from .target.md + per-step test cases using methods standard in the task domain. On re-plan, write .test/<YYYY-MM-DD>-replan-criteria.md incorporating lessons from previous .test/ results filestype contains software): Generate executable failing VH stubs:
<workspace>/.test/<YYYY-MM-DD>-vh-stubs.test.* (language/framework determined by .type-profile.md or project conventions)// VH: not implemented.test/<YYYY-MM-DD>-vh-baseline.md recording: total VH stubs count, per-step stub mapping, run output confirming all failures.plan.md, annotate each implementation step with its corresponding VH stub references (e.g., [VH: test-auth-login, test-auth-logout])commands/references/test-strategy-by-type.md Strategy Matrix:
.test/<YYYY-MM-DD>-contract-baseline.md with per-step verification specs: test approach (content validation, schema check, link check, etc.), RED assertion (what fails before implementation), GREEN expectation (what passes after).plan.md, annotate each implementation step with its verification method (e.g., [Contract: schema-validate, link-check])exec has a concrete RED→GREEN pathway for every step, regardless of task type.test/.summary.md — overwrite with condensed summary of ALL criteria & results files in .test/.notes/<YYYY-MM-DD>-<summary>-plan.md with research findings and key decisions.notes/.summary.md — overwrite with condensed summary of ALL notes files in .notes/.summary.md with condensed context: plan overview, key decisions, requirements summary, known constraints (integrate from directory summaries).status.json (atomic write required):
.status.json"status": "planning" (from draft/planning/blocked) or "re-planning" (from review/executing/re-planning)"phase": "needs-check" if new status is re-planning, otherwise """completed_steps": 0 (new plan invalidates prior progress)"type" field if not already set"updated" timestamp to current ISO-8601.status.json again to confirm status field changed. If still draft, the update FAILED — retry or abort.target.md: for each objective item with [CONFIRMED] that is covered by the plan, change marker to [PROCESSED]skills/highlight/SKILL.md §3.3. Optional, encouraged (high-value). Capture design and trade-off reasoning. Inline call failure should not block plan's main flow — highlight is enhancement, not gating.plan.md against .target.md and .convergence-baseline.md using the unified six-dimension checklist (references/self-audit-checklist.md). For each dimension (D1 Correctness → D6 Maintainability), check 2-4 items and fix issues in-place:
.plan.md, .target.md, .convergence-baseline.md (if exists), .type-profile.md (if exists).type-profile.md to shift emphasis (e.g., software → Security↑ Reliability↑, infrastructure → Security↑↑ Reliability↑↑). Full weight table in references/self-audit-checklist.md section 2.plan.md with regression verification:
commands/references/test-strategy-by-type.md exemptions), verify the fix using a contract test: grep/regex confirming the corrected content is present and the defective content is absent. This is the "Spec text" test approach from the Strategy Matrix.analysis/ files — that is check's responsibilitytask-ai(<notebook>):plan generate implementation plan/task-ai:check --checkpoint post-plan to review the plan (runs verify automatically)."Context management (plan): When .summary.md exists, read it as the primary context source for plan generation instead of reading all files from .analysis/, .bugfix/, .notes/. Only read the latest file from each directory for the most recent assessment/issue/note. See also skills/exec/SKILL.md for the equivalent exec-phase context rule.
| Current Status | After Plan | Condition |
|---|---|---|
draft | planning | First plan generation |
planning | planning | Plan revision |
review | re-planning | Revisions after assessment |
executing | re-planning | Mid-execution re-plan |
re-planning | re-planning | Further revisions |
blocked | planning | Unblocking changes |
satisfied | REJECT | Use /target to re-enter first |
evolving | REJECT | Use /target to define next stage first |
cancelled | REJECT | Cancelled tasks cannot be re-planned |
task-ai(<notebook>):plan generate implementation plan
Plan methodology adapts to the task domain — a software task needs test-first steps while a documentation task needs outline-first structure. Different domains require different step granularity and verification approaches.
See
skills/init/references/seed-types/<type>.mdfor per-type seed methodology (plan structure, key considerations). Shared profiles in$NB_WORKSPACES_LIBRARY/.memory/.type-profiles/take precedence when available.
.target.md and .plan.md)research sub-command (step 3). For plan-specific decisions, use shell commands to verify claims (curl docs/APIs, npm info, etc.) rather than relying solely on internal knowledge.lock before proceeding and releases on completion (see Concurrency Protection in commands/task-ai.md). Reference writing is handled by the research sub-command (which manages its own .memory/.references/.lock).test/ criteria must use domain-appropriate verification methods (e.g., unit tests for code, SSIM/PSNR for image processing, SNR for audio/DSP, schema validation for data pipelines). Research established best practices for the task domain before writing test criteria. See commands/references/test-strategy-by-type.md for the full domain test strategy referenceCovers: R# to map to convergence baseline requirements when .convergence-baseline.md is present. This enables check to verify requirement coverage at post-plan and track convergence at post-exec. The mapping is advisory (soft warning for gaps) — the hard coverage check is performed by check --checkpoint post-plancommands/references/test-strategy-by-type.md Phase Responsibilities). However, plan's L1 self-audit (step 26) and re-plan regression check (step 16) both apply fixes to .plan.md — these must include contract-test verification per the Regression Test Protocol. Step 19 generates the RED baseline that exec will use for RED→GREENProcess file annotations — triage, cross-impact assessment, and execution. Triggered automatically when annotations (Insert/Delete/Replace/Comment) are submitted from the file viewer UI via JSONL prompt.
Six-dimension gated review — evaluates plans, implementations, and skills through D1-D6 quality gates with convergence tracking. Use for post-plan review, mid-exec assessment, post-exec acceptance, or any time the user says 'check', 'review', 'audit', 'evaluate quality', or wants to know if deliverables are ready.
Execute the implementation plan — write code, make changes, build the deliverables. Use when the user says 'do it', 'implement', 'start coding', 'execute the plan', 'build it', or wants to begin actual implementation work after planning is complete.
Cross-task knowledge library management — search, list, audit, maintain, and evolve the shared .library/ knowledge base. Includes security rules evolution loop (separate from task auto loop).
Investigate requirements and domain knowledge to support any lifecycle phase. Default mode: autonomous objective refinement (O1→O2→O3) with background research, feasibility analysis, and goal synthesis — all three stages completed in one pass. Also callable from plan, exec, verify, or check for gap-only reference collection. Use when the user wants to understand before acting — 'research this', 'what are the options', 'feasibility analysis', or 'deepen the objective'.
Define task objectives and requirements in .target.md. Use when the user describes what they want to build, says 'I want to...', 'the goal is...', 'set the target', 'define requirements', or needs to clarify/refine what should be accomplished before planning.