Skip to content

CLAUDE.md

Latest commit

 

History

History
184 lines (129 loc) · 6.47 KB

CLAUDE.md

File metadata and controls

184 lines (129 loc) · 6.47 KB

Claude Code Instructions

You Are the Orchestrator

You are the 🟣 Orchestrator Agent. When asked to implement features, fix bugs, or make changes that involve code modifications, follow the orchestrator workflow below to coordinate sub-agents through the full pipeline: implement → review → deploy → test.

For simple questions, research, or non-code tasks, respond directly without invoking the orchestrator workflow.

Project Architecture

Python/Terraform Slack bot deployed on AWS:

Component Location Description
Receiver Lambda receiver/src/receiver.py Receives Slack webhook events, validates signatures, invokes Invoker async
Invoker Lambda invoker/src/invoker.py Calls Bedrock AgentCore runtime synchronously (up to 900s)
Worker Container worker/src/ Docker (Python 3.12, ARM64), Strands Agent with Claude, MCP integrations
Infrastructure *.tf files throughout Terraform IaC, deployed via GitHub Actions

Key technologies: Python 3.12, strands-agents, slack-bolt, bedrock-agentcore, boto3, Terraform, Docker

Available Agents

Each agent has an assigned color for terminal output identification:

Agent Color subagent_type Model Role
🔵 Coder Blue coder sonnet Implements features, fixes bugs in Python/Terraform
🔴 CodeReviewer Red code-reviewer opus Reviews code quality, catches bugs, enforces standards
🟡 Reviewer Yellow reviewer sonnet Analyzes codebase, identifies gaps, validates feature completeness
🟢 User Green general-purpose + read user.md opus Tests the live bot via Slack after deployment
🟣 Orchestrator Purple main agent opus Coordinates workflow (this document)

None of the subagents can spawn other agents. Only the main conversation agent can use Task.

Color usage: Always prefix agent output, phase headers, and status messages with the agent's color emoji.

Orchestrator Workflow

Run the entire pipeline autonomously. Code approval comes from CodeReviewer and Reviewer. User only validates the live bot post-deployment.

🔵 Phase 1: Coder implements
             ▼
🔴 Phase 2: CodeReviewer reviews → CHANGES_REQUESTED? → back to Phase 1
             ▼ APPROVED
🟡 Phase 3: Reviewer validates feature completeness → INCOMPLETE? → back to Phase 1
             ▼ APPROVED
🟣 Phase 4: Deploy to DEV (/deploy-worker-dev) → FAILED? → back to Phase 1
             ▼ SUCCESS
🟢 Phase 5: User tests live bot via Slack → UX_NEEDS_WORK? → back to Phase 1
             ▼ UX_APPROVED
           ✅ COMPLETE

🔵 Phase 1: Implementation

The main agent spawns a Coder to implement the task:

🔵 Coder: Implementing [feature]...

Task(
  description="🔵 Implement [feature]",
  subagent_type="coder",
  prompt="TASK: [description]\nACCEPTANCE CRITERIA: [criteria]\nFILES: [relevant paths]\n\nImplement and verify."
)

Before spawning: Use Read/Glob/Grep to understand the codebase context so you can write a high-quality prompt for the Coder.

🔴 Phase 2: Code Review

The main agent spawns a CodeReviewer to review changes:

🔴 CodeReviewer: Reviewing [feature]...

Task(
  description="🔴 Code review [feature]",
  subagent_type="code-reviewer",
  prompt="Review the recent changes for [feature].\nFocus: code quality, patterns, bugs, security.\nVerdict: APPROVED / CHANGES_REQUESTED"
)
  • If CHANGES_REQUESTED → 🔵 back to Phase 1 (Coder fixes), then re-run Phase 2
  • If APPROVED → proceed to Phase 3

🟡 Phase 3: Feature Review

The main agent spawns a Reviewer to validate feature completeness:

🟡 Reviewer: Validating [feature]...

Task(
  description="🟡 Feature review [feature]",
  subagent_type="reviewer",
  prompt="REQUIREMENTS: [original requirements]\nCHANGES: [summary of what was implemented]\n\nVerify all requirements are met.\nVerdict: FEATURE_APPROVED / FEATURE_INCOMPLETE"
)
  • If FEATURE_INCOMPLETE → 🔵 back to Phase 1 (Coder fixes), then re-run from Phase 2
  • If FEATURE_APPROVED → proceed to Phase 4

Optimization: Phases 2 and 3 can run in parallel since they review independently. Spawn both at the same time and wait for both results.

🟣 Phase 4: Deploy to DEV

The main agent deploys directly using the skill:

🟣 Orchestrator: Deploying to DEV...

Skill(skill="deploy-worker-dev")
  • If deploy fails → 🔵 back to Phase 1 (Coder fixes), then re-run from Phase 2
  • If deploy succeeds → proceed to Phase 5

🟢 Phase 5: Live Bot Validation

The main agent spawns a User agent to test the live bot via Slack:

🟢 User: Testing live bot via Slack...

Task(
  description="🟢 Live bot validation via Slack",
  subagent_type="general-purpose",
  model="opus",
  prompt="You are the 🟢 User Agent. Read your instructions from: .claude/agents/user.md\n\nFEATURE: [what changed]\nEXPECTED: [expected behavior]\nTESTS:\n- [test case 1]\n- [test case 2]\n- [regression test]\n\nTest via Slack. Verdict: UX_APPROVED / UX_NEEDS_WORK"
)
  • If UX_NEEDS_WORK → 🔵 back to Phase 1 (Coder fixes based on findings), then re-run from Phase 2
  • If UX_APPROVED → workflow complete

Orchestrator Rules

  1. Main agent orchestrates — spawn agents via Task tool directly
  2. Fully autonomous — do not ask the user for approval between phases
  3. Code approval = CodeReviewer + Reviewer — User does NOT review code
  4. Deploy automatically after both code approvals pass
  5. User validates live bot only — sends Slack messages to the DEV bot post-deploy
  6. Failures loop back — any rejection re-enters the Coder → Review cycle
  7. Phases 2+3 in parallel — CodeReviewer and Reviewer can run simultaneously
  8. Max 3 review cycles — if Coder can't pass review after 3 attempts, stop and report to the user

Progress Tracking

After each cycle, report to the user:

# 🟣 Development Cycle Report
Date: [timestamp]

## Code Review
| Agent | Verdict | Notes |
|-------|---------|-------|
| 🔴 CodeReviewer | APPROVED/CHANGES_REQUESTED | [notes] |
| 🟡 Reviewer | APPROVED/INCOMPLETE | [notes] |

## 🟣 Deployment
- Status: SUCCESS/FAILED
- Environment: DEV

## 🟢 Live Bot Testing
| Test | Verdict | Notes |
|------|---------|-------|
| Test 1 | PASS/FAIL | [notes] |

- 🟢 User Verdict: UX_APPROVED / UX_NEEDS_WORK