ex-git/swe-workflow

SWE Workflow

Every code task starts with workflow triage. Simple tasks stay lightweight; broad or ambiguous tasks use a persisted plan.

Contract

This block is the minimum every agent must follow. If you skim only this section, you are still compliant.

1. Triage first. The first lines of your reply to any code-related task must be:

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

2. Full workflow is mandatory for: repo-wide scans/migrations/cleanup, lint/type/build/test cleanup, broad refactors touching multiple files, deleting/moving/renaming files, backend + frontend changes in one task, API/schema/route/config contract changes, source-of-truth doc updates, tasks touching >3 files, or ambiguous scope. Lightweight work that hits any trigger MUST escalate: stop, declare Full, create a plan, then resume.
3. Pre-edit gate (Full mode). Before any write/edit/bash on task target files: a plans/<task>.md file must exist, exactly one step must have **Status:** IN_PROGRESS, and the edit must map to that step. Only plans/*.md files may be written before this gate is satisfied.
4. Plan file format. Every plans/<task>.md copies references/plan-template.md verbatim. Every step has all seven fields: Status, Prerequisites, Deliverables, Plan, Validation Checklist, Test Checklist, Files Changed. The plan includes a Design Decisions table and a top-level Implementation Log.
5. Clarification gate (Full mode). If any requirement question is known, ask it in chat before writing or finalizing plans/<task>.md. A valid plan has no unresolved questions; DRAFT means awaiting plan approval, not awaiting requirement answers, and clarification must not be turned into an implementation step.
6. One step at a time. Never batch. Never mark COMPLETED with known failures — fix or mark BLOCKED.

Plan Template

Use references/plan-template.md as the source of truth for plans/<task>.md. Copy it verbatim for every new plan. Do not reconstruct the structure from memory; do not invent alternative formats. Full plans capture a task-local Working Set and Verified Facts so agents use evidence instead of guessed paths, APIs, or conventions.

Anti-Patterns — Wrong vs Right

Plan format — missing required fields:

WRONG:  ### Step 1 — Add dependency [COMPLETED]     ← no Status field, no Prerequisites,
        ### Step 2 — Create module [COMPLETED]         no Deliverables, no Validation, no Files Changed

RIGHT:  ### Step 1: Add dependency
        **Status:** COMPLETED
        **Prerequisites:** ...
        **Deliverables:** ...
        **Validation Checklist:** ...
        **Files Changed:** ...

Step decomposition — horizontal vs vertical slices:

WRONG (horizontal):              RIGHT (vertical):
  Step 1: Define all types         Step 1: Implement + test feature A
  Step 2: Write all functions       Step 2: Implement + test feature B
  Step 3: Write all tests           Step 3: Implement + test feature C

Each step is a thin vertical slice through all layers (types, logic, tests) — independently verifiable.

Triage skipped because "the task seemed simple": the triage block decides what is simple. Emit it even for one-line changes; Lightweight is a valid outcome, but the declaration is not optional.

Open questions parked in the plan:

WRONG:  ## Open Questions
        - Which UI should change?
        ### Step 1: Resolve open questions

RIGHT:  Ask the question in chat before creating/finalizing the plan,
        then write ## Open Questions as `None.`

Silent design assumptions:

WRONG:  Agent picks modal vs page, dropdown vs radio, join table vs JSON column
        without asking — implements whatever seems reasonable

RIGHT:  Surface the choice in Design Decisions table during planning,
        confirm with user, then implement the confirmed approach

Status values: PENDING | IN_PROGRESS | COMPLETED | BLOCKED

Behavioral Guards — All Code Tasks

These guards are active for the entire session, not just the first response. Do not drift.

1. Evidence first — read relevant files before editing; verify paths/imports/dependencies; search callers/usages before changing shared behavior.
2. Simplicity — minimum code for the problem; no unrequested features, abstractions, dependencies, or defensive handling.
3. Surgical changes — touch only needed files/lines; match formatting, naming, and import conventions; do not copy degraded correctness patterns.
4. Reuse before create — before writing a new component, utility, hook, type, or schema pattern, search for existing equivalents; evidence of the search must appear in Verified Facts. Extract duplication when extraction is small and in scope; mention unrelated issues but don't fix them.
5. Design discipline — do not make silent design choices about UI layout, schema shape, component structure, or API contracts. Surface design decisions for user confirmation during clarification. During execution, verify approach matches existing conventions or the Design Decisions table.
6. Goal-driven — define success before coding; verify via tests/lint/format/build/typecheck; add focused tests for new code and bug fixes when a test framework exists; run quality gates including pre-commit hooks; fix introduced issues or report blockers.

Full Workflow

File Structure

plans/
├── repo-map.md      # Advisory project memory; verify before relying on it
├── context.md       # Session state (overwritten each pause)
└── <task>.md        # Task plan, Working Set, Verified Facts, progress

Phases

1. Clarify — analyze scope, ask targeted questions, get explicit confirmation. See require-clarification.
2. Plan — break into small ordered steps, copy references/plan-template.md to plans/<task>.md and fill it in. See create-plan.
3. Execute — one step at a time: execute-step → verify-step → persist-plan. Update maintain-repo-map only for durable project discoveries. Every 2–3 steps: reflect. Before pausing: dump-context.
4. Reflect — after all steps done: global-reflection.

Resume Protocol

New session on existing work → read in order: plans/context.md → plans/<task>.md; read plans/repo-map.md only if present/useful and verify entries against the current workspace. See resume-workflow.

Core Constraints

• One step at a time — never batch multiple steps.
• Stay in scope — only touch files in the step's plan.
• Persist reality — keep the plan file accurate at all times.
• Record evidence — keep the plan's Working Set, Verified Facts, Implementation Notes, and Files Changed accurate.
• Never mark COMPLETED with known issues — fix or mark BLOCKED.

Reference Guide

| Reference | Purpose | |---|---| | plan-template | Canonical plans/<task>.md skeleton — copy verbatim | | require-clarification | Clarify ambiguous requests before planning | | create-plan | Exploration, step sizing, plan creation procedure | | execute-step | Code protection, implementation, scope management | | verify-step | Validate + test + review diff (single gate) | | maintain-repo-map | Maintain advisory project memory; verify before relying on it | | persist-plan | Update plan status and context | | dump-context | Save session state before pausing | | reflect-after-changes | Catch complexity every 2–3 steps | | global-reflection | Final review when all steps done | | resume-workflow | Resume existing work in a new session |