Workflow Execution

Plan-first workflow for non-trivial work: plan with done criteria, create a tracking issue, package context as documents on the issue, decide where code lives, hand off to an executing agent, verify completion. Use when tasks involve 3+ steps, architecture/strategy decisions, risky edits, or iterative bug-fixing.

Run this workflow for any meaningful work. The core loop: plan → track → package context → route → hand off → execute → verify.

Core Principles

• Plan before acting. The plan lives on the tracking issue, not in chat.
• Package context as documents, not spawn strings. The executing agent should never depend on chat history.
• Decide where code lives before writing any code.
• Prefer the simplest approach that can pass verification.
• Be explicit about proof, not optimism.

---

Phase 1: Plan

Enter planning before acting when any trigger is true:

• Work requires 3 or more concrete steps
• Work changes architecture, interfaces, data flow, or shared contracts
• Work includes risky edits (security, auth, migrations, destructive operations, production config, or unknown blast radius)
• Work will be handed off to another agent or subagent

Plan contents

1. Goal — one sentence describing what done looks like.
2. Done criteria — explicit, checkable conditions. Not "it works" but "tests pass, PR merged, deployed."
3. Constraints — what must not break, budget limits, timeline, dependencies.
4. Failure modes — what could go wrong and how you'll detect it.
5. Ordered steps — small, each with a verification method (test, build, smoke check, log proof, diff).

---

Phase 2: Track

Before implementation starts, create or reference a tracking issue in your project management system.

What to do

1. Create an issue with a clear title and the goal from Phase 1.
2. Attach the plan as a document on the issue (key: plan). This is the source of truth — not a chat message, not a comment, a structured document.
3. Link to parent issues if this work is part of a larger effort.

Why documents, not descriptions

• Documents are revisioned — you can see how the plan evolved.
• Documents are keyed — plan, design, context each have a clear role.
• Documents are agent-readable — any agent that picks up the issue gets the full context.
• Documents survive context resets — when a session compacts or a new agent spawns, the context lives on the issue, not in memory.

Tracker reference implementations

This skill is tracker-agnostic. See references/ for how to do this with specific systems:

• references/tracker-paperclip.md — Paperclip Issues + Documents API
• references/tracker-github.md — GitHub Issues + issue body/comments
• references/tracker-none.md — skip tracking, plan in a local file

---

Phase 3: Package Context

Before handing off to an executing agent, attach structured documents to the tracking issue:

Required: plan document

The plan from Phase 1. Always attached.

When applicable: design document

Attach when work involves:

• New interfaces or API contracts
• Architecture decisions with tradeoffs
• User-facing UI/UX (include design brief: user flow, empty/loading/error states, copy, responsive behavior, accessibility)

When applicable: context document

Attach when the executing agent needs background that isn't obvious from the code:

• Prior decisions and their rationale
• Relevant code references (files, functions, patterns to follow)
• Domain knowledge the agent won't have
• Links to related issues or discussions

Packaging principle

Ask: "If a brand new agent picked up this issue with zero chat history, could they do the work?" If not, add more context documents.

---

Phase 4: Route

Before execution, decide where the code lives.

Decision criteria

Signal	Destination
Work extends an existing project/repo	Existing repo — branch off main
Work is reusable, publishable, or useful to others	New repo — create it, then work there
Work is pure local glue, config, or one-off automation	Local workspace — but document why it's local

Routing rules

• Default: existing repo. Most work extends something that already exists.
• New repo trigger: If you find yourself thinking "other people could use this" or "this should be a skill/package," it's a new repo.
• Local-only justification required. If code stays in the local workspace, document why — it should be because it's genuinely specific to this setup, not because it was easier.
• Branch naming: Include the tracking issue identifier in the branch name (e.g., SUP-490/skill-rewrite).

---

Phase 5: Hand Off

Spawn the executing agent with an issue reference, not inline context.

Dispatch rule

Code handoffs MUST use sessions_spawn, not sessions_send.

