swe-workflow
ex-git/swe-workflow
A lightweight, structured development workflow for coding agents. Compatible with Pi, Claude Code, Cursor, Codex, Gemini, and 40+ agents supporting the Agent Skills spec.
Instalação
npx convez-ai ex-git/swe-workflow1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
swe-workflow
A lightweight, structured Software Engineering Workflow (SWE workflow) for AI coding agents. Compatible with Pi, Claude Code, Cursor, Codex, Gemini, and other agents supporting the Agent Skills spec.
Every code task starts with workflow triage. Simple tasks stay lightweight; broad, ambiguous, or multi-file tasks use a persisted plan.
What It Does
Enforces visible workflow selection plus a disciplined process for any coding task complex enough to warrant it:
- Triage — declare
LightweightorFullmode before edits - Clarify — understand the request before acting; surface design decisions
- Plan — break Full workflow work into small, ordered steps with a Design Decisions table
- Execute — one step at a time, documented as you go; verify design against conventions
- Verify — re-read, test, review diff (single gate)
- Reflect — catch complexity before it compounds
Every reference file front-loads a Contract block (first 5-10 rules) so even low-thinking agents absorb the critical gates.
In Full workflow mode, task state lives in plans/<YYYY-MM-DD>-<slug>/plan.md plus individual step files at steps/step-N.md plus plans/context.md.
Why
Without structure, coding agents tend to:
- Jump straight to code without understanding the request
- Make sweeping changes that break unrelated code
- Skip testing and self-review
- Lose context across sessions
This workflow addresses all of that with a single skill, mandatory mode declaration, and persistent plan files when needed. See SKILL.md for the full agent-facing specification.
Expected Agent Behavior
For every code-related task, the agent must first declare:
Workflow mode: Lightweight | Full
Reason: ...
Success criteria:
- ...
Plan needed: yes | no
Full workflow mode is mandatory for broad cleanup/refactor/lint tasks, deletes/moves, backend + UI changes, API/schema/route/tooling/config changes, source-of-truth docs, ambiguous work, or anything expected to touch more than 3 files.
In Full workflow mode, unresolved questions must be asked in chat before plan creation/finalization; valid plans record Open Questions as None. and surface design choices in a Design Decisions table for user confirmation. Implementation edits must wait until a valid plan exists under plans/<YYYY-MM-DD>-<slug>/, the current step file is marked IN_PROGRESS, and the edit maps to that step.
Installation
Via the Agent Skills CLI:
# Install globally (all supported agents)
npx skills add ex-git/swe-workflow -g
# Install for a specific agent
npx skills add ex-git/swe-workflow -g --agent claude
npx skills add ex-git/swe-workflow -g --agent cursor
npx skills add ex-git/swe-workflow -g --agent pi
npx skills add ex-git/swe-workflow -g --agent codex
npx skills add ex-git/swe-workflow -g --agent gemini
Manual install
Copy the skill directory to your agent's skills location:
# Pi
cp -r swe-workflow ~/.pi/agent/skills/
# Claude Code
cp -r swe-workflow ~/.claude/skills/
# Cursor
cp -r swe-workflow ~/.cursor/skills/
# Codex
cp -r swe-workflow ~/.codex/skills/
# Gemini
cp -r swe-workflow ~/.gemini/skills/
Structure
swe-workflow/
├── SKILL.md # Agent-facing entry point (mandatory router/contract)
├── references/ # Supplementary detail for each workflow phase
│ ├── task-overview-template.md # Task overview skeleton — copy to plan.md verbatim
│ ├── step-template.md # Per-step file skeleton — copy to steps/step-N.md verbatim
│ ├── plan-example.md # Filled-in 3-step example plan (directory structure)
│ ├── code-quality.md # Reusable code quality bar
│ ├── delegated-guards.md # Standalone guards for child agents in multi-agent setups
│ ├── definition-of-done.md # Final completion gate
│ ├── command-discovery.md # Validation command discovery
│ ├── risk-classification.md # Compact risk routing rules
│ ├── project-agents-template.md # Template for target repo AGENTS.md
│ ├── require-clarification.md
│ ├── create-plan.md
│ ├── resume-workflow.md
│ ├── execute-step.md
│ ├── verify-step.md
│ ├── persist-plan.md
│ ├── dump-context.md
│ ├── reflect-after-changes.md
│ └── global-reflection.md
├── examples/ # Worked examples and optional evaluation aids
│ └── evaluation-prompts.md # Prompts for workflow evaluation
├── AGENTS.md # Repo-level agent instructions / template
├── CHANGELOG.md
├── LICENSE
├── package.json
└── README.md
Production Code Quality Setup
This skill provides the workflow contract. For production codebases, pair it with a project-level AGENTS.md.
Recommended setup:
- Install
swe-workflow. - Copy
references/project-agents-template.mdinto the target repo asAGENTS.md. - Fill in required commands, architecture rules, API rules, data rules, security rules, testing rules, and do-not-touch areas.
- Test the setup with
examples/evaluation-prompts.md.
Keep SKILL.md small. Put project-specific rules in the target repo's AGENTS.md, not in this skill.
Verification
After installing, test with a vague feature request:
Add a function that validates email addresses
Expected behavior: the agent declares Full workflow mode, explains why the request is ambiguous, and asks clarifying questions (scope, input format, error shape) rather than jumping to code.
Multi-Agent Handoffs
The task plan and context files are portable across agents. Agent A can complete steps 1–3 and dump context; Agent B reads plans/context.md if present, scans plans/<YYYY-MM-DD>-<slug>/plan.md and step statuses to find active work, verifies relevant entries in the current workspace, and picks up at step 4.
Subagent / Multi-Agent Orchestration
This skill supports both orchestrator and delegated child roles:
| Role | What applies | What's skipped |
|---|---|---|
| Orchestrator (top-level agent, user-facing) | Full workflow: triage → plan → execute → verify | Nothing |
| Delegated child (focused task from another agent) | Behavioral Guards + Code Quality Bar | Triage block, plan creation, pre-edit gate |
How it works
When an agent receives a focused task from an orchestrator (not an open-ended user request) with explicit scope and success criteria, it automatically enters Delegated Mode — defined in SKILL.md. No platform-specific hooks needed; the LLM self-detects based on its context.
For orchestrator authors
Three options for child agents, from lightest to heaviest:
- Inject only
references/delegated-guards.md— minimal overhead, standalone file with behavioral guards and code quality bar. Works on any platform that supports injecting text into a child's context. - Inject the full skill — children self-detect Delegated Mode and skip the ceremony. More tokens but requires no orchestrator-side configuration.
- No skill injection — rely on the orchestrator's task prompt to encode quality expectations. Least overhead, most fragile.
Platform examples
# Pi: child inherits skill automatically, self-detects delegated mode
# Or inject only the guards file via task prompt / reads
# Claude Code: reference in child context
# Cursor: include in child rules
# Codex: include in child system instructions
# Any LLM: paste references/delegated-guards.md into child context
Documentation
SKILL.md— the full agent-facing workflowCHANGELOG.md— release historyexamples/— worked example plans
License
MIT — see LICENSE.