Skip to content

dvy1987/agent-loom / .agents/skills/structured-planning

structured-planning

Verified

Decompose multi-step work into a revisable subgoal plan with stable step IDs, checkpointing, and plan-ahead execution. Load when a task needs explicit planning before action, subgoal decomposition, plan checkpointing, or ReCAP-style plan-ahead execution. Also triggers on "structured plan", "plan with steps", "subgoal graph", "revise the plan", "checkpoint plan", or multi-step tasks where naive one-shot execution would be fragile. Skips trivial single-step tasks. Pairs with dynamic-routing on failure. Distinct from process-decomposer (registry/triage) and problem-to-plan (doc deliverables).

Structured Planning

You plan before you act: emit a subgoal checklist with stable ids (S1, S1.1), execute one step against ground truth, record observations, refine the remainder. On failure, hand off to dynamic-routing — do not blind-retry.

Hard Rules

Trivial tasks (single step, obvious outcome) → skip formal plan; state "trivial — plan skipped." Non-trivial tasks → write plan to .agent-loom/plans/<task-id>.md per references/PLAN-SCHEMA.md. Generate full plan once; execute only the first pending step per cycle (ReCAP commit-one). Every step records: goal, action, precondition, expected observation, status, evidence. Run scripts/plan_lint.py after each plan write. Append plan changes to Plan delta log with reason — never silent edits.


Workflow

Step 1 — Triage complexity

SignalRoute
Single tool call / one file / clear outcomeSkip plan — execute directly
Multi-step, failure-prone, or user asked to planContinue

Step 2 — Draft full plan

  1. Assign task_id slug and stable step ids.
  2. Fill all fields per PLAN-SCHEMA.
  3. Write file; run plan_lint.py.

Step 3 — Execute one step

  1. Mark step in-progress.
  2. Run the action; capture actual observation in evidence:.
  3. Mark done or failed.

Step 4 — Refine remainder

Before the next step: update preconditions/expected fields for pending steps using new evidence. Log deltas.

Step 5 — On failure

Invoke dynamic-routing with failed step id + evidence. Apply revised plan; lint again.

Step 6 — Complete

All steps done or explicit aborted. Emit final plan path.


Gotchas

  • Executing the whole plan without observation updates recreates one-shot fragility.
  • Reusing step ids after revision breaks trace cross-reference with run-trace.
  • Plans in chat only — not auditable; always persist to .agent-loom/plans/.

Output Format

## Structured plan — [task_id]

Plan file: `.agent-loom/plans/[task_id].md`
Steps: N total | done: N | pending: N | failed: N

Current step: **Sx** — [goal]
Observation: [actual vs expected]

Delta (if any): [step] [from→to] — [reason]

Next: execute **Sy** | invoke dynamic-routing | complete

Examples

Teaser: 4-step API feature → full plan written → S1 done (migration applied) → S2 preconditions updated after observing schema conflict.

Full pairs: references/examples.md


Common Rationalizations

ExcuseReality
"Planning is overhead"Rework from a failed one-shot costs more.
"I'll keep the plan in my head"Not handoff-safe; write the file.
"Execute all steps then fix"Violates commit-one; observations won't flow.
"process-decomposer already planned"That produces process entries; this is runtime execution state.
"problem-to-plan wrote a plan doc"docs/plans/ is spec; this is live execution tracking.

Verification

  • Plan file exists at .agent-loom/plans/<task-id>.md
  • plan_lint.py passes
  • Only one step executed per cycle
  • Delta log updated on revision

Red Flags

  • Multi-step work with no plan file
  • Failed step without delta log entry
  • Blind retry of same action after failure

Prune Log

Last pruned: 2026-07-05

  • Initial release from high-leverage skill spec (Skill 1 family)

Impact Report

Plan: [task_id] | Steps: N/M done | Lint: [pass/fail] | Current: [step id]
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: 118kUpdated 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: 117kUpdated 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