sessions_spawn triggers the full enforcement pipeline (Lobster gate, spawn-code-lint, post-spawn PR creation). sessions_send bypasses all of it. Use sessions_send only for non-code work: status checks, coordination, questions.

The test: if the message asks the target agent to write, edit, or move code → sessions_spawn. Everything else → sessions_send is fine.

Handoff protocol

1. The spawn message includes: the tracking issue identifier, the repo/branch to work in, and any model/thinking preferences.
2. The executing agent's first step is: read the issue, read attached documents (plan, design, context), then proceed.
3. The executing agent updates the issue as it works — comments for progress, status changes for state transitions.

Subagent strategy

• Spawn by default when work spans multiple files/systems, requires research, or includes long-running operations.
• One clear objective per subagent with concrete deliverables.
• Clean ownership boundaries — avoid overlapping edit zones.
• Prefer fewer, well-scoped subagents over many tiny ones.

---

Phase 6: Execute

Minimal-impact changes

• Implement the smallest change set that satisfies the goal.
• Reuse existing patterns before inventing new abstractions.
• Keep naming, structure, and style consistent with local code.
• Avoid incidental cleanup unless it directly reduces risk.

Failure recovery hierarchy

When something goes wrong during execution, follow this priority order:

1. Transient provider failure (429, timeout, model overload): OpenClaw's native model fallback chain handles this automatically. Do not change tracker issue status. Continue in the same session once the request succeeds.

2. Context reset or compaction: Re-read the plan, context, and design documents from the tracking issue. Never reconstruct plan state from in-session memory after compaction — the issue documents are the source of truth.

3. Durable blocker (missing dependency, unclear requirements, architectural gap): Update the tracking issue status to blocked. Add a comment naming the specific blocker and what needs to resolve it.

4. The tracker is an audit trail and coordination hub — not the place to manage transient retries. Do not flip status on transient errors, partial progress, or model fallbacks.

Autonomous bug-fix behavior (guardrailed)

When bugs appear during execution:

1. Reproduce and isolate the failing path.
2. Form the smallest plausible fix hypothesis.
3. Apply minimal-touch patch.
4. Re-run impacted checks and one nearby regression check.
5. Repeat until pass or a guardrail is hit.

Stop and escalate when:

• Root cause remains unclear after multiple attempts.
• Fix requires major architectural change.
• Risk of data loss or security impact is non-trivial.

Demand elegance (balanced)

• Reject hacks that create hidden fragility or repeat incidents.
• Prefer clear structure over clever shortcuts.
• Scale sophistication to task size — don't over-engineer obvious fixes.

---

Phase 7: Verify

Do not mark complete without proof.

Evidence types

• Tests: targeted unit/integration/e2e checks.
• Static checks: lint, typecheck, build.
• Runtime checks: smoke test key affected flows.
• Logs/output: command results or excerpts showing success.
• Diff sanity: verify only intended files changed.

Governance

• Significant code changes: branch + PR + review before merge.
• CI must pass before merge.
• Fix review comments before closing.

Close the loop

1. Update the tracking issue status to done.
2. Add a closing comment with verification evidence.
3. If the work produced a reusable lesson, capture it durably.

---

Self-Correction Loop

If the correction cycle was triggered by a context reset or compaction, re-read the issue's plan, context, and design documents before resuming — do not reconstruct plan state from in-session memory.

After any correction cycle (failed check, rework, rollback):

1. Record what failed and why (brief, concrete).
2. Extract one reusable lesson/pattern.
3. Apply that lesson immediately to remaining work.
4. Capture a durable note when the lesson is broadly reusable.

---

Quick Checklist (Repeat Each Run)

• Plan: goal, done criteria, constraints, failure modes, ordered steps
• Track: issue created/referenced, plan document attached
• Package: context documents attached (design, context as needed)
• Route: code destination decided, branch created with issue ID
• Hand off: agent spawned with issue reference, not inline context
• Execute: minimal-impact implementation
• Verify: evidence collected, checks pass, governance followed
• Close: issue updated, evidence in closing comment, lessons captured