Implement

---
description: Bash development workflow - explore, plan (4 perspectives), implement, review, test, iterate until success
allowed-tools: Task, Read, Glob, Grep, TodoWrite, AskUserQuestion, Edit, Write
argument-hint: <feature-or-task-description>
---

# Role: Orchestrator

You coordinate specialized agents in parallel waves for Bash/shell script development. Launch paired writer/tester agents simultaneously to prevent reward hacking.

## Critical Constraints

- **FORBIDDEN**: NotebookEdit, WebFetch, WebSearch
- **STRONGLY DISCOURAGED**: Edit, Write - use agents instead (see exceptions below)
- **REQUIRED**: Delegate implementation work to agents via Task tool
- **REQUIRED**: Execute agents in parallel waves when possible
- **REQUIRED**: Track progress with TodoWrite
- **REQUIRED**: Launch bash-script-architect + bash-tdd-architect TOGETHER (prevents reward hacking)
- **REQUIRED**: Always run 4 Plan agents in Wave 1b (Implementation, Testing, Security, DevOps perspectives)

## Direct Edit Exceptions

Edit/Write tools are available but **strongly discouraged**. Prefer agent delegation.

**Acceptable uses for direct edits:**
- Trivial fixes (typos, single-line changes, import ordering)
- Config file tweaks during iteration
- Quick fixes identified by devops-infra-lead that don't warrant full agent cycle

**NOT acceptable for direct edits:**
- Main implementation (use bash-script-architect)
- Test writing (use bash-tdd-architect)
- Any change requiring review consideration
- Multi-file changes

**Rule of thumb:** If you're unsure whether to edit directly, use an agent.

## Parallel Wave Structure

Wave 1a: [Explore agent]

• Identify files to modify/create
• Build dependency graph
• Break task into features with specific behaviors
• Output to ~/.claude/bash-workflow/explorer-findings.md

Wave 1b: [4 Plan agents IN PARALLEL] - different perspectives

• Plan (Implementation): Structure, patterns, dependencies
• Plan (Testing): Edge cases, failure modes, bats test strategy
• Plan (Security): Input validation, permissions, secrets
• Plan (DevOps): Portability (macOS/Linux), CI/CD, deployment
• Synthesize into unified approach in ~/.claude/bash-workflow/unified-plan.md

Wave 2: For each dependency group (processed sequentially):

• [N bash-script-architect agents] - one per file in group, run in parallel
• [M bash-tdd-architect agents] - one per feature touching group, run in parallel
• Wait for all agents before proceeding to next group

Wave 3: [1 devops-infra-lead + 1 bash-test-runner] IN PARALLEL

• bash-test-runner: shellcheck + bats tests
• devops-infra-lead: reviews ALL code and tests
• Returns: [PASS] | [FAIL] + failures | [NEEDS_CHANGES] + issues | [ERROR] + setup issues

Wave 4: [git-ops agent] - only on [PASS]

## Fallback Heuristics

Orchestrator decides when to use per-file parallelization vs simpler approach:

| Condition | Approach |
|-----------|----------|
| 1 file, trivial change | Direct edit (no agents) |
| 1-2 files, straightforward | Simple mode: 1 writer + 1 tester for whole task |
| 3+ files OR complex dependencies | Per-file parallel writers |
| Multiple features spanning files | Feature-based parallel testers |

## Execution Flow

1. **Initialize**: Create todo list with task breakdown
2. **Wave 1a**: Launch Explore agent to understand codebase and build dependency graph
3. **Wave 1b**: Launch 4 Plan agents in parallel (Implementation, Testing, Security, DevOps)
4. **Synthesize**: Combine perspectives into unified-plan.md
5. **Wave 2**: For each dependency group (sequentially):
   - Launch N bash-script-architect agents (one per file in group) in SINGLE message
   - Launch M bash-tdd-architect agents (one per feature touching group) in SAME message
   - Wait for all agents in group to complete
6. **Wave 3**: Launch devops-infra-lead AND bash-test-runner in SINGLE message
7. **Verdict**: Process verdict ([PASS] + [PASS] | [FAIL] | [NEEDS_CHANGES] | [ERROR])
8. **Loop**: If not approved, synthesize feedback and return to Wave 2
9. **Git**: Launch git-ops agent on success

## Agent Prompts

### Explore Agent

Analyze codebase for: {TASK}

Find:

• Relevant shell scripts and their dependencies
• Existing patterns and conventions (set -euo pipefail, function patterns)
• Test locations (test/*.bats, *.bats files)
• Platform considerations (macOS vs Linux specifics)

Output to ~/.claude/bash-workflow/explorer-findings.md with this structure:

Files

Path	Action	Group	Notes
scripts/sync.sh	modify	1	Entry point
scripts/lib/utils.sh	create	1	Helper functions
scripts/backup.sh	modify	2	Depends on utils.sh

Group assignment rules:

• Group 1: Files with no dependencies on other modified files
• Group N+1: Files that depend on files in group N
• Files in same group can be written in parallel

Features

Feature: {name}

• Files: [list of files involved]
• Behaviors:
  • {behavior 1}
  • {behavior 2}

### Plan Agent (Implementation Perspective)

Design implementation approach for: {TASK}

Based on exploration findings: {EXPLORER_SUMMARY}

Focus on:

• Script structure and organization
• Function decomposition
• Dependencies between components
• Reusable patterns from codebase

Output implementation design to ~/.claude/bash-workflow/plan-implementation.md

### Plan Agent (Testing Perspective)

Design test strategy for: {TASK}

Based on exploration findings: {EXPLORER_SUMMARY}

Focus on:

• Behaviors to verify with bats tests
• Edge cases: empty input, missing files, bad permissions, signals
• Error paths and failure modes
• Platform-specific test considerations

Output test strategy to ~/.claude/bash-workflow/plan-testing.md

### Plan Agent (Security Perspective)

Analyze security considerations for: {TASK}

Based on exploration findings: {EXPLORER_SUMMARY}

Focus on:

• Input validation requirements
• Permission handling (file modes, sudo usage)