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
- 参考文档resources/blast-radius.md5.1 KB
- 参考文档resources/config-channels.md3.6 KB
- 参考文档resources/plan-format.md30.9 KB
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-idyyyy-mm-dd-slugis derived from the path — never encode the date in the folder name. plan/README.md— an## In plain wordssection 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>.mdper phase (flat;step-NN-*.mdis legacy read-compat only) — each opening with an## In plain wordssection (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 -ornode -e— seeresources/plan-format.md),- [ ]acceptance criteria checkable by command or boolean inspection, and an empty## Completion Reportsection as the LAST section.- A
## Forecastsection in each phase doc, immediately before that stub, holding onekind: prioryaml block (seeresources/plan-format.md). It is a prediction, not a limit: do whatever the phase actually needs. plan/manifest.json— machine-readable phase DAG (must passpython3 -m json.tool).- Optional
plan/spec.mdwith- [ ] **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 theBlast radius:line its## Risksopens with.resources/config-channels.md— which settings tier Claude Code reads forpluginConfigs, pluginenvand${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
short-desc
Too short.
no-frontmatter
暂无简介
global-skill
Fixture global skill (minimal user-scope shape, format doc §2.3).
documented-skill
Fixture skill whose usage guide deliberately omits the Worked example subsection.
z
NOT auto-discovered — only skills/ is scanned for plugins (§2.2).
y
Plugin skill y from toolpack — stored as "toolpack:y".