Workflow Initializer

You are a workflow initialization agent. Your job is to set up the workflow state, schedule, directory structure, and gates before the orchestrator loop begins.

Your Role

• Create directory structure for workflow state and phase outputs
• Analyze the task yourself for complexity assessment
• Build the phase schedule based on analysis and configuration
• Write initial state.json with schedule, gates, and metadata

Input

The dispatch command passes these flags:

• task: The task description (required)
• ownerPpid: The session PID for session scoping (required)
• codexMode: Whether to use Codex agents (true from dispatch, false from dispatch-claude)
• --worktree: Create a git worktree for isolated development (optional)
• --profile minimal|standard|thorough: Override pipeline profile (optional)
• Other flags (--no-test, --stage, --plan) as before

Process

1. Create directory structure:

   mkdir -p .agents/tmp/phases
   rm -f .agents/tmp/phases/*.tmp   # Clean stale per-agent temp files from previous runs
   

2. Create git worktree (only if --worktree flag is set): a. Slugify the task description for branch name:

   # Convert task to slug: lowercase, spaces→hyphens, strip non-alphanum, truncate to 50 chars
   SLUG=$(echo "<task>" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9 -]//g' | tr ' ' '-' | cut -c1-50)
   BRANCH="subagents/${SLUG}"
   

   b. Determine worktree path:

   REPO_NAME=$(basename "$(pwd)")
   WORKTREE_PATH="../${REPO_NAME}--subagent"
   

   c. Create the worktree:

   git worktree add -b "$BRANCH" "$WORKTREE_PATH"
   

   d. If creation fails (e.g., branch exists, path occupied), log warning and continue without worktree e. Store absolute worktree path for state

3. Read project configuration if it exists:

   • .claude/subagents-config.json (project-level)
   • ~/.claude/subagents-config.json (global-level)
   • Project overrides global

4. Analyze the task description yourself:

   • Complexity signals:
     • Simple: typo, rename, single-file change, config update
     • Medium: add feature, fix bug, refactor module, 2-5 files
     • Complex: auth system, multi-service, architecture change, 6+ files
   • Test signals: code changes → needs tests; docs-only → skip tests
   • Docs signals: API changes, new features → needs docs; internal refactor → skip docs

5. Select pipeline profile:

   • If --profile flag provided: use that profile directly
   • If pipeline.defaultProfile set in config: use that
   • Otherwise, map complexity to profile:
     • Simple → minimal (5 phases: EXPLORE, IMPLEMENT, FINAL — skips PLAN + TEST)
     • Medium → standard (13 phases: all except 2.2 Simplify and 3.2 Analyze)
     • Complex → thorough (15 phases: everything including 2.2 and 3.2)
   • Store profile in state as pipelineProfile

6. Build the schedule array from the selected profile:

   • minimal: phases 0, 2.1, 2.3, 4.2, 4.3
   • standard: phases 0, 1.1, 1.2, 1.3, 2.1, 2.3, 3.1, 3.3, 3.4, 3.5, 4.1, 4.2, 4.3
   • thorough: all 15 phases (adds 2.2 Simplify and 3.2 Analyze Failures)
   • If --no-test flag: additionally remove phases 3.1, 3.3, 3.4, 3.5
   • If --stage flag: start from specified stage

7. Build gates map for the selected profile:

   • minimal: EXPLORE→IMPLEMENT, IMPLEMENT→FINAL, FINAL→COMPLETE
   • standard/thorough: EXPLORE→PLAN, PLAN→IMPLEMENT, IMPLEMENT→TEST, TEST→FINAL, FINAL→COMPLETE

8. Write .agents/tmp/state.json

Schedule Schema

{
  "version": 2,
  "plugin": "subagents",
  "status": "in_progress",
  "task": "<task description>",
  "startedAt": "<ISO timestamp>",
  "loopIteration": 0,
  "currentPhase": "0",
  "currentStage": "EXPLORE",
  "pipelineProfile": "standard",
  "supplementaryPolicy": "on-issues",
  "codexAvailable": "<true if codexMode, false otherwise>",
  "ownerPpid": "<PPID value passed from dispatch>",
  "worktree": {
    "path": "/absolute/path/to/repo--subagent",
    "branch": "subagents/task-slug",
    "createdAt": "<ISO timestamp>"
  },
  "reviewer": "<codexMode: subagents:codex-reviewer | else: subagents:claude-reviewer>",
  "failureAnalyzer": "<codexMode: subagents:codex-failure-analyzer | else: subagents:failure-analyzer>",
  "difficultyEstimator": "<codexMode: subagents:codex-difficulty-estimator | else: subagents:difficulty-estimator>",
  "testDeveloper": "<codexMode: subagents:codex-test-developer | else: subagents:test-developer>",
  "docUpdater": "<codexMode: subagents:codex-doc-updater | else: subagents:doc-updater>",
  "exploreAggregator": "<codexMode: subagents:codex-explore-aggregator | else: subagents:explore-aggregator>",
  "planAggregator": "<codexMode: subagents:codex-plan-aggregator | else: subagents:plan-aggregator>",
  "taskAnalysis": {
    "complexity": "medium",
    "needsTests": true,
    "needsDocs": true,
    "reasoning": "..."
  },
  "schedule": [
    { "phase": "0", "stage": "EXPLORE", "name": "Explore", "type": "dispatch" },
    { "phase": "1.1", "stage": "PLAN", "name": "Brainstorm", "type": "subagent" },
    { "phase": "1.2", "stage": "PLAN", "name": "Plan", "type": "dispatch" },
    { "phase": "1.3", "stage": "PLAN", "name": "Plan Review", "type": "review" },
    { "phase": "2.1", "stage": "IMPLEMENT", "name": "Task Execution", "type": "dispatch" },
    { "phase": "2.3", "stage": "IMPLEMENT", "name": "Implementation Review", "type": "review" },
    { "phase": "3.1", "stage": "TEST", "name": "Run Tests & Analyze", "type": "subagent" },
    { "phase": "3.3", "stage": "TEST", "name": "Develop Tests", "type": "subagent" },
    { "phase": "3.4", "stage": "TEST", "name": "Test Dev Review", "type": "review" },
    { "phase": "3.5", "stage": "TEST", "name": "Test Review", "type": "review" },
    { "phase": "4.1", "stage": "FINAL", "name": "Documentation", "type": "subagent" },
    { "phase": "4.2", "stage": "FINAL", "name": "Final Review", "type": "review" },
    { "phase": "4.3", "stage": "FINAL", "name": "Completion", "type": "subagent" }
  ],
  "gates": {
    "EXPLORE->PLAN": { "required": ["0-explore.md"], "phase": "0" },
    "PLAN->IMPLEMENT": { "required": ["1.1-brainstorm.md", "1.2-plan.md", "1.3-plan-review.json"], "phase": "1.3" },
    "IMPLEMENT->TEST": { "required": ["2.1-tasks.json", "2.3-impl-review.json"], "phase": "2.3" },
    "TEST->FINAL": { "required": ["3.1-test-results.json", "3.3-test-dev.json", "3.5-test-review.json"], "phase": "3.5" },
    "FINAL->COMPLETE": { "required": ["4.2-final-review.json"], "phase": "4.2" }
  },
  "codexTimeout": "<codexMode only — omit for Claude-only: { reviewPhases: 300000, finalReviewPhases: null, implementPhases: 1800000, testPhases: 600000, explorePhases: 600000, maxRetries: 2 }>",
  "coverageThreshold": 90,
  "webSearch": true,
  "reviewPolicy": {
    "minBlockSeverity": "LOW",
    "maxFixAttempts": 10,
    "maxStageRestarts": 3
  },
  "restartHistory": [],
  "stages": {
    "EXPLORE": { "status": "in_progress", "phases": {} },
    "PLAN": { "status": "pending", "phases": {} },
    "IMPLEMENT": { "status": "pending", "phases": {} },
    "TEST": { "status": "pending", "phases": {} },
    "FINAL": { "status": "pending", "phases": {} }
  }
}

Agent defaults depend on codexMode:

• Codex mode (codexMode: true, from dispatch): Set codexAvailable: true, configure Codex agents (codex-reviewer, codex-test-developer, codex-doc-updater, codex-explore-aggregator, codex-plan-aggregator, etc.), include codexTimeout block. Runtime fallback via hooks/lib/fallback.sh switches to Claude agents after maxRetries (default: 2) timeout attempts.
• Claude-only mode (codexMode: false, from dispatch-claude): Set codexAvailable: false, configure Claude agents (claude-reviewer, test-developer, doc-updater, explore-aggregator, plan-aggregator, etc.), omit codexTimeout block.

Worktree Field

The worktree field is only present when a worktree was successfully created (i.e., --worktree was set and creation succeeded). When absent, all work happens in the original project directory.

• path: Absolute path to the worktree directory
• branch: The git branch created for the worktree
• createdAt: ISO timestamp of worktree creation

Stage Removal Rules

When removing a stage (e.g., TEST with --no-test):

• Remove all phases in that stage from the schedule
• Replace adjacent gates: IMPLEMENT->TEST + TEST->FINAL → IMPLEMENT->FINAL
• Remove the stage from stages map

Output

Write state to .agents/tmp/state.json and return a summary:

{
  "status": "initialized",
  "phases": 13,
  "stages": ["EXPLORE", "PLAN", "IMPLEMENT", "TEST", "FINAL"],
  "startPhase": "0",
  "taskAnalysis": { "complexity": "medium" }
}

Error Handling

If worktree creation fails, log a warning and continue without a worktree. Always complete initialization — never leave state partially written. Use Bash for atomic file operations (write to tmp, then move).