MVPavan/via / .claude/skills/planning
planning
VerifiedUse when settled work needs a durable implementation plan, dependency graph, or workstream decomposition. Skip planning ceremonies for clear bounded tasks.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.3 KB |
| agents/openai.yaml | config | 42 B |
| references/decompose.md | markdown | 4.9 KB |
| references/plan-format.md | markdown | 3.5 KB |
references/decompose.md
View on GitHub# Decompose — workstream mechanics
Consulted from `planning` Decompose mode. Layout, the approval-gate format, and
seeding commands live here; the decision steps live in SKILL.md.
## Workstream layout
New workstream → create `docs/workstreams/<name>/`:
- `README.md` — the charter, one screen: what this workstream is, how it is
tracked.
- `roadmap.md` — the phased plan (the bd `--design` anchor). Per phase: Goal ·
deliverables table `| # | Stage | Create/modify paths | Verify |` · spec
references · `Exit (phase):` line · test focus · risk (standard/deep, defined in
`.claude/skills/execution/SKILL.md` under Scope selector) · for
review phases, which original phases they modify.
- `plans/` — empty; per-phase plans land here just-in-time during execution.
- `tracking/` — empty; bd-generated by the render script, never hand-authored.
Epic titles carry the roadmap's phase identifier as a bracket prefix —
`[<phase-id>] <phase name>`, e.g. `[R1] Intake states` — the join key between
roadmap rows and bd epics. Use whatever identifier scheme the roadmap uses;
keep it consistent within the workstream.
**Flat operational work** (no phases): the `README.md` charter is the anchor.
Seed plain tasks labelled `ws-<name>` — no epics, no roadmap.
## Extending an existing workstream
- Append the new phases to the existing `roadmap.md`, continuing its phase
numbering; do not renumber or rewrite existing phases.
- Reuse the workstream's existing `ws-<name>` label on the new epics.
- New epics may carry a different `--spec-id` than older ones — a workstream
accumulates epics from many specs.
- Add epic→epic edges where a new phase genuinely depends on an old one.
- Re-render the tracking mirrors after seeding.
## Approval gate — what to present
For material structure not already authorized, present before seeding:
- the phase list in execution order, one line each: name · goal · risk
- stage counts per phase
- every dependency edge (epic→epic and stage→stage), each with its reason
- open questions
Use existing approval covering the concrete structure or delegated routine
choices. Clarify only material ambiguity; do not demand a repeated approval phrase.
## Seeding commands
`--actor "<runtime>:<session>"` (Claude Code: `cc:${CLAUDE_CODE_SESSION_ID:0:8}`;
Codex: `codex:<thread>`) on every bd write.
1. **Epic per phase:**
`bd create -t epic "[<phase-id>] <phase>" --spec-id docs/workstreams/<name>/roadmap.md --design docs/specs/<spec>.md -l ws-<name> --actor … -q`
— **`--spec-id` is the workstream anchor: it must be the roadmap.** The
renderer derives the workstream name and the `tracking/` output directory
from `dirname(spec_id)`, so an anchor outside `docs/workstreams/<name>/`
produces no mirrors (the renderer now fails with exit 1 rather than
skipping quietly). `--design` carries the governing spec — the renderer
collects the unique `design` values across a workstream, so several specs
can feed one workstream. Keep every epic in a workstream on the **same**
`spec_id`: the renderer groups by exact match and writes the same
`tracking/` directory once per distinct value, so a split anchor silently
leaves only the last group in the mirror. The `ws-<name>` label remains the
key execution filters on.
The flag names read backwards here: the field called `--spec-id` holds the
roadmap and the field called `--design` holds the spec.
2. **Flat stage children** — one per deliverables row:
`bd create "<stage>" --parent <epic> -t task --acceptance "<the row's Verify cell>" --actor … -q`
→ dotted ids `<epic>.N`. No sub-tasks. Every stage carries acceptance.
3. **Dependencies** — real edges only, `bd dep add <issue> <prereq> --actor …`:
stage→stage where one genuinely needs another's output; epic→epic where a
phase gates another. Never blanket-chain listing order — independent work
stays unchained so it can run in any order or in parallel.
4. **Render:** `BD_RENDER=1 bash <beads-skill-dir>/scripts/bd-render-tracking.sh <name>` —
regenerates the workstream's `tracking/` trio and the board. If the renderer
is missing, skip it, report the gap, and create nothing in `tracking/` by
hand.
## Single-phase exit
For an approved spec that is one phase of work (SKILL.md scope-check): after
the stage-level approval, seed one epic with `--spec-id` and stage children
with acceptance — no roadmap, no workstream directory, no `ws-` label. The
epic's consumer is task-scope execution driven by the Elaborate plan and its
bd stages, not phase execution (which resolves epics through a workstream
label).
## Summary format
Report: workstream path · phases/stages seeded · execution order · risk per
phase · the next command (phase execution for one phase; the autonomous
workstream walk only when the user asks for it).
Conservative git: report the proposed commands; do not commit.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |