Workflows Reference

All 10 development workflows — from feature delivery to code audits.

Table of contents
  1. What Are Workflows?
    1. Choosing the Right Workflow
  2. 🏭 Feature Workflow (/orchestrator)
    1. Flow
    2. Phases
    3. Key Rules
    4. Error Handling
  3. Phase 1: Research (/1-research)
    1. Steps
    2. Skills Used
  4. Phase 2: Implement (/2-implement)
    1. TDD Cycle
    2. Unit Test Requirements
    3. Skills Used
  5. Phase 3: Integrate (/3-integrate)
    1. When Required
    2. Steps
  6. Phase 3.5: E2E Test (/e2e-test)
    1. When Required
    2. When to Skip
    3. Steps
  7. Phase 4: Verify (/4-verify)
    1. Backend Validation (Go)
    2. Frontend Validation (TypeScript/Vue)
    3. Build Check
    4. Coverage Target
    5. If This Phase Fails
  8. Phase 5: Ship (/5-commit)
    1. Conventional Commit Format
    2. Types
  9. 🔧 Quick-Fix Workflow (/quick-fix)
    1. When to Use
    2. Phases
  10. 🔧 Refactor Workflow (/refactor)
    1. When to Use
    2. Requires a Specific Goal
    3. Phases
    4. Key Principle
  11. 🔧 Audit Workflow (/audit)
    1. When to Use
    2. Phases
    3. Findings Triage
    4. Best Practice

What Are Workflows?

Workflows are structured, multi-phase development processes defined in .agent/workflows/. They chain rules and skills together into repeatable, quality-enforced development cycles.

Each workflow is invoked as a slash command (e.g., /orchestrator, /quick-fix) and guides the agent through specific phases with completion criteria at each step.

Choosing the Right Workflow

Situation Workflow
Building a new feature /orchestrator
Fixing a known bug (<50 lines) /quick-fix
Restructuring code /refactor
Reviewing code quality /audit
Running a single phase /1-research, /2-implement, etc.

🏭 Feature Workflow (/orchestrator)

File: .agent/workflows/orchestrator.md

The primary workflow for building features. Treats the development lifecycle as a state machine — no phase can be skipped.

Flow 

Research → Implement (TDD) → Integrate → E2E (conditional) → Verify → Ship

Phases

Phase Gate Output
Research Research log created task.md + docs/research_logs/*.md
Implement Unit tests pass Production code + unit tests
Integrate Integration tests pass Integration tests (Testcontainers)
E2E (conditional) E2E tests pass + screenshots E2E tests + screenshots
Verify All linters pass Coverage report
Ship Committed Git commit

Key Rules

  • FORBIDDEN from skipping phases — each phase must complete before the next starts
  • Agent acts as a “Senior Principal Engineer with a mandate for strict protocol adherence”
  • Pre-implementation: scan .agent/rules/, identify applicable rules, READ them
  • Tasks marked [x] only after Phase 4 (Verify) passes

Error Handling

If a phase fails:

  1. Document the failure in task summary
  2. Do not proceed to next phase
  3. Fix the issue within current phase
  4. Re-run phase completion criteria
  5. Then proceed

Phase 1: Research (/1-research)

File: .agent/workflows/1-research.md

Understand the request context and gather knowledge before writing any code.

Steps

  1. Analyze Request — parse requirements, identify scope
  2. Review Current Implementation — understand existing architecture
  3. Build Mental Model — requirements, constraints, integration points
  4. Define Scope — create task.md with atomic tasks
  5. Identify Research Topics — list all technologies involved
  6. Search Documentation — use Qurio or web search for each topic
  7. Document Findings — create docs/research_logs/{feature}.md
  8. Document Architecture Decisions — create ADRs using ADR Skill if needed
  9. Fallback — web search if documentation search fails

Skills Used

  • Sequential Thinking — for complex design decisions
  • ADR — for significant architecture decisions

Phase 2: Implement (/2-implement)

File: .agent/workflows/2-implement.md

Write production code following Test-Driven Development (TDD).

TDD Cycle

  1. Red — write a failing test
  2. Green — write minimal code to make it pass
  3. Refactor — improve structure while keeping tests green

Unit Test Requirements

  • Mock all dependencies (interfaces)
  • Test happy path, error paths, AND edge cases
  • Target >85% coverage on domain logic

Skills Used

  • Sequential Thinking — for complex refactoring
  • Debugging Protocol — for non-obvious test failures
  • Guardrails — pre-flight checklist before writing code

Phase 3: Integrate (/3-integrate)

File: .agent/workflows/3-integrate.md

Test adapter implementations with real infrastructure using Testcontainers.

When Required

  • Code that touches database (storage implementations)
  • Code that calls external APIs
  • Code that uses message queues, caches, etc.

Steps

  1. Setup Testcontainers (PostgreSQL, Redis, NSQ, etc.)
  2. Write integration tests (*_integration_test.go or *.integration.spec.ts)
  3. Run integration tests
  4. Optional manual verification

Phase 3.5: E2E Test (/e2e-test)

File: .agent/workflows/e2e-test.md

Validate complete user journeys through the full system using Playwright MCP.

When Required

  • UI components were added or modified
  • API endpoints interact with frontend
  • Critical user-facing flows were changed

When to Skip

  • Pure backend/infrastructure changes
  • Internal library refactoring
  • Test-only changes

Steps

  1. Start services (docker compose or local dev)
  2. Create E2E test plan
  3. Execute with Playwright MCP (navigate, interact, screenshot)
  4. Document results with screenshots in docs/e2e-screenshots/

Phase 4: Verify (/4-verify)

File: .agent/workflows/4-verify.md

Run all linters, static analysis, and tests to ensure code quality.

Backend Validation (Go) 

gofumpt -l -e -w . && go vet ./... && staticcheck ./... && gosec -quiet ./... && go test -race ./...

Frontend Validation (TypeScript/Vue) 

pnpm run lint --fix && npx vue-tsc --noEmit && pnpm run test

Build Check 

# Backend
go build ./...

# Frontend
pnpm run build

Coverage Target

85% on domain logic.

If This Phase Fails

  1. Do NOT proceed to Ship
  2. Fix the issue (go back to Phase 2 or 3)
  3. Re-run full verification
  4. Only proceed when ALL checks pass

Phase 5: Ship (/5-commit)

File: .agent/workflows/5-commit.md

Commit completed work with proper conventional commit format.

Conventional Commit Format 

<type>(<scope>): <description>

Types

| Type | Purpose | | ———- | ——————————– | | feat | New feature | | fix | Bug fix | | docs | Documentation only | | refactor | Code change (no new feature/fix) | | test | Adding or updating tests | | chore | Maintenance, dependencies | | perf | Performance improvement | | ci | CI/CD configuration changes |

🔧 Quick-Fix Workflow (/quick-fix)

File: .agent/workflows/quick-fix.md

Fast-track bug fixes and small changes (<50 lines) that don’t require full research or integration phases.

When to Use

  • Bug fixes with a known root cause
  • Small, isolated changes
  • Hotfixes for production issues
  • Addressing review findings from /audit

Phases

  1. Diagnose — identify the bug, locate affected code, optionally use Debugging Protocol skill
  2. Fix + Test (TDD) — write failing test, apply fix, verify existing tests pass
  3. Verify + Ship — full validation suite, commit with fix type

🔧 Refactor Workflow (/refactor)

File: .agent/workflows/refactor.md

Safely restructure existing code while preserving behavior.

When to Use

  • Code restructuring (moving, renaming, splitting modules)
  • Pattern migration (e.g., callbacks → async/await)
  • Dependency upgrades with breaking changes
  • Addressing tech debt or architectural improvements

Requires a Specific Goal

  • ✅ /refactor extract storage interface in task feature
  • ✅ /refactor split user handler into separate auth handler
  • ❌ /refactor apps/backend (too vague — use /audit first)

Phases

  1. Impact Analysis — map blast radius, document existing behavior, identify risks
  2. Incremental Change (TDD) — one change at a time, tests pass at each step
  3. Parity Verification — full validation, compare coverage (equal or better)
  4. Ship — commit with refactor type

Key Principle

Never break the build for more than one step at a time.

🔧 Audit Workflow (/audit)

File: .agent/workflows/audit.md

Inspect existing code quality without writing new features. Produces structured findings for subsequent fix workflows.

When to Use

  • After another agent’s feature is committed (cross-agent review)
  • Periodic quality gates
  • Before releases or deployments
  • Verification without new code

Phases

  1. Code Review — invoke the Code Review Skill against specified files
  2. Automated Verification — full lint/test/build validation
  3. Findings Report — saved to docs/audits/review-findings-{feature}-{date}-{HHmm}.md

Findings Triage

Finding Type Example Follow-Up
Nit / minor “Rename x to userCount” Fix directly
Small isolated fix “Add input validation” /quick-fix in new conversation
Structural change “Storage not behind interface” /refactor in new conversation
Missing capability “No auth on admin routes” /orchestrator in new conversation

Best Practice

Run audits in a fresh conversation (not the one that wrote the code) to avoid confirmation bias.

Back to top

Built with ❤️ for the Developer Community. Distributed under the MIT License.

This site uses Just the Docs, a documentation theme for Jekyll.