Workflow Orchestration

Workflow Orchestration

This skill defines how the Automatasaurus workflow operates.

Architecture Overview

Slash Commands (Orchestration)

Commands run in the main conversation and orchestrate agents:

Agents (Autonomous Workers)

Agents perform discrete tasks without user dialogue:

Workflow Modes

The system operates in different modes:

Mode Context Passing

When delegating to agents, include mode context:

# Single-issue mode
"This is SINGLE-ISSUE mode. Do NOT auto-merge. Notify when PR is approved."

# All-issues mode
"This is ALL-ISSUES mode. Auto-merge after approvals and continue to next issue."

Default: If mode unclear, default to single-issue (safer).

Coordination Modes

The orchestrator can use two modes for delegating work to agents:

Decision Criteria

Settings control defaults:

• teamPreferForReviews: true — default to review teams
• teamPreferForImplementation: false — default to solo developer subagent
• teamMaxTeammates: 4 — cap concurrent team members

Teams are experimental. Always fall back to subagents if team creation fails.

Two-Phase Workflow

Phase 1: Discovery (Interactive)

User: /auto-discovery "feature description"
           ↓
    Main conversation facilitates requirements gathering
    (loads requirements-gathering, user-stories skills)
           ↓
    Produces discovery.md (or discovery-{N}.md on re-runs)
           ↓
    Spawns Architect → reviews technical feasibility
    Spawns Designer → reviews UI/UX considerations
           ↓
    User approves → Creates milestones and issues

Phase 2: Implementation (Autonomous)

User: /auto-plan (optional)
           ↓
    Analyzes issues, creates implementation-plan.md (or implementation-plan-{N}.md on re-runs)
           ↓
User: /auto-work-all
           ↓
    LOOP for each issue:
      - Setup orchestration folder
      - Check dependencies
      - Choose coordination mode (teams vs subagents per step)
      - Spawn Designer → specs (if UI)
      - Implementation:
          Subagent path: Spawn Developer → implements, creates PR
          Team path:     Developer + Designer team → real-time iteration, PR
      - Reviews:
          Subagent path: Spawn Architect, Designer, Tester in parallel
          Team path:     Review team → coordinated findings
      - Check PR Done Criteria
      - Merge (if all-issues mode)
      - Continue to next
           ↓
    All complete → Notify user

Bidirectional Context Flow

Sub-agents start with fresh context (no conversation history). The orchestration layer uses briefings and reports to communicate context and capture results.

Orchestration Folder Structure

orchestration/
├── discovery/
│   └── {date}-{feature-slug}/
│       ├── BRIEFING-architect-review.md
│       ├── REPORT-architect-review.md
│       └── ...
├── planning/
│   └── {date}-{plan-name}/
│       └── ...
└── issues/
    └── {issue-number}-{slug}/
        ├── BRIEFING-design-specs.md
        ├── REPORT-design-specs.md
        ├── BRIEFING-implement.md
        ├── REPORT-implement.md
        ├── BRIEFING-architect-review.md
        ├── REPORT-architect-review.md
        ├── BRIEFING-designer-review.md
        ├── REPORT-designer-review.md
        ├── BRIEFING-test.md
        └── REPORT-test.md

How It Works

Parent agent (orchestrating workflow):

1. Creates briefing file in orchestration/{type}/{id}/BRIEFING-{step}.md
2. Includes briefing path in Task prompt when spawning sub-agent
3. After Task returns, reads REPORT-{step}.md from same folder
4. Includes report summary in next agent's briefing

Sub-agent (following AGENT.md protocol):

1. Reads briefing file path from task prompt
2. Reads briefing as first action
3. Does work
4. Writes report to REPORT-{step}.md in same folder before completing

Context Chain

Each agent receives context about what previous agents did:

1. Designer creates specs → writes REPORT-design-specs.md
2. Developer briefing includes designer's report summary
3. Developer implements → writes REPORT-implement.md
4. Reviewer briefings include developer's report summary
5. ...and so on

This enables informed decisions throughout the workflow.

Benefits

• Audit trail: Full history of agent communication per issue
• Debugging: Can review what context each agent received
• No collisions: Each spawn gets unique files
• Context chain: Parent aggregates prior work into new briefings

PR Done Criteria

Both /auto-work-issue and /auto-work-all use these criteria to determine when a PR is ready:

Required Approvals

Criteria Checklist

• All required approval comments present
• No outstanding ❌ CHANGES REQUESTED
• CI/automated tests passing

Then What?

Issue State Labels

Track issue progress:

State Flow

[new] → ready (if no deps) OR blocked (if deps)
  ↓
ready → in-progress (when selected)
  ↓
in-progress → needs-review (when PR opened)
  ↓
needs-review → [closed] (when merged)

Dependency Parsing

Issues declare dependencies in their body:

## Dependencies
Depends on #12
Depends on #15

An issue is "ready" when all dependencies are closed.

Review Flow

Standardized Review Comments

Since all agents share the same GitHub identity, reviews use standardized comments:

Approval:

✅ APPROVED - [Role]
[Summary]

Changes Requested:

❌ CHANGES REQUESTED - [Role]
[Issues to address]

Review Process

1. Developer creates PR

2. Architect reviews (REQUIRED)
   Posts: ✅ APPROVED - Architect
   Or: ❌ CHANGES REQUESTED - Architect

3. Designer reviews (if UI)
   Posts: ✅ APPROVED - Designer
   Or: N/A - no UI changes

4. Tester verifies (REQUIRED)
   Posts: ✅ APPROVED - Tester
   Or: ❌ CHANGES REQUESTED - Tester

5. If changes requested:
   Developer fixes
   Re-request relevant review

6. When all approved:
   Orchestration checks mode
   → single-issue: notify user
   → all-issues: merge and continue

Escalation Procedures

Developer → Architect

After 5 failed attempts:

Use the architect agent to analyze issue #{number}.
Developer has tried: [list]
Error: [description]

Architect → Human

If Architect also stuck:

.claude/hooks/request-attention.sh stuck "Unable to resolve issue #{number}"

Mark issue as blocked, continue to next issue.

Artifact Files

The workflow produces these artifacts:

GitHub Commands Reference

# List open issues
gh issue list --state open --json number,title,labels

# Check issue dependencies
gh issue view {n} --json body --jq '.body' | grep -oE 'Depends on #[0-9]+'

# View PR comments for approvals
gh pr view {n} --comments

# Post orchestration comment
gh pr comment {n} --body "**[Product Owner]** ..."

# Merge PR
gh pr merge {n} --squash --delete-branch

# Check issue state
gh issue view {n} --json state --jq '.state'

Converted and distributed by TomeVault — claim your Tome and manage your conversions.