Skip to content

MVPavan/via / .claude/skills/planning

planning

Verified

Use when settled work needs a durable implementation plan, dependency graph, or workstream decomposition. Skip planning ceremonies for clear bounded tasks.

FileKindSize
SKILL.mdskill md3.3 KB
agents/openai.yamlconfig42 B
references/decompose.mdmarkdown4.9 KB
references/plan-format.mdmarkdown3.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.
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall