convez.ai
Skill
ex-git

swe-workflow

ex-git/swe-workflow

Ver no GitHub
InicialPluginScore · de 0 a 100

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-workflow

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
—
Issues abertas
1
Contribuidores
1

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:

  1. Triage — declare Lightweight or Full mode before edits
  2. Clarify — understand the request before acting; surface design decisions
  3. Plan — break Full workflow work into small, ordered steps with a Design Decisions table
  4. Execute — one step at a time, documented as you go; verify design against conventions
  5. Verify — re-read, test, review diff (single gate)
  6. 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:

  1. Install swe-workflow.
  2. Copy references/project-agents-template.md into the target repo as AGENTS.md.
  3. Fill in required commands, architecture rules, API rules, data rules, security rules, testing rules, and do-not-touch areas.
  4. 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:

RoleWhat appliesWhat's skipped
Orchestrator (top-level agent, user-facing)Full workflow: triage → plan → execute → verifyNothing
Delegated child (focused task from another agent)Behavioral Guards + Code Quality BarTriage 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:

  1. 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.
  2. Inject the full skill — children self-detect Delegated Mode and skip the ceremony. More tokens but requires no orchestrator-side configuration.
  3. 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

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados