swe-workflow

SWE Workflow

Every code task starts with workflow triage. Bounded work stays lightweight; risky or coordination-heavy implementation uses a persisted plan.

Contract

1. Triage first. Start the first reply to a code-related task with one of these declarations:

   Workflow mode: Lightweight — <reason>; success: <outcome>; plan: no.
   

   Workflow mode: Full
   Reason: <one sentence>
   Success criteria:
   - <what done means>
   Plan needed: yes
   

   If an exact machine-readable contract permits no extra text, follow that contract instead of adding a plain-text triage prefix. Include triage fields only when the schema permits them.
2. Lightweight is the default for clear localized changes, bounded investigation, and read-only reviews or discovery—even when many files must be inspected. It uses the Behavioral Guards but no persisted plan.
3. Full is required before implementation when work is risky or hard to reverse; changes API/schema/migration/security/configuration contracts; couples multiple subsystems; is a broad refactor/migration/cleanup; needs durable multi-session or multi-agent coordination; remains materially ambiguous after bounded discovery; or the user requests a plan. File count alone is a signal, not a trigger.
4. Escalate before target-file edits. Lightweight discovery may gather evidence first. If Full criteria emerge, stop before mutating task files, declare Full mode, clarify decision-critical questions, create the plan, and then resume. If edits already began, preserve the verified state and escalate before expanding scope.
5. Pre-edit gate (Full mode). Before mutating task target files: a plan directory must exist under plans/<YYYY-MM-DD>-<slug>/, exactly one step file must have > Status: IN_PROGRESS, and the edit must map to that step. Read-only exploration and workflow-bookkeeping updates are allowed before this gate.
6. Plan file format. Copy references/task-overview-template.md to plan.md and references/step-template.md to each step file. Every step has ten fields: Status, Goal, Prerequisites, Deliverables, Plan, Quality Checklist, Validation Checklist, Test Checklist, Implementation Notes, Files Changed.
7. Clarification gate (Full mode). Ask only decision-critical questions that repository evidence cannot answer. A valid plan has Open Questions: None.; the plan approval is the sole routine pre-execution approval.
8. One writer step at a time. Exactly one step may authorize active-worktree writes. Independent read-only investigation or validation may run concurrently. Never mark COMPLETED with known failures—fix through an authorized step or mark BLOCKED.

Delegated Mode

When all of the following are true, skip triage/plan/pre-edit gate:

1. Task assigned by another agent or orchestrator (not an open-ended user request)
2. Explicit scope, success criteria, or acceptance contract received
3. Operating in a focused role (implementer, reviewer, analyst, etc.)

In Delegated Mode: follow all Behavioral Guards and references/code-quality.md; report changed files, commands, validation evidence, and surprises; escalate unapproved design/architecture decisions; stay in scope.

Statuses

Plan-level (plan.md): DRAFT → ACTIVE → COMPLETED → ARCHIVED Step-level (steps/step-N.md): PENDING → IN_PROGRESS → COMPLETED | BLOCKED

Only one writer step may be IN_PROGRESS at a time. The pre-edit gate checks step-level status. The plan remains ACTIVE after execution steps finish and becomes COMPLETED only after global reflection passes.

Reference Loading

Load only what the current phase needs:

• Planning: references/create-plan.md, references/task-overview-template.md, references/step-template.md
• Execution: references/execute-step.md, references/code-quality.md
• Verification: references/verify-step.md
• Command discovery: references/command-discovery.md
• Risk review: references/risk-classification.md
• Project setup: references/project-agents-template.md

Behavioral Guards

Active for the entire session. Do not drift.

1. Evidence first — read target files before editing; search callers/usages before changing shared behavior; distinguish Verified/Assumption/Unknown when evidence status matters and cite key claims.
2. Anti-shortcut gate — before editing: target read ✓, impact search (or N/A — isolated) ✓, validation command (or skipped reason) ✓.
3. Think in code — for aggregate analysis, prefer short scripts/commands that compute results over many raw file dumps. For noisy output, store in /tmp, print bounded slice.
4. Minimalism ladder — before adding code, prefer: delete/skip if not needed → stdlib/native feature → existing dependency/helper → smallest safe implementation; never cut security, data safety, accessibility, or explicit requirements.
5. Surgical changes — touch only needed files/lines; match existing formatting, naming, and conventions; do not copy degraded patterns.
6. Implementation quality — follow local patterns and search for existing equivalents. Prefer the smallest complete change. Do not duplicate business rules or add speculative abstractions, options, dependencies, or refactors. For shared behavior, identify the regression surface and validate requested and preserved behavior. DRY does not justify premature abstraction or out-of-scope cleanup.
7. Design discipline — do not make silent design choices. Surface decisions for user confirmation. Verify approach matches conventions or Design Decisions table.
8. Goal-driven — define success before coding; verify via tests/lint/build/typecheck; add focused tests for new code and bug fixes; fix introduced issues or report blockers.
9. STE-inspired writing (mandatory) — use this style in all agent-authored prose. Use short, direct sentences. Use one main idea per sentence. Use consistent terms. Name the referent when it, this, or another reference could be ambiguous. Apply the rule to answers, handoffs, plans, reports, documentation, comments, and docstrings. Preserve the meaning of normal programming terms, identifiers, code, commands, paths, quotations, generated content, third-party content, and exact formats. Do not claim formal ASD-STE100 compliance. Do not rewrite unrelated prose only to apply this rule.
10. Answer first — after the required triage, lead with the answer or outcome. Include material evidence, validation, uncertainty, caveats, and residual risks. Remove repetition and unnecessary narration, but do not omit material findings. Use headings, lists, tables, and evidence labels only when they improve clarity. Preserve exact JSON and other machine-readable contracts.

Full Workflow Phases

1. Clarify — resolve only decision-critical ambiguity that repository evidence cannot answer. See references/require-clarification.md.
2. Plan — break into vertical-slice steps. See references/create-plan.md.
3. Execute — one step at a time: references/execute-step.md → references/verify-step.md → references/persist-plan.md. Every 2–3 steps: references/checkpoint.md. Before pausing: dump context.
4. Reflect — after all execution steps are done, keep the plan ACTIVE; references/global-reflection.md owns final plan completion.

Resume Protocol

New session → read plans/context.md → relevant plan.md → current step file. See references/resume-workflow.md.