plan-tasks
Use when a design is approved and the tasks.md implementation plan (vertical-slice tasks with requirement footers and behavior tests) needs writing, after design-solution and before the execute family (build (wave mode) / build (story mode) / build (inline mode)).
How do I install this agent skill?
npx skills add https://github.com/jayden-dang/skills --skill plan-tasksIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a workflow tool for creating implementation plans. It follows a rigorous multi-step process including requirements mapping, file structure planning, and vertical-slice task generation. It incorporates strong safety measures such as independent subagent review and mandatory human approval before transition to execution. No malicious patterns or security vulnerabilities were detected.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Produce docs/specs/<YYYY-MM-DD>-<feature>/tasks.md from the approved
requirements and design, from the skill set's templates/tasks.md (first path
that exists: templates/ beside this SKILL.md, ${CLAUDE_PLUGIN_ROOT}/templates,
else ../../../templates). Every task-block slot (Files, Interfaces,
Depends-on, Steps, _Requirements:_) is REQUIRED — no per-task risk
labels, decision-surface flags, or Human-review-order (see Step 3's gate table
for why). Write for a skilled implementer with NO context on this codebase,
seeing ONLY their task plus Global Constraints: names, paths, types,
commands they must not guess go in Files / Interfaces / Reuse / footer,
never as prose inside Steps (see Thin steps). Create a todo per step (1–4,
plus 5 if there's a tracker) — this skill's own list, separate from
design-solution's and the execute family's — checked off only when its
Done when: is met.
Step 1: Header and Global Constraints
Goal (one sentence), Architecture (2–3 sentences), Tech Stack, and
Execution-mode: <unset|continuous|story-unit> (leave unset; never invent
it from size/band/habit — mode write-back happens only at Exit). Then
Global Constraints: project-wide rules at a canonical source path + hash,
referenced (not copied) by every task. ## Team with a roster/band override →
derive band + packaging from it alone (Solo: no fake multi-assignee theater;
Small/Multi: optional freeform notes, never a new required field); no Team →
pre-feature default. docs/architecture/ spine, if any → fold its hard
**ARCH-N** invariants in too, so every task inherits them. Resolve the
source below — first hit is SSOT; never invent a parallel one:
| Order | Source | Covers |
|---|---|---|
| 1 | docs/standards/, when it exists (INDEX.md + domain files like testing.md, errors-logging.md) | naming, i18n, house rules, testing, errors/logging |
| 2, then 3 | Else docs/product/guidelines.md (legacy fallback only, and only if it has a parallel rule body — not pointer-only) when docs/standards/ is absent; else docs/agents/project.md | test/lint/typecheck commands, naming/i18n rules, forbidden changes |
Done when: Goal, Architecture, Tech Stack, Execution-mode: (typically
unset), and Global Constraints source path/hash are written, with the
constraint source identified and no parallel SSOT invented.
Step 2: File structure and retrieval
Map every file the plan creates or modifies, with one-line responsibilities, BEFORE writing tasks. A file not in the map should not be touched by any task.
System docs consult during File Structure (optional)
WHEN this step writes or revises File Structure / path placement, read
system-docs-consult.md beside this file and follow it exactly — it resolves
codebase/standards authority, conflict handling, and the no-op path when those
docs are absent or non-authoritative.
Once the map is complete and before writing task bodies (Step 3), run
retrieval once: REQUIRED SUB-SKILL: use load-subgraph for blast_radius
on the mapped paths, then for cluster(feature CODE) as sole focus. Hold
the package while authoring Files/Reuse; for grounded claims (one home)
follow skills/execution/load-subgraph/references/grounded-claims.md —
empty/thin isn't a gate, but state coverage before absence claims.
Done when: every file to create/modify is mapped with a one-line responsibility, and blast_radius/cluster(feature CODE) ran once (or no-op if specs/seeds are missing).
Step 3: Tasks as vertical slices
Contract: a task is a vertical slice — the smallest unit with its own test
cycle and review verdict; split only where a reviewer could reject one task
while approving its neighbor. Shape: one demoable end-to-end outcome per
task per user story; prefactoring that only enables a later slice is its own
earlier task ("make the change easy, then make the easy change") via
Depends-on edges — never buried horizontal layers inside a story task.
Each task carries these slots:
| Slot | Rule |
|---|---|
| Files, Reuse, Interfaces, Depends-on | Files: Create / Modify / Test, each path hardened in backticks (e.g. `src/foo/bar.ts`); never glue a line number/range into the path token (path:86-103 is forbidden) — ranges go in surrounding prose or a separate annotation (new plans only; P1 ownership extraction still accepts legacy glued forms in already-written tasks.md). Reuse: the concrete existing code/library/pattern this task builds on, copied verbatim from the design section's Reuse: line — same <rung> — <concrete target> grammar (e.g. Reuse: existing — src/util/dates:parseISO (rung 2)); copy, don't reinterpret — Step 4 checks it against the design's line. Interfaces: Consumes / Produces — the names and types neighboring tasks share, so an isolated implementer learns what to call things. Depends-on: the earlier tasks this one truly needs — those whose interface it Consumes or whose files it builds on — as Depends-on: Task 2, Task 4, or Depends-on: none. Parallelism signal: two tasks sharing no files and no interface declare no edge, so the continuous build (wave mode) scheduler may place them in one ready set when surfaces are disjoint and worktree isolation is safe; omitting the line falls back to depending on every prior task (safe but fully serial) — over-declaring needlessly serializes, under-declaring is caught by the executor's file-disjoint check before it can collide. Governs build waves — never reorder or narrow dependencies solely to tidy review units if that would lie about what the task needs. |
| Steps (thin, 3–8 checkboxes) | Bite-sized checkboxes (2–5 min each, prefer 3–8 per task), TDD cycle: failing test (complete code describing behavior, not embedding requirement IDs in application/test source) → run, expect the stated failure → implement (complete code) → run, expect pass → commit with a conventional subject explaining the change (no Implements: / Guards: trailer required or taught). No novel-length essays here — that bloats review surface; long how-to narration for one worker goes in the execute brief (.skills/<CODE>/task-N-brief.md) at execute time, while the shared plan keeps identifiers (paths, type names, commands) in Files / Interfaces / Reuse so the brief cannot invent APIs. |
| Footer | `_Requirements: CODE-N.M, CODE-N.M_` — the IDs this task implements or guards; every task has one. Default: one story's IDs (same story number N); multi-story footers merge those stories into one review unit under build (story mode) (plan-quality signal — not a ban, not a reason to lie about Depends-on). IDs live in this footer (and in requirements/design), not in production source or test titles. No placeholders anywhere in a slot — "TBD", "add appropriate error handling", "similar to Task 3", or a type referenced but defined in no task — each is a plan bug; fix it before the plan ships. |
| Thought | Reality |
|---|---|
| "Prefactor first is always right — make the change easy" | Prefactor via Depends-on is fine; review units still follow story citations at build (story mode) |
| "I'll add Risk: high so reviewers notice" | No such field. Risk globs on the actual diff replace agent labels |
| "I'll write Human review order so the human knows what to read first" | Superseded: story-derived units are the review order; an authored second list dies without a consumer |
Done when: every file in Step 2's map is covered by ≥1 task, each written as a vertical slice with its own test cycle — slot/placeholder cleanliness is Step 4's check, not this one.
One triad, one plan
Home for this rule — Step 4 and Exit only point here.
Write every vertical slice of the approved design and requirements into this
tasks.md. One feature triad is one plan. frame-change / plan-milestones
own independent subsystems or a new feature shape, not leftover slices
of this triad. Cut scope only when the user strikes requirements. Merge only
when the result stays a vertical slice (Step 3).
| Thought | Reality |
|---|---|
| "28 tasks — decompose leftover onto a later ROAD so this can Approve" | Leftover slices of this triad stay in this file. That split fragments the feature. |
| "I'll merge layers into one mega-task so the file looks smaller" | Horizontal hiding is still a Step 3 plan bug. |
Step 4: Coverage and consistency check
| Check | Rule |
|---|---|
| Coverage: audit-trace, behavior steps, seam-table | REQUIRED SUB-SKILL: use audit-trace — every Approved requirement cited by ≥1 task footer (uncited IDs mean incomplete, or strike with a reason); docs-only, no IDs in test source. Each footer ID needs a covering TDD step (or manual/acceptance step) asserting behavior in domain language — never [CODE-N.M], /// REQ:, or @CODE-N.M in test source; map IDs to tests in the task report / Spec review, not production trees. Covering is not one test per ID: IDs whose behavior has the same shape at the same seam (a rule applied to several inputs, several defaults) share one table-driven test with a row per ID, and the footer still cites every ID. If design.md has a "Seams for testing" table, every ID in every row needs a planned test/acceptance step at that seam — an ID promised but left uncovered is dropped coverage: add the step, don't renumber. |
| Type/name + Reuse consistency + reuse-miss | The same function must have the same name and signature in every task that mentions it. Flag any task whose Reuse: line disagrees with the design section's Reuse: line. Also flag any task whose Files Create something the scan digest or an already-installed dependency already provides — build on it instead (task-granularity sibling of inspect-change's reuse-miss; advisory, not a hard block). |
| Spec alignment + upstream sync-back | Re-read requirements.md once, checking each criterion against the task that claims it. If a requirement proves wrong or infeasible as written — not merely uncovered — correct it in requirements.md and re-surface for approval; do not bury a workaround in a task that leaves the requirement lying — a plan that satisfies a false requirement ships the falsehood. |
| Independent plan review (dispatch, don't self-review) | The checks above are doc-only and stay here; the codebase comparison does not. Dispatch a review subagent with the plan, requirements.md, design.md, and the repo; have it prove-claim against real code every symbol, signature, path, import, and hardcoded test value the plan asserts — a fabricated golden or a guessed API is the classic plan defect — citing file:line and defaulting to flag. Findings to .skills/<CODE>/plan-review.md; fix before offering execution (no subagents? do the comparison yourself). Check One triad, one plan (one home). |
Done when: every requirement ID has a task footer and a planned behavior test at an agreed seam; audit-trace, the seam-table reconcile, and the placeholder scan are clean.
Step 5 (optional): Publish to the issue tracker
If the repo has no tracker (docs/agents/issue-tracker.md absent, or
Tracker: empty / none) → skip this step (not pending). Otherwise, read
publish-recipe.md beside this file and follow it exactly: resolve Publish
unit, author the issue body, and record ids under .skills/<CODE>/. Default
and only tracker-visible unit: one feature issue per plan, closed by the
feature PR.
| Thought | Reality |
|---|---|
| "Four tasks → four issues so agents can grab in parallel" | Waves read tasks.md + Depends-on. Tracker noise is not parallelism |
| "Sub-issues keep hierarchy without noise" | Under unit feature, tasks are not tracker tickets |
| "I'll publish tasks; the user can close extras" | Extras are the defect under unit feature |
| "Many tasks — config must mean tasks" | Size never sets Publish unit; only the file line or explicit user order |
Red Flags — Step 5
- Under unit
feature: more than one triad issue, or any issue titled like a plan task (Task N:) - Setting or assuming
Publish unit: tasksfrom plan size alone - Falling back to task issues after a permission error
Done when: skipped (no tracker / cannot publish), or unit feature with
exactly one feature issue (union IDs, plan path, id under .skills/<CODE>/),
or unit tasks with one issue per plan task and ids recorded.
Change map — when the operator asks to see it
WHEN the operator asks to see what the plan changes — a picture, diagram, map — the
presentation includes a change map. REQUIRED SUB-SKILL: use craft-page, figure job
before/after structure; write .skills/<CODE>/change-map.html and give its path. Four
baseline runs asked for a picture: one drew none, three drew the feature's own call chain
in ASCII, and none showed that REFUND's Task 4 rewrites the same invoiceView — one drew
the merged signature invoiceView(invoice, refunds, today) that neither plan holds.
The files are every path in the plan's **Files:** lines, docs included — one early
haiku map dropped the docs/api.md its plan modifies, and its owner with it. Run
grep -ln '<path>' docs/specs/*/tasks.md for each. The page shows:
- Each of those files, marked new or changed, with its owner from
docs/agents/project.mdOwnership notes. - The calls and imports the plan adds or changes between them.
- Each external consumer of a changed surface (the design's
Surface:lines). - On the figure itself: each other plan the grep names whose
requirements.mdis notShipped, as a collision on that file, with the signature or change as each plan writes it.
A picture drawn inline in the reply is not the map, even when it "covers the same ground": the three baseline pictures were inline, and the collision was on none of them.
Done when: the page exists with all four, and every collision is on the figure.
Exit
| Step | Rule |
|---|---|
| 1–2. Present | Present the FILE and STOP — conversational agreement is not approval; the written plan is what gets approved, and the execute family runs only on an approved tasks.md. Follow One triad, one plan (one home). |
| 3. On approval | Set Status: Approved. Leave Execution-mode: as unset (or untouched); do not write continuous or story-unit yourself. |
| 4. Offer three routes | Exactly three, one question — do not first ask continuous vs story-unit (that interview is dead); mode write-back owned by the picked skill. build (story mode): subagent path, human-gated review units derived from stories (writes story-unit). build (wave mode): subagent waves, no human pause between tasks (writes continuous). build (inline mode): controller implements sequentially with test-first, no implementer subagents (writes continuous as bookkeeping; does not run unit barriers). Recommend (label only, not invent mode): mark build (story mode) (Recommended) first WHEN user-facing UI/UX, Team Solo/Small, or requirements.md has ≥2 behavioral stories — still offer all three, still wait for the pick; no triggers → leave unmarked (not invent mode, not a size default — see gate table below). |
| 5–6. On pick, INDEX | Name the skill and hand off — REQUIRED SUB-SKILL: use build (wave mode), build (story mode), or build (inline mode) as chosen (for the two subagent routes, prefer REQUIRED SUB-SKILL: use isolate-workspace first when none exists yet). Then confirm the feature's row in docs/specs/INDEX.md carries the same Status: as its requirements.md. |
| Thought | Reality |
|---|---|
| "PM said just mark Approved — continuous is obvious" | Offer the three modes. Do not invent mode. |
| "I'll ask continuous vs story-unit, then offer routes" | One question: which of the three modes. |
| "I'll write Execution-mode now so the plan looks complete" | Mode is written by the execute skill. |
Red Flags — Exit
- Asking continuous vs story-unit before the three-mode offer
- Setting
Status: Approvedwhile inventingExecution-mode: - Splitting leftover slices of this triad onto a new ROAD because of task count
- Offering only one route, or treating "LGTM, build it" as
build(wave mode) - Omitting
(Recommended)onbuild(story mode) when the Recommend predicate holds
Done when: One triad, one plan holds, Status: Approved,
one of build's three modes named (and handed off on pick),
Execution-mode: not invented here, and the INDEX.md row agrees.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/jayden-dang/skills/plan-tasks">View plan-tasks on skillZs</a>