convez.ai
SkillAutomaçãoAvançado
xzh20121116

Agent Workflow

xzh20121116/agent-workflow

Orquestração disciplinada para agentes de IA — requisitos, delegação, revisão e evidência

Ver no GitHub
InicialPluginScore · de 0 a 100

Suite de skills para orquestração de fluxos de trabalho estruturados em agentes de IA como Claude Code e Codex. Transforma um agente de codificação em um gerenciador de projetos disciplinado que clarifica requisitos, delega trabalho, executa revisões e entrega evidências antes de declarar conclusão.

Instalação

$npx convez-ai xzh20121116/agent-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
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
1
Contribuidores
1

Casos de uso

  • Coordenar fluxos de desenvolvimento complexos entre múltiplos agentes especializados
  • Garantir revisão de código e testes antes de aprovar mudanças
  • Manter contexto claro e separar responsabilidades entre orquestrador e subagentes

Veredito

Solução madura e bem fundamentada para disciplinar fluxos de agentes de IA, especialmente relevante para times que precisam de governança em desenvolvimento assistido por IA. Excelente documentação com exemplos práticos, embora demande familiaridade com orquestração de workflows.

README

A tradução para o português deste README ainda está na fila.


Why This Exists

AI coding agents are powerful. But give them a complex task and watch what happens:

  • They start coding before understanding the requirement
  • The main thread does everything — chatting, coding, testing, reviewing — all in one bloated context
  • Context gets compressed, goals get lost, behavior drifts
  • They say "done" without running a single test
  • You ask "did you test the error case?" and they start over from scratch

Agent Workflow fixes this by adding one constraint: the main thread never touches code.

Before / After

Without Agent Workflow

User:  Add phone number editing to the profile page.
AI:    Sure, I'll update a few files.
AI:    [modified 6 files]
AI:    Done.
User:  Did you test it?
AI:    It should work.
User:  What about verifying the old number first?
AI:    Good point, let me add that.
AI:    [modified 4 more files]
AI:    Done.
User:  The context is getting long...
AI:    [context compressed, forgot earlier discussion]

With Agent Workflow

User:  Use the heavy workflow: add phone number editing to the profile page.

Orchestrator:
  1. "What verification method?" → SMS code
  2. "Verify old number first?" → Yes
  3. Writes requirements.md → user confirms
  4. Writes acceptance.md → user confirms
  5. Writes plan.md

  ── Dispatches Implementation Subagent ──
     Returns: DONE (4 files, tests passing)

  ── Dispatches Spec Compliance Reviewer ──
     Result: PASS — all requirements covered

  ── Dispatches Code Quality Reviewer ──
     Result: PASS

  ── Dispatches Verification Subagent ──
     Result: PASS — 12 tests, 0 failures

  ── Dispatches QA Subagent ──
     Result: PASS — 8/8 acceptance criteria

  → Final handoff: feature complete, with evidence

The user answered 3 questions. The Orchestrator managed the rest. Every step has evidence.

How It Works

graph LR
    User["User"] <-->|"clarify, confirm, handoff"| O["Orchestrator<br/>(main thread)"]
    O -->|"writes"| R["requirements.md"]
    O -->|"writes"| A["acceptance.md"]
    O -->|"writes"| P["plan.md"]

    O -->|"dispatches"| IMP["Implementation<br/>Subagent"]
    O -->|"dispatches"| SR["Spec Reviewer"]
    O -->|"dispatches"| QR["Code Quality<br/>Reviewer"]
    O -->|"dispatches"| UI["UI Reviewer<br/>(frontend only)"]
    O -->|"dispatches"| VER["Verification<br/>Subagent"]
    O -->|"dispatches"| QA["QA Subagent"]

    IMP -->|"status + evidence"| O
    SR -->|"pass/fail"| O
    QR -->|"pass/fail"| O
    UI -->|"AI Slop Score"| O
    VER -->|"test results"| O
    QA -->|"criteria check"| O

    style O fill:#2563EB,stroke:#1D4ED8,color:#fff
    style IMP fill:#10B981,stroke:#059669,color:#fff
    style SR fill:#F59E0B,stroke:#D97706,color:#fff
    style QR fill:#F59E0B,stroke:#D97706,color:#fff
    style UI fill:#EC4899,stroke:#DB2777,color:#fff
    style VER fill:#8B5CF6,stroke:#7C3AED,color:#fff
    style QA fill:#8B5CF6,stroke:#7C3AED,color:#fff

