dvy1987/agent-loom / .agents/skills/structured-planning
structured-planning
VerifiedDecompose 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
| Signal | Route |
|---|---|
| Single tool call / one file / clear outcome | Skip plan — execute directly |
| Multi-step, failure-prone, or user asked to plan | Continue |
Step 2 — Draft full plan
- Assign
task_idslug and stable step ids. - Fill all fields per PLAN-SCHEMA.
- Write file; run
plan_lint.py.
Step 3 — Execute one step
- Mark step
in-progress. - Run the action; capture actual observation in
evidence:. - Mark
doneorfailed.
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
| Excuse | Reality |
|---|---|
| "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]
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: 118k | 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: 117k | 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 |