AGENT SKILL

workspace-plans

Use this skill when writing, revising, or executing a workspace plan — the plan/README.md + phase-N-<slug>.md format the dashboard ingests. Don't use it for ad-hoc todo lists or in-repo design docs.

License 许可
Apache-2.0
最近更新
2026-11-11
Stars
★ 8
Forks
5

01 前言 Front Matter

docs
{ "status": "draft", "updated": 1792540800000 }
name
workspace-plans
color
cyan
owner
swarmery-core
version
1.2.0
description
Use this skill when writing, revising, or executing a workspace plan — the plan/README.md + phase-N-<slug>.md format the dashboard ingests. Don't use it for ad-hoc todo lists or in-repo design docs.

02 资源文件 3

03 SKILL.md 正文

Purpose

The private workspace plan format is a contract: the control plane parses it to render plan progress, phase summaries, and spec coverage. A plan that deviates from the format ships work the operator cannot see.

The contract (never violate)

  • Plans live at <workspace>/<project>/workspace/working/{YYYY}/{MM}/{DD}/{slug}/plan/; task-id yyyy-mm-dd-slug is derived from the path — never encode the date in the folder name.
  • plan/README.md — an ## In plain words section under the H1, objective, architecture decisions with real file paths, the sequencing table with exactly these header cells: | # | Phase | Doc | Depends on |, risks, Definition of Done.
  • plan/phase-N-<slug>.md per phase (flat; step-NN-*.md is legacy read-compat only) — each opening with an ## In plain words section (after the header rows, before ## Goal), with a self-contained copy-paste executor prompt whose Verify block is file-backed (a repo script or test by absolute path; no heredoc, python3 - or node -e — see resources/plan-format.md), - [ ] acceptance criteria checkable by command or boolean inspection, and an empty ## Completion Report section as the LAST section.
  • A ## Forecast section in each phase doc, immediately before that stub, holding one kind: prior yaml block (see resources/plan-format.md). It is a prediction, not a limit: do whatever the phase actually needs.
  • plan/manifest.json — machine-readable phase DAG (must pass python3 -m json.tool).
  • Optional plan/spec.md with - [ ] **SC-n** — <criterion> lines; then every phase doc carries a **Covers:** SC-… header line (coverage is linted).

Criteria closed by a push, PR or merge start with [LAND] and name no branch (- [ ] [LAND] phase PR merged into main) — the header's **Branch:** is informational and the daemon lands only the run branch swarm/phase-<id>. Criteria only a human can perform (production, a console, a manual check) start with [MANUAL]. Neither is the executor's to tick or perform: the daemon settles a run against the rest, refuses to start a [MANUAL]-only phase and lists it in Needs you, lists a phase with only [LAND] left as awaiting merge, and ticks [LAND] itself when the pull request for the run branch merges — whether landed through the Review tab or opened outside the platform and found by the landing poll or "Find PR". When the PR comes from any other branch, its [LAND] criteria are ticked by hand. The header rows **Verify:** (off | normal | strict), **Review:** (on | off) and the required **Effort:** (low | medium | high | xhigh) sit directly after **Repo:** …; L/XL phases default to normal / on. Details: resources/plan-format.md → "Criterion classes" and "Header rows".

Criteria that lean on the engine follow five rules in resources/plan-format.md: spike a guarantee under every permission mode, live-check engine-boundary phases before [LAND], append live-check evidence immediately, cite resources/config-channels.md for any settings-file criterion, and number migrations at landing.

Resources

  • resources/plan-format.md — the full field-by-field format, examples, the manifest schema, and the engine-facing criterion rules.
  • resources/blast-radius.md — the planner's blast-radius step: who calls what a phase changes, and the Blast radius: line its ## Risks opens with.
  • resources/config-channels.md — which settings tier Claude Code reads for pluginConfigs, plugin env and ${VAR}, with the CLI version measured.
  • templates/spike-matrix.md (plugin root) — the permission mode × surface matrix for a spike.

Executor duties

After reading the code the phase touches and before your first edit, add a kind: posterior block beside the prior in ## Forecast — the prediction-not-a-limit rule above applies unchanged — and if the work then diverges from it, say how and why in a short "Where reality diverged" paragraph of the Completion Report.

Tick each satisfied criterion - [ ] → - [x] immediately after verifying it — progress is derived only from these checkboxes. When a phase's last EXECUTABLE criterion is ticked (every one that is not [LAND]/[MANUAL] — those close later, without an executor), fill that doc's ## Completion Report (what shipped, files/commits, verification output, deviations, plus three mandatory fields — Blocked calls, Delegation cost, and the one-sentence What would have made this cheaper; ≤50 lines) — the dashboard renders exactly that heading. Each of the three is written out even when empty ("none" / "Nothing, it was already minimal"); resources/plan-format.md carries their exact wording and is the source of truth. Never tick unsatisfied criteria; never archive with unmet criteria or a missing SUMMARY.md.

Full field-by-field format, examples, and the manifest schema: resources/plan-format.md.

How to use

What it does

Carries the exact workspace-plan format the dashboard ingests: README sequencing table, phase docs with file-backed-verification executor prompts and checkbox criteria, manifest DAG, optional spec with SC coverage, and the tick/Completion Report duties for executors — including the report's Blocked calls, Delegation cost and "what would have made this cheaper" fields.

When to use it

Load it whenever you write a new plan, revise one, or execute one — any time plan files under a task dir's plan/ are created or updated.

How to invoke

The @core:planner and @core:implementation-agent agents list it in their skills:; load it manually with /workspace-plans context or by reading resources/plan-format.md when editing plan files by hand.

Worked example

A planner writing plan/phase-2-api.md includes: **Covers:** SC-3, a prompt an executor can run cold whose Verify block names scripts/check-api.sh rather than inlining a heredoc, three - [ ] criteria each with a check command, and ends the doc with an empty ## Completion Report section. The executor later ticks the boxes one by one and fills the report — Blocked calls, Delegation cost and the one-sentence cheaper field included — and the dashboard's phase Summary tab shows exactly that section.

04 同仓库更多 Skills