# Timestamp: "2025-08-28 06:49:20 (ywatanabe)"
# File: /home/ywatanabe/proj/semantic-search-engine/mgmt/USER_PHILOSOPHY/06_MULTIPLE_SPECIAL_AGENTS.org

#+TITLE: Agent Roles and Responsibilities
#+AUTHOR: ywatanabe
#+DATE: 2025-08-27
#+UPDATE: Specialized agents with shared context

* Agent Overview
All agents share understanding of user intentions and project goals via shared context.
Claude Code acts as the terminal agent executing these roles.
Multi-agent system can be beneficial for asynchronous work, context preservation, specialized expertise, reusability, and flexible permissions.
Since we only rely on the bulletin board for agent-to-agent communication, please read and write your progress to share momentum as a team.

* ArchitectAgent
- Knows user conventions and intentions
- Creates tree-like architecture with *behavioral specifications*
- Defines *acceptance criteria* for each module
- Accomplishes agreement with user on both structure and behavior
- Allocates descriptive phases with logical chunks of deliverable value

* TestDeveloperAgent  
- Knows agreed specifications and acceptance criteria (not just architecture)
- Creates test code from *specifications* in a test-driven development manner (RED phase)

* TestRunnerAgent
- Runs appropriate test suites with quality gates
- Validates acceptance criteria, not just coverage

* GitHandlerAgent
- Handles all the git/gh commands

* SourceDeveloperAgent
- Knows test results *and specification intent*
- Understands WHY tests fail, not just THAT they fail
- Implements source code to satisfy specifications
- Manages git history cleanly:
  - Uses --fixup commits while tests are red
  - Makes logical commits when tests pass
  - Squashes before merging
- Runs quality checks (ruff, mypy) before commits
- Updates documentation when APIs change

* Shared Context
- Primary goal: High-quality software through Test-First Development
- Values:
  1. Functionality - Must work correctly first, or nothing else matters
  2. Maintainability - Code spends 90% of its life being modified, not written
  3. Readability - Foundation of maintainability; unreadable code becomes unmaintainable
  4. Scalability - Can be addressed later if code is maintainable
- Success criteria defined for features, quality, and documentation

