AGENT SKILL

do-plan

Generate the implementation plan (HOW) and dependency-ordered task checklist from requirement.md + design.md (plus design/specs.md's IC-### interface contracts when the feature has one), with a Constitution Check gate, as Phase 3 of the doflow chain. Use whenever requirement.md and design.md exist and the next step is creating an actionable, owner-and-file-scoped task breakdown before implementation, or when the user says 'create an implementation plan', 'break this down into tasks', 'plan the work', or 'plan Phase 3'. Always activate this skill before executing feature implementation.

License 许可
MIT
所属仓库
khoavu882/do-flow
最近更新
2026-11-10
Stars
★ 0
Forks
0

01 前言 Front Matter

name
do-plan
effort
high
description
Generate the implementation plan (HOW) and dependency-ordered task checklist from requirement.md + design.md (plus design/specs.md's IC-### interface contracts when the feature has one), with a Constitution Check gate, as Phase 3 of the doflow chain. Use whenever requirement.md and design.md exist and the next step is creating an actionable, owner-and-file-scoped task breakdown before implementation, or when the user says 'create an implementation plan', 'break this down into tasks', 'plan the work', or 'plan Phase 3'. Always activate this skill before executing feature implementation.
argument-hint
[--depth shallow|normal|deep]

03 SKILL.md 正文

do-plan

Phase 3 of the doflow chain. Turns requirement.md (WHAT/WHY) + design.md (system shape) — and design/specs.md's IC-### interface contracts when /do-design wrote one — into plan.md (HOW to implement, plus the dependency-ordered task checklist).

Invocation

/do-plan [--depth shallow|normal|deep]

Behavioral Flow

  1. Resolve — run the resolver, parse JSON. Every DoFlow runtime call in this skill goes through the runtime seam. Resolve it once here and reuse $DOFLOW for every later call in this skill:
# Resolve the DoFlow runtime: nearest project install wins, then the global one.
D=$PWD; while [ "$D" != / ] && [ ! -x "$D/.doflow/scripts/doflow/bin/doflow-run" ]; do D=$(dirname "$D"); done
DOFLOW="$D/.doflow/scripts/doflow/bin/doflow-run"
[ -x "$DOFLOW" ] || DOFLOW="$HOME/.doflow/scripts/doflow/bin/doflow-run"
[ -x "$DOFLOW" ] || { echo "doflow: no runtime found in any .doflow/ above $PWD, nor at $HOME/.doflow. Run: npx @khoavu882/doflow install -t <harness>" >&2; exit 2; }

Run every command below from the project root — the walk-up starts at $PWD. On exit 2, print the message verbatim and stop; it names every path searched.

"$DOFLOW" paths --json

feature_slug null with a non-empty candidate_slugs is an unresolved choice, not "no active feature": ask one option per entry, re-resolve with "$DOFLOW" paths --json --slug="<chosen>", and use that slug for the rest of this flow. /do-flow passing --slug already resolves it — no prompt then.

Once per stage, after feature_slug resolves, run "$DOFLOW" attendance --task-id "<feature_slug>"; unattended → references/WORKFLOW_HANDOFF.md § Unattended stage.

  1. Propose one task class; the runtime validates it — name exactly one class id for the work being planned. /do-flow passes one when it invoked this skill; a user who named one settles it; otherwise derive it from requirement.md and design.md, not from their mere existence.
    "$DOFLOW" classify --task-class "<proposed>" --calling-skill do-plan --view brief --json
    

Branch on outcome, not the exit code.

  • ACCEPTED — the returned workflow is this run's plan of record; read stages, gates and handoff off it rather than from memory.
  • REJECTED — stop. Print message verbatim (it already names validClasses and any suggestions), ask the user to choose from validClasses, then re-validate. Never substitute feature. A rejection may be about you rather than the class (reason: caller-not-a-stage). Then the fix is to propose one of the classes in fit.hostingClasses, or to hand the work to the skill this class names for the stage you meant — not to re-propose the same class.
  • Exit 2 — surface the message verbatim and stop.

This skill is the accepted workflow's planning stage: state the class and the signal it rests on in one line. Its stageIds are also what §8's phases must decompose toward, and its implementation stage's readinessTemplate names the contract /do-execute-plan will be graded against — read them off the returned object rather than assuming the six-stage feature chain. If the accepted stageIds contain no planning stage, say so and hand off to the first stage they do name. Only feature plans; bug, refactor, dependency-change and trivial-edit go straight from their analysis stages to implementation, and writing them a plan.md adds a gate their workflow deliberately does not have.

  1. Precondition (advisory) — if has_requirement or has_design is false, warn and offer to run /do-brainstorm / /do-design first. This gate is advisory (skippable), like the edit hook.
  2. Read inputs — compile the recorded prior context first, using the same task id rule step 10 uses below (the plan task id for anything already scoped to a single - [ ] task, otherwise the feature slug):
    "$DOFLOW" context-pack --task-id "<task id>" --json
    
    Exit 1 means the pack came back empty; exit 3 means overflow: the pack is complete, act on overflowAction.message and report the gap. By this point do-design should have batched evidence and claims (step 8), so an empty pack carries weight: either the batch never ran or the task id mismatched. Empty packs are advisory; prerequisites check artifact existence only. Report them in this stage's report and plan.md §3 "Research & Decisions"; prose without a compiled pack cannot claim prior evidence. When non-empty, read it alongside requirement.md, design.md, and the constitution. Also read specs.md when step 1's has_specs is true — use that flag, never a filesystem check of your own, and read the specs path the resolver returned. /do-design moves the interface and data-model contracts out of design.md into specs.md §1 as numbered IC-### entries, so on a feature that has one, design.md's API / Interface Contracts and Data Model sections are a pointer and the contracts this plan must decompose toward live only in specs.md. Planning from design.md alone on such a feature plans against a pointer. When has_specs is false (an old-layout feature dir, which never had a specs.md), the contracts are still in design.md (API / Interface Contracts, Data Model) and there is nothing extra to read. Read constitution_base, then read constitution_local only when has_constitution_local is true — use that flag, never a filesystem check of your own (path math belongs to the resolver). You then reconcile the two tiers yourself, tier-2 taking precedence: nothing hands you a merged set. See the guidance tree's references/DOFLOW_CHAIN.md → "Two-tier constitution" for what is computed and what is convention.
  3. Write plan.md, sections 1–7 — copy the plan template to the plan path step 1 resolved (<feature_dir>/plan.md, the same flat location under both the structured and legacy layouts), mkdir -p-ing its parent directory first. The template is templates/doflow/plan-template.md in the install step 1 resolved: take constitution_base from that JSON and swap its trailing guidance/references/CONSTITUTION_BASE.md for that path. Fill [REQUIREMENT_PATH]/[DESIGN_PATH] with that same step 1 resolution's requirement/design fields, verbatim (repo-root-relative, exactly as the resolver returns them) — never hand-written ./ links, which assume the artifact sits next to plan.md; under layout: structured it instead sits in a sibling subdirectory, and only the resolver's own field says which. Fill it: approach, research/decisions that resolve every [NEEDS CLARIFICATION] from the requirement, components, data/contracts, risks, validation strategy. §5 "Data / Contracts" cites contracts by id, not by pointer: when step 4 read a specs.md, name the IC-### ids that this plan's tasks implement or consume, one per contract, so a task can be traced to the contract it satisfies. Pointing §5 at design.md is only correct when has_specs is false and the contracts genuinely still live there. When the feature has a data-model.md (check the resolver's has_data_model flag, the same way has_specs is already checked), also name any entities/tables from its schema catalog that this plan's tasks touch, citing them by the name the schema catalog already gives them — never inventing a new id scheme, since data-model.md carries no ID-bearing index the way specs.md does. Stop when every [NEEDS CLARIFICATION] marker / open decision the contract names has an answer or a stated gap, and the last round produced no new [NEEDS CLARIFICATION] marker / open decision. A round that only restates what you already have is the last round. Report the remaining gaps rather than continuing. Structure the artifact per the guidance tree's references/ARTIFACT_FORMAT.md — read it before filling the template; it names which of this artifact's sections take an index-then-detail table. Filling §8's task dependency graph, read the guidance tree's references/DIAGRAM_GUIDE.md first — §4 above names the slot, that file governs what goes in it: the flowchart node and edge ceilings, the direction convention, and the rule for splitting a graph that outgrows them. Its §5 governs §8's ### Task Summary rollup — the per-task - [ ] checklist stays the single source of truth and is never mirrored into a per-task index. Read references/ARTIFACT_VOICE.md at the same point: it carries the prose rules the artifact's sentences follow, and the carve-outs where one of those rules meets a construct the checker parses. This stage fills the plan from requirement + design + constitution rather than by eliciting, so it writes no dialogue log — its sibling stages' intention//design/ question files have no counterpart here. Should a future revision of this skill add a question-tool clarification loop, each of its rounds logs to plan-<NN>-question.md at the feature root exactly as /do-brainstorm and /do-design log theirs to their own subdirectories, numbered from step 1's plan_next_round.
  4. Constitution Check (exit gate) — evaluate the plan against both tiers as reconciled in step 4. Record one row per principle in plan.md §2: its id, its tier (MUST unless it says **Tier:** SHOULD) and PASS/FAIL; a base MUST that tier-2 makes SHOULD names that overlay version in its row. On a violation, revise the approach first. A MUST marked FAIL or left without a row refuses step 11's handoff; a SHOULD FAIL is a note. That refusal is the runtime's, beside the advisory hook on artifact existence (references/DOFLOW_CHAIN.md scopes both). There is no waiver: revise the plan, or a person amends the constitution with /do-constitution.
  5. Decompose into Tasks (section 8) — dependency-ordered, [US#]-traced to the requirement's user stories, owner+files named per task, with checkpoints and completion criteria. Read the guidance tree's references/ORCHESTRATION.md and references/MODEL_SELECTION.md before assigning agent owners and write sets. --depth shallow|normal|deep is the single granularity knob: it sets how finely a phase is split into tasks and how much detail each task carries. Default normal. Why explicit task scoping and [P] markers: Specifying concrete file paths (files: [...]) and agent-spec owners (review tasks name reviewer) per task enables /do-execute-plan to compute write-set isolation (parallel-check). Tasks with disjoint file sets run concurrently without merge conflicts, while overlapping tasks are safely serialized. Mark [P] by default: parallel execution is the framework default, so apply [P] to every task whose files: set is disjoint from its phase siblings' and leave it off only where a real dependency forces the order — an unmarked task is the exception that owes a reason, not the norm. Siblings that write any path in common are not parallel-safe however independent they otherwise look, so compare the actual files: sets rather than judging by description. Do not change the marker's syntax or meaning: unmarked still means sequential, which is what keeps plans written before this rule behaving as they always did. Set depends-on: on a task when it references a service (via its files: or description) that has no owning task in this plan and is external to what the plan builds. When such a dependency has no local repo at all (a vendor API, a SaaS integration) but does have a documented contract, also set external-contract: pointing to a doc built from templates/doflow/external-contract-template.md — /do-execute-plan --scaffold generates a real frame from it instead of silently skipping the dependency (its default when external-contract: is absent). The - [ ] checkboxes are the execution contract /do-execute-plan parses — keep the marker syntax intact, don't reflow it into prose.
  6. Derive branch plan — read requirement.md's **Ticket:** field (absent/none → no ticket). Branch name: feat/<TICKET>-<slug-description> (ticket present, slug's leading NNN- stripped) or feat/<slug> (no ticket). Resolve a repo for each task's files: path and each task's depends-on: value the same way — walk up to the nearest .git; if a depends-on: value doesn't resolve to a .git (not a real local path), skip that row rather than guessing. external-contract: never participates in this derivation — it names a doc in this same repo, not an external service repo. Write one row per repo to plan.md's Repo Branch Plan table: primary if it owns a task via files:, dependency-only if it's only ever reached via depends-on:. A single-repo result → N/A: single-repo feature. Derivation only — no branch is created here (/do-execute-plan's job, lazily, per repo).
  7. Self-review, then validate — reread the plan against itself and fix it inline: every requirement id and [US#] story is traced to a task or a §7 row, no TBD/TODO/"later" placeholder is left, and no task is coarser than --depth sets (split one that is). plan-check scans the first two and prints each one as a findings entry with its path:line. Fix every entry, then run the advisory consistency check and surface its findings verbatim:
    "$DOFLOW" plan-check "<plan path>" --json
    "$DOFLOW" validate "<plan path>"
    
    This also verifies each ### Task Summary rollup row against the - [ ] lines under its ### Phase <X> heading. Surface findings verbatim; a non-zero exit is advisory and does not halt the chain.
  8. Batch this stage's evidence — one pass here at the stage boundary, never one call per fact. <task id> is the unit these stores key on: the plan task id for anything scoped to a single - [ ] task, otherwise the feature slug. Use the same id for every evidence, claim and readiness call that concerns it — a different id reads a different task's record.
    "$DOFLOW" evidence --task-id "<task id>" --action add --batch <batch>.json --json
    "$DOFLOW" claim --task-id "<task id>" --action add --statement "<one conclusion>"
    

Item schema, provenance rules, and the refused-field list: the guidance tree's references/EVIDENCE_LEDGER.md. Read it before writing the batch. This stage's items are §3 "Research & Decisions" of the plan.md you just wrote: per decision, what was found, where it came from, and its locator. Add each §3 decision as a claim in the same pass: by D#, or, with a register, new planning decisions by statement (their DEC-### IDs are written back at the handoff step). 11. Record the handoff — read the guidance tree's references/WORKFLOW_HANDOFF.md. Use the feature slug as <task id>; if no feature is active, this is standalone and there is no workflow handoff. After completing this skill's work:

"$DOFLOW" orchestrate --action handoff --task-id "<task id>" --calling-skill do-plan --task-class "<validated class>" --note "<work completed and verification result>" --json

The runtime selects this skill's stage, records completion or a rerun annotation, and returns disposition. Report deferred with its reason; resolve no gate in this skill. standalone means no run was created. Render the trail after a recorded handoff:

"$DOFLOW" render-audit --slug="<task id>" --json

Leave any returned approval gate for /do-flow or /do-execute-plan to present (unattended: the loop decides it by policy).

  1. Stop — report the plan path, Constitution Check result, the task count ([P]/sequential), and the derived branch name/repo count when the Repo Branch Plan is populated.

Planning Efficiency Invariants

  • Identify concurrent versus sequential operations across disjoint write sets.
  • Map explicit dependencies between tasks; batch tool calls; maximize parallel execution gains.

Embedded feature research

For an external fact gap or request, follow the Gap or request protocol in ../do-document/references/embedded-research.md before stage completion.

Boundaries

Will: propose a task class and have the runtime validate it, read requirement + design + specs (when has_specs) + constitution, cite specs.md's IC-### contracts in §5, write plan.md including its embedded task checklist and Repo Branch Plan, run the Constitution Check, resolve clarifications, batch the stage's evidence and claims at the boundary, and record the stage handoff through orchestrate/render-audit. Will Not: write design.md or specs.md (that's /do-design) — it cites their contracts, it does not author or amend them — write code, execute the plan, decide the approval gate its own handoff opens, create any git branch (derivation only), plan under a class the runtime rejected or replaced with feature, call readiness for a stage that declares no template; or express evidence, an estimate or readiness as a number, a percentage or a confidence.

CRITICAL BOUNDARIES

STOP AFTER PLAN CREATION. Output: agent-docs/doflow/<slug>/plan.md (HOW + tasks).

Next Step: /do-execute-plan to execute the tasks. The implement phase is gated: it requires requirement.md, design.md, and plan.md to all exist.

04 同仓库更多 Skills

khoavu882
khoavu882/do-flow

beta

暂无简介

★ 0
khoavu882
khoavu882/do-flow

alpha

暂无简介

★ 0
khoavu882
khoavu882/do-flow

do

DoFlow universal dispatcher and the entry point for a plain code-change request: it classifies the task, routes it to the matching /do-* workflow and applies that workflow's gates. Use whenever the user asks to add, fix, change or build something in code without naming a /do-* skill, a request bundles several unrelated asks, or needs a tool recommendation or effort estimate first (e.g., 'add a retry to the upload client in src/upload.js', 'give me a rough estimate for this change', 'first do X, then document Y'). Skip it for questions about how existing code behaves, explanations, reviews, and work already inside a /do-* skill.

★ 0
khoavu882
khoavu882/do-flow

do-test

Execute project builds, automated test suites, and coverage verification with intelligent error reporting across whatever toolchain the repo already uses. Use whenever the user wants to run existing tests, execute test suites, verify builds, check test coverage, or check compile status (e.g., 'run the tests', 'execute test suite', 'check coverage', 'verify build', 'does this still build'). Always activate this skill when verifying test suites or running builds without writing new application code.

★ 0
khoavu882
khoavu882/do-flow

do-implement

Direct, standalone code implementation from a description, /do-code-review findings, or an existing task — no DoFlow chain artifacts required. Use when the user names /do-implement, says 'now implement that', 'fix what the review found' or 'address these comments', or /do routed a bug, refactor, dependency change or small edit here. A plain change request that names no /do-* skill goes to /do first, which classifies it and routes it back here when it fits. Skip it for questions, reviews, and new features that need the full chain.

★ 0
khoavu882
khoavu882/do-flow

do-git

Git operations with lifecycle-aware intents and safety checks — start, save, sync, ship, release, hotfix, backport, and status, plus raw git passthrough for anything else. Use whenever the user requests git actions, branch management, committing changes, syncing with remotes, or release rituals (e.g., 'commit these files', 'ship this feature', 'create a feature branch', 'cut a hotfix', 'sync repo', 'what is git status'). Always activate this skill for safe, confirmed git operations rather than running bare mutating git commands.

★ 0