tasks
Generate a frozen task list from a frozen PRD using the spec union in one pass. Use when PRD is frozen and implementation tasks are needed before /sw-freeze. No mid-pass user gates; does not implement.
- License 许可
- MIT
- 最近更新
- 2026-11-03
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- tasks
- description
- Generate a frozen task list from a frozen PRD using the spec union in one pass. Use when PRD is frozen and implementation tasks are needed before /sw-freeze. No mid-pass user gates; does not implement.
03 SKILL.md 正文
Task list generation (/sw-tasks)
Port of v1 spec-tasks under sw-. Reads U8 union so amended requirements are reflected.
Model tier: deep — resolve via python3 scripts/sw_bootstrap.py resolve-model-tier.py -- --skill tasks. When using the Task tool for subagent dispatch, resolve concrete model IDs from models.tiers in config (never semantic tier names in subagent model: frontmatter).
Issue-store authoring (PRD 056 R11–R12)
When effective backend is issue-store:
-
Never write task lists under
docs/prds/in the code repo. -
Persist via
planning_store.putwith unit idtasks-<n>-<slug>and virtual body-pathdocs/prds/<n>-<slug>/tasks-<n>-<slug>.md. -
Run gates on handles (materialize is deliver-time only):
python3 scripts/spec-rigor-check.py --root <consumer-repo> --artifact tasks --path <body-path> --unit-id <tasks-unit-id> --prd <prd-body-path> --prd-unit-id <prd-unit-id> python3 scripts/traceability-check.py --prd <prd-body-path> --tasks <body-path> [--prd-unit-id …] [--tasks-unit-id …] -
INDEX registration is mechanical reconcile / living-docs — not a local
docs/prds/INDEX.mdwrite.
File-store repos: unchanged — path and file save below apply.
DecisionGraph scope (PRD 280 R15)
When task generation covers PRDs with an attached DecisionGraph:
- Include a
## DecisionGraph scopesubsection under each affected parent phase when decision nodes gate implementation. - Reference the linked graph by unit id + virtual
docs/planning/decision/<unit-id>/decision-graph.json— never assume a code-repo JSON file exists under issue-store. - Phase dependency edges may reference decision-frontier readiness; cite
python3 scripts/planning-graph.py decision-frontier --unit-id <prd-unit-id>for read-only ready-set discovery.
Path
docs/prds/<n>-<slug>/tasks-<n>-<slug>.md per .shipwright/layout.md.
Procedure
- Require frozen PRD as input.
- Load effective spec via
scripts/spec-union.pyorskills/spec-union/SKILL.md. - In one pass, identify parent tasks (phases) and expand each into
- [ ]sub-tasks with executable shape (IM6):- Parent tasks: numbered, dependency-ordered,
small|medium|largesizing from the deterministic heuristic (### N.headings; see Phase sizing heuristic below). - Sub-tasks: File, Expected, R-IDs as below.
- Relevant Files + Notes as needed.
- Prefer many small phases with explicit
## Phase Dependenciesedges over few large sequential phases (R19).
- Parent tasks: numbered, dependency-ordered,
- Emit
## Phase Dependencies(required) — machine-parseable edge source for/sw-deliverphase-mode (R5/R6/R37). Place after## Tasksand before## Traceability. - Run execute-tier granularity pass (see Execute-tier granularity below).
- Add
## Traceabilitytable mapping each union R-ID → task ref → named test scenario → ZOMBIES checklist (test-list-first; seeskills/spec-rigor/references/zombies.md). - Save task file; run
spec-rigor-check.py --root <consumer-repo>(tasks) +traceability-check.py; freeze via/sw-freeze. Installed spec-rigor requires consumer--root. Requirement bullets and task R-ID cites parse hyphen and asterisk RID markers (- **R1**/* **R1**); Linear*lists must extract on the stored body. - Register/refresh PRD entry in
docs/prds/INDEX.mdwith statusnot-started. - Stop — do not start implementation. Standalone
/sw-tasksends after freeze;doc.afterTaskson/sw-docowns the boundary to implementation.
Phase Dependencies table (required)
Every generated task list MUST include a ## Phase Dependencies section with this table shape (parsed by
scripts/wave_deliver.py in /sw-deliver phase-mode):
## Phase Dependencies
| Phase | Depends on |
|-------|------------|
| 1 | none |
| 2 | 1 |
| 3 | 1 |
| 4 | 2, 3 |
Rules:
- One row per phase (
### N.parent in## Tasks). Phase column is the integerNonly. - Depends on is
none, a single phase number, or comma-separated phase numbers (e.g.2, 5). - Edges are authoritative for
/sw-deliverwave planning — derive from the dependency order of parent phases. - Human-reviewable; lives inside the task-list artifact (no sidecar file).
Deliver-time fallback (PRD 013 — legacy lists only)
Sequential fallback (R8): when neither declared edges nor file-set inference apply, deliver assigns strict sequential edges with a notice.
/sw-tasks requires ## Phase Dependencies at freeze (spec-rigor-check.py blocks missing/invalid tables).
For legacy frozen lists that omit the table, /sw-deliver applies the PRD 013 ladder (authoritative in
skills/deliver/SKILL.md):
- Declared — explicit
## Phase Dependenciesrows (always preferred at authoring time). - File-set inference — overlapping
**File:**paths infer serializing edges before wave assignment. - Sequential + notice — strict
1→2→3…edges with a missing-edges notice when inference finds no overlap.
Authors MUST emit explicit edges for new task lists — never rely on deliver-time fallback for multi-phase PRDs.
Phase sizing heuristic (PRD 040)
Replace informal S/M/L labels with the deterministic scorer:
python3 scripts/phase_sizing.py score docs/prds/<n>-<slug>/tasks-<n>-<slug>.md
python3 scripts/phase_sizing.py advisory docs/prds/<n>-<slug>/tasks-<n>-<slug>.md # draft-only block
Per phase the scorer emits size: small|medium|large from structural signals (filesTouched,
traceabilityScenarios, depFanOut, subTaskCount, distinctDirs) against tasks.sizing.thresholds in
config. Thresholds and bounds (minPhaseFiles, minPhaseScenarios, maxPhaseCount) are documented in
core/sw-reference/phase-sizing.schema.json.
Small-phase design constraint (R18)
Small phases are a design constraint for reviewability and wave parallelism (Osmani on bounded change sets;
Faros reports on agent PR size). Each phase SHOULD stay small or medium where practical. Splitting below the
minimum-viable-phase floor (belowFloor: true) is not rewarded — avoid granularity DoS (many tiny phases
inflating merge-gate load).
Prefer-many-small + split suggestions (R19)
- Prefer many small phases with declared dependency edges over one large sequential phase.
- When
overThreshold: trueorseparableSetshas multiple components, review the advisory split suggestion (draft-only; stripped at freeze). Each proposed edge MUST respect contention families documented inskills/parallelism/SKILL.md(shared migrations, living INDEX/numbering,CHANGELOG/version.txt,**File:**overlap, generator-output / golden-manifest globs). - Adopting a split requires an unfrozen
/sw-tasksre-run +/sw-freeze— never edit a frozen task list in place.
Executable sub-task shape
- [ ] 1.1 Add tdd-gate script (R1)
- **File:** `scripts/tdd-gate.py`
- **Expected:** JSON verdict on stdout; exit 0 pass, 20 fail
- **R-IDs:** R1
Parent phase items (1., 2.) may remain summary-level; numbered sub-tasks (1.1, 1.2) carry File +
Expected for /sw-execute plan-self-review.
Wiring proof (Wired: / Callsite:) (PRD 085 R15)
When a sub-task's Expected introduces a new production-reachable entry point in one of these bounded
categories, the row MUST declare a Wired: (or alias Callsite:) field naming the calling
module or file that dispatches to / registers the produced artifact:
| Category | Example Expected signal |
|---|---|
Script main() dispatch branch |
"new script's main() dispatch branch" |
| CLI subcommand | "adds a new CLI subcommand" |
| Hook registration | "new hook registration" |
| Backend / adapter registration | "backend/adapter registration function" |
| Workflow file | "new workflow (.github/workflows/*.yml) file" |
- [ ] 3.2 Register the foo backend (R4)
- **File:** `scripts/credentials/backends/foo.py`
- **Expected:** adds a new backend/adapter registration function
- **Wired:** `scripts/credentials/resolver.py`
- **R-IDs:** R4
tasks_generate.py check enforces the field for rows matching these categories (not a general "every
artifact must declare a caller" rule). claims_audit.py brief performs a bounded static reachability check
that the cited callsite file references the produced artifact in the branch diff (R16).
Execute-tier granularity (PRD 055 R16–R20)
Every generated task list MUST include bounded intra-phase sub-task refs sized for PRD 053 execute-tier
fan-out. This is a first-class generation requirement alongside ## Phase Dependencies and
## Traceability.
Authoring procedure
After drafting sub-tasks and before /sw-freeze:
python3 scripts/tasks_generate.py apply-granularity --task-list docs/prds/<n>-<slug>/tasks-<n>-<slug>.md --inplace
python3 scripts/tasks_generate.py check --task-list docs/prds/<n>-<slug>/tasks-<n>-<slug>.md
apply-granularity decomposes list-shaped **File:** fields (comma/and-separated paths, glob lists)
into one ref per bounded file-set when contention rules permit parallelism. It emits a durable
## Execute-tier granularity section with split preflight JSON — part of the frozen artifact, not
the advisory-only ## Sizing & Split Suggestions block stripped at freeze.
Re-numbering: when a ref splits (e.g. 3.1 → three units), refs within the phase are renumbered in order
(3.1, 3.2, 3.3, …) preserving phase-local sequence.
Contention and serial edges
When phase_sizing.separable_sets_for_paths() groups paths into one contention family, parallelism is
forbidden — apply-granularity documents serial edges in the ## Execute-tier granularity JSON rather
than emitting parallel refs.
Runtime escape hatch (R20)
Already frozen coarse lists are never mutated. execute_plan.py runtime expansion remains the
sanctioned fallback for in-flight deliver runs until the task list can be re-generated.
Blocking sizing freeze gate (PRD 065 R16)
At /sw-freeze, spec-rigor-check.py runs the blocking sizing gate (phase_sizing.py evaluate_freeze_gate`):
- Over-threshold phases block freeze with split suggestions (same scorer as
phase_sizing.py score). - Advisory
## Sizing & Split Suggestionsblocks are stripped before freeze — they do not satisfy the gate. - Human override only — durable record at
.cursor/sw-sizing-overrides/<key>.jsonwithactor,reason, andoverThresholdPhases. Agents on autonomous/sw-doc→/sw-tasksdispatch cannot author overrides (refuse_autonomous_override). - Deliver-time sizing report (
/sw-deliver --sizing-report) is read-only visibility — it does not bypass the freeze gate.
Collision policy
- First run: create the complete task file (parents, sub-tasks, phase dependencies, traceability) in one pass.
- Resume (unfrozen draft): continue in the same file; do not duplicate sections.
- Re-run against frozen task list: require explicit confirmation before full overwrite.
- No sub-task-expansion gate — the human checkpoint between doc and implementation is
doc.afterTasks(orchestrator boundary), not/sw-tasks.
Handoff
→ implementation workstream (/sw-execute when available) only after the doc orchestrator boundary (doc.afterTasks).
04 同仓库更多 Skills
wrong-name
Missing use when phrase and wrong directory name for critical lint failure.
demo-skill
Demo workflow pack skill fixture. Use when validating workflow-pack-sdk golden paths in CI.
good-skill
Validates Agent Skills spec conformance for fixture trees. Use when testing skills-spec-guard pass paths across core and dist mirrors. Does not ship production skills.
wrong-name
Fixture with name/dir mismatch for guard failure tests. Use when verifying skills-spec-guard rejects invalid identity. Does not ship production skills.
bad-description
Missing the required when trigger phrase in this fixture skill.
dropin-demo
暂无简介