Orchestrator Boundaries

The Orchestrator has exactly four jobs. Everything else goes to subagents.

The Orchestrator DOESThe Orchestrator NEVER
Talks to the user — clarifies requirements, confirms, deliversReads source code for implementation
Manages state — state.json, requirements, acceptance, planWrites or edits code directly
Dispatches subagents — builds context packets, delegates via Agent toolRuns tests, lint, or build commands
Synthesizes results — handles status, decides next actionPerforms code review or UI review

This is a hard rule, not a guideline. If you catch the Orchestrator doing any of the "NEVER" column, it's a bug.

Why Subagents Matter

In a long AI coding session, the main thread's context grows with every turn: requirements, code diffs, test logs, review comments, fix attempts, user feedback, assumptions. After a few context compressions, the AI starts to:

  • Forget the original goal — drifts into tangential work
  • Treat assumptions as facts — unverified hypotheses become "known"
  • Modify unrelated files — loses track of scope
  • Claim completion without checking — says "done" without verifying acceptance criteria

This isn't a model capability problem. It's a context management problem.

Agent Workflow solves it by splitting the work:

ComponentWhat stays in context
OrchestratorTask state, user decisions, stage summaries, evidence, risks. Stays lightweight.
Implementation SubagentTask + goal + relevant files + non-goals. Does one thing, returns status + evidence.
Spec ReviewerRequirements + actual code. Compares line by line, returns pass/fail with references.
Code Quality ReviewerCode + patterns. Checks structure, returns issues by severity.
Verification SubagentChanged files + test commands. Runs tests, returns results.
QA SubagentAcceptance criteria + code. Verifies each criterion, returns per-criterion status.

Each subagent receives a SubagentContextPacket — a self-contained prompt with:

  • Task: what to do
  • Goal: success condition
  • Stop condition: when to stop
  • Relevant files: explicit file list
  • Known facts: from requirements, acceptance
  • Non-goals: what NOT to do
  • Expected output: what to write, where
  • Verification expected: how to confirm success

The subagent does its job and returns: status, summary, changed files, evidence, risks, next action. No conversation history leaking. No context bloat.

Multi-agent division of labor isn't for show. It makes complex tasks more stable, more controllable, more auditable, and less likely to drift under long-context pressure.

Execution Gate: When to Ask, When to Proceed

Requirement clarification is a judgment gate, not an interrogation. The Orchestrator follows this rule:

Ask when the missing answer could materially change the implementation. Otherwise, record assumptions and proceed.

SituationAction
Clear enough to proceedStart working
Low-risk assumption possibleRecord assumption, continue
Ambiguity blocks implementationAsk only the necessary questions
High-risk / destructive / security / payment / migrationGenerate requirements + acceptance, request explicit approval

This applies to all task types: backend, frontend, refactoring, bug fixes, infrastructure.

Workflow Intensity: Use the Lightest Safe Workflow

Not every task needs the full heavy workflow. The principle is: use the lightest safe workflow.

Task typeWorkflow intensityWhat runs
Documentation, README, comments, promptsMinimalEdit files, return diff summary. No requirements/acceptance/plan/state. No subagents.
Simple bug fix, typo, config changeLightQuick clarification, implementation + verification. Skip full review chain.
Feature, refactoring, multi-file changeHeavyFull workflow: requirements → acceptance → plan → implementation → review → verification → QA.
Security, payment, auth, migration, large refactorHeavy + explicit approvalFull workflow with user confirmation before implementation.

Example — this README optimization is a documentation-only task. It doesn't need requirements.md, acceptance.md, plan.md, state.json, or QA subagents. It just needs: edit the file, show the diff, done.

Workflow Stages

graph TD
    A["requirement_clarification"] --> B["requirements"]
    B --> C["acceptance"]
    C --> D["plan"]
    D --> E["implementation"]
    E --> F["spec_compliance_review"]
    F --> G["code_quality_review"]
    G --> H{"Frontend task?"}
    H -->|Yes| I["ui_review"]
    H -->|No| J["verification"]
    I --> J
    J --> K["qa"]
    K --> L["final_handoff"]

    style A fill:#3B82F6,stroke:#2563EB,color:#fff
    style E fill:#10B981,stroke:#059669,color:#fff
    style F fill:#F59E0B,stroke:#D97706,color:#fff
    style G fill:#F59E0B,stroke:#D97706,color:#fff
    style I fill:#EC4899,stroke:#DB2777,color:#fff
    style J fill:#8B5CF6,stroke:#7C3AED,color:#fff
    style K fill:#8B5CF6,stroke:#7C3AED,color:#fff
    style L fill:#3B82F6,stroke:#2563EB,color:#fff
StageWho runsWhat happens
requirement_clarificationOrchestratorTalks to user, clarifies ambiguities
requirementsOrchestratorWrites requirements.md, user confirms
acceptanceOrchestratorWrites acceptance.md with testable criteria, user confirms
planOrchestratorWrites plan.md with executable task breakdown
implementationSubagentImplements code (worktree isolation for high-risk)
spec_compliance_reviewSubagentReads actual code, compares to requirements line by line
code_quality_reviewSubagentChecks structure, correctness, maintainability
ui_reviewSubagentCatches AI slop — fonts, gradients, layout, responsiveness
verificationSubagentRuns tests, lint, build
qaSubagentVerifies every acceptance criterion against code
final_handoffOrchestratorReports results with evidence bundle

Key Features

FeatureWhat it does
Orchestrator-subagent separationMain thread coordinates, subagents execute. The Orchestrator never writes code.
SubagentContextPacketSelf-contained prompts with task, goal, files, non-goals, verification. No conversation history leaking.
Implementer 4-status returnDONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED — Orchestrator handles each
3-stage reviewSpec compliance + code quality + UI review (frontend tasks)
Execution gateAsk only when the answer materially changes implementation; otherwise record assumptions and proceed
Workflow intensityLightest safe workflow — docs skip heavy workflow, simple fixes skip full review chain
Checkpoint & resumeSurvives context resets via handoff.md. Never resumes from memory alone.
Drift detectionAfter each stage, verifies work still serves original intent
Risk-based isolationHigh-risk tasks use git worktree isolation; medium-risk shares working directory

Quick Start

AI-Assisted Install (Recommended)

Paste this to your AI coding agent:

Read https://github.com/xzh20121116/agent-workflow and install the agent-workflow skills globally.

Manual Install

git clone https://github.com/xzh20121116/agent-workflow.git ~/.agent-workflow

# Claude Code:
ln -s ~/.agent-workflow/skills/agent-workflow-init ~/.claude/skills/agent-workflow-init
ln -s ~/.agent-workflow/skills/agent-workflow-start ~/.claude/skills/agent-workflow-start

# Codex App:
ln -s ~/.agent-workflow/skills/agent-workflow-init ~/.codex/skills/agent-workflow-init
ln -s ~/.agent-workflow/skills/agent-workflow-start ~/.codex/skills/agent-workflow-start

Usage

Initialize a project

Initialize the current project with agent-workflow.

Start a feature (heavy workflow)

Use heavy workflow: add phone number editing to the user profile page.

Fix a bug

Use heavy workflow: payment callback fails intermittently, a few times per day.

Beautify a frontend page

Use heavy workflow to beautify src/pages/landing/index.tsx.

Run spec compliance review only

Review src/services/auth.service.ts against docs/requirements.md for spec compliance.

Run code quality review only

Run code quality review on src/services/order.service.ts.

Included Skills

SkillPurpose
agent-workflow-initProject-level bootstrapper. Creates docs/agent/ structure, AGENTS.md, project config.
agent-workflow-startRequest-level entry point. Creates request workspace, drives the full workflow from clarification to delivery.

Subagent Prompt Templates

Each role has a dedicated prompt template in skills/agent-workflow-start/references/:

TemplateRoleKey Feature
implementer-prompt.mdBackend implementationSubagentContextPacket, 4-status return
frontend-implementer-prompt.mdFrontend implementationDesign constraints (typography, color, layout, motion)
spec-reviewer-prompt.mdSpec compliance review"Do Not Trust the Report" — reads actual code
code-quality-reviewer-prompt.mdCode quality reviewStructure, correctness, maintainability
ui-reviewer-prompt.mdUI/visual reviewAI Slop Score, responsive check, accessibility
verification-prompt.mdTest/lint/buildRuns project test suite
qa-prompt.mdAcceptance criteriaVerifies every criterion against code

Example Output

After a successful workflow run, you get:

docs/agent/requests/REQ-20260609-001/
├── requirements.md          # What we're building
├── acceptance.md            # How we verify it
├── plan.md                  # Task breakdown
├── state.json               # Machine-readable state
├── handoff.md               # Checkpoint for resume
├── implementation.md        # What was built, files changed
├── review.md                # Spec + code quality findings
├── verification.md          # Test results, lint output
└── qa.md                    # Acceptance criteria check

Every claim is backed by evidence. No "theoretically it should work."

Origin Story

Agent Workflow came from real daily usage — hitting the same pain points over and over: AI agents freestyle-coding without understanding requirements, main threads bloating with code + tests + reviews all mixed together, context compression causing goal drift.

After building the initial version, the author found Aegis and Superpowers. Both had valuable ideas. Agent Workflow absorbed the best of both and added what was still missing.

What Agent Workflow Does That Others Don't

Agent WorkflowAegisSuperpowers
Main threadNever touches codeCoordinator + baselineAuto-trigger
Review3-stage (spec + quality + UI)2-stage2-stage
Implementer4-status returnSubagent-drivenPlan-driven
ContextSubagentContextPacket (isolated)Baseline contextPlan-as-junior
Execution gateAsk only when needed, record assumptionsBaseline-read before changesUniform process
Workflow intensityLightest safe workflow per task typeRisk-adaptiveUniform
SetupZero configDoctor scriptPer-host plugin

Core advantage: Orchestrator discipline

The #1 failure mode of AI coding agents on complex tasks: the main thread does everything — chatting, coding, testing, reviewing — all in one bloated context. Then context gets compressed, goals get lost, behavior drifts.

Agent Workflow enforces a hard rule: the Orchestrator never reads, writes, or reviews code. Every coding task goes to a subagent with a self-contained context packet. The Orchestrator's context stays clean. The subagent stays focused. No leaking.

This applies to all task types: backend APIs, database migrations, refactoring, bug fixes, infrastructure changes, and yes, frontend too.

Core advantage: SubagentContextPacket

Each subagent gets a self-contained context packet — task, goal, files, non-goals, verification. No conversation history leaking in. The subagent does its job and returns evidence.

Core advantage: 3-stage review

Other tools have 2-stage review. Agent Workflow has 3: spec compliance, code quality, and UI review (for frontend tasks). The first two apply to every task.

Bonus: Frontend quality control

AI-generated frontends have a distinctive "plastic look." Agent Workflow addresses this through design constraints and a dedicated UI Reviewer. But this is one feature among many, not the core value proposition.

When Agent Workflow is the right choice

  • You want the main thread to stay focused on coordination, not coding
  • You want explicit status handling (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED)
  • You want self-contained subagent execution with no context leaking
  • You want a simple setup with minimal configuration
  • You want proven patterns from Aegis and Superpowers in a simpler package

When to use something else

  • Complex enterprise codebase needing baseline reads before every change → Aegis
  • TDD-first team wanting strict red-green-refactor as non-negotiable discipline → Superpowers

Project Structure

.
├── skills/
│   ├── agent-workflow-init/
│   │   ├── SKILL.md
│   │   ├── references/agent-workflow-guide.md
│   │   ├── assets/templates/
│   │   │   ├── AGENTS.md.template
│   │   │   └── change-request-template.md
│   │   └── scripts/
│   │       ├── init_agent_workflow.py
│   │       └── install_symlinks.sh
│   └── agent-workflow-start/
│       ├── SKILL.md
│       ├── references/
│       │   ├── start-guide.md
│       │   ├── implementer-prompt.md
│       │   ├── frontend-implementer-prompt.md
│       │   ├── spec-reviewer-prompt.md
│       │   ├── code-quality-reviewer-prompt.md
│       │   ├── ui-reviewer-prompt.md
│       │   ├── verification-prompt.md
│       │   └── qa-prompt.md
│       └── scripts/
│           └── start_agent_workflow.py
├── LICENSE
└── README.md

Inspired By

  • Aegis — baseline-first, evidence-driven method pack for AI coding agents
  • Superpowers — composable agent skills by Jesse Vincent

License

MIT License. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados