> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentsoflearning.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENT SYSTEM PLAN

# Agent-Based Development Team: Implementation Plan

## Overview

This document outlines the design and implementation of a complete agent-based software development team using Claude Code agents. Each agent represents a specialized role in the software development lifecycle, working together to deliver high-quality products from concept to deployment.

## Architecture

### Agent System Design Principles

1. **Single Responsibility**: Each agent has a clearly defined role
2. **User Confirmation**: All agents must confirm with user before adopting changes
3. **Handoff Protocol**: Clear workflows for passing work between agents
4. **Tool Access**: Each agent has access to appropriate tools for their role
5. **Collaboration**: Agents reference each other's outputs and build incrementally

### Agent Storage Structure

```
.claude/agents/
├── product/
│   ├── chief-product-officer.md
│   ├── senior-product-manager.md
│   └── marketer.md
├── design/
│   ├── ux-designer.md
│   └── product-designer.md
├── engineering/
│   ├── software-architect.md
│   ├── dba.md
│   ├── frontend-developer.md
│   └── backend-developer.md
├── quality/
│   ├── app-security-engineer.md
│   └── senior-qa-engineer.md
└── operations/
    └── devops-engineer.md
```

## Agent Specifications

### 1. Chief Product Officer (CPO)

**Role**: Strategic product vision and roadmap

**Responsibilities:**

* Define product vision and strategy
* Create high-level product roadmaps
* Identify market opportunities
* Prioritize features and initiatives
* Align product with business goals

**Tools**: Read, Write, Grep, Glob, WebSearch

**Inputs**: Market research, user feedback, business objectives

**Outputs**: Product vision documents, strategic roadmaps, OKRs

**Handoff to**: Sr Product Manager

***

### 2. Senior Product Manager (Sr PM)

**Role**: Detailed product requirements and specifications

**Responsibilities:**

* Write comprehensive PRDs (Product Requirements Documents)
* Define user stories and acceptance criteria
* Create feature specifications
* Manage stakeholder requirements
* Prioritize backlog items

**Tools**: Read, Write, Edit, Grep, Glob

**Inputs**: Product vision from CPO, user research

**Outputs**: PRDs, user stories, acceptance criteria, feature specs

**Handoff to**: UX Designer, Software Architect

***

### 3. Marketer

**Role**: Brand identity and visual strategy

**Responsibilities:**

* Define brand identity and guidelines
* Create color palettes and visual themes
* Develop marketing messaging
* Design brand assets
* Ensure brand consistency

**Tools**: Read, Write, Edit, WebSearch

**Inputs**: Product vision, target audience

**Outputs**: Brand guidelines, color palettes, design tokens, messaging frameworks

**Handoff to**: UX Designer, Product Designer

***

### 4. UX Designer

**Role**: User experience and design systems

**Responsibilities:**

* Build comprehensive style guides
* Create design systems and component libraries
* Define interaction patterns
* Establish accessibility standards
* Document UX principles

**Tools**: Read, Write, Edit, Grep, Glob

**Inputs**: Brand guidelines from Marketer, PRD from Sr PM

**Outputs**: Style guides, design systems, component specifications, UX patterns

**Handoff to**: Product Designer

***

### 5. Product Designer

**Role**: High-fidelity UI designs

**Responsibilities:**

* Create detailed UI designs
* Design user interfaces following style guide
* Produce design specifications for developers
* Create design assets and mockups
* Ensure design-to-code fidelity

**Tools**: Read, Write, Edit, Grep, Glob

**Inputs**: Style guide from UX Designer, PRD requirements

**Outputs**: UI specifications, component designs, design assets, design documentation

**Handoff to**: Frontend Developer

***

### 6. Software Architect

**Role**: Technical architecture and implementation strategy

**Responsibilities:**

* Design system architecture
* Make tech stack decisions
* Create implementation plans
* Define API contracts
* Create and manage Linear tickets
* Document architectural decisions

**Tools**: Read, Write, Edit, Grep, Glob, Bash

**Inputs**: PRD from Sr PM, UI designs

**Outputs**: Architecture diagrams, tech stack documentation, implementation plans, Linear tickets

**Handoff to**: DBA, Frontend Developer, Backend Developer

***

### 7. Database Administrator (DBA)

**Role**: Database design and management

**Responsibilities:**

* Design database schemas
* Configure MongoDB/Supabase
* Optimize queries and indexes
* Manage data migrations
* Set up database security
* Use MCP tools for database operations

**Tools**: Read, Write, Edit, Bash, MCP (MongoDB, Supabase)

**Inputs**: Architecture from Software Architect, data requirements from PRD

**Outputs**: Database schemas, migration scripts, database configuration, data models

**Handoff to**: Backend Developer

***

### 8. Frontend Developer

**Role**: UI implementation specialist

**Responsibilities:**

* Implement UI designs in code
* Build reusable components
* Ensure responsive design
* Optimize frontend performance
* Integrate with backend APIs
* Ensure accessibility compliance

**Tools**: Read, Write, Edit, Grep, Glob, Bash

**Inputs**: UI designs from Product Designer, architecture from Software Architect

**Outputs**: Frontend code, components, styles, integration with APIs

**Handoff to**: App Security Engineer, Sr QA Engineer

***

### 9. Backend Developer

**Role**: Server-side implementation expert

**Responsibilities:**

* Implement backend logic and APIs
* Build database integrations
* Implement authentication/authorization
* Create API endpoints
* Write backend tests
* Optimize server performance

**Tools**: Read, Write, Edit, Grep, Glob, Bash

**Inputs**: Architecture from Software Architect, database schema from DBA

**Outputs**: Backend code, API implementations, server logic, integration tests

**Handoff to**: App Security Engineer, Sr QA Engineer

***

### 10. App Security Engineer

**Role**: Security scanning and code review

**Responsibilities:**

* Review commits for security issues
* Run code scanning before push
* Perform secret scanning
* Execute vulnerability scanning
* Use secure-push skill for automated checks
* Provide security recommendations

**Tools**: Read, Grep, Glob, Bash, Skill (secure-push)

**Inputs**: Code from Frontend/Backend developers

**Outputs**: Security scan reports, vulnerability findings, remediation recommendations

**Handoff to**: Sr QA Engineer (after security approval)

***

### 11. Senior QA Engineer

**Role**: Quality assurance and testing

**Responsibilities:**

* Write comprehensive test plans
* Execute integration testing
* Use Playwright MCP for E2E tests
* Perform regression testing
* Document test cases
* Report bugs and issues

**Tools**: Read, Write, Edit, Bash, MCP (Playwright)

**Inputs**: Code from developers, test requirements from PRD

**Outputs**: Test plans, test results, bug reports, test automation scripts

**Handoff to**: DevOps Engineer (after QA approval)

***

### 12. DevOps Engineer

**Role**: Infrastructure and deployment

**Responsibilities:**

* Write infrastructure as code
* Set up CI/CD pipelines
* Configure cloud resources
* Manage deployments
* Monitor production systems
* Implement observability

**Tools**: Read, Write, Edit, Bash, Grep, Glob

**Inputs**: Architecture from Software Architect, tested code

**Outputs**: IaC scripts, CI/CD configurations, deployment procedures, monitoring setup

**Final Output**: Production deployment

***

## Workflow Orchestration

### Development Lifecycle Flow

```
1. CPO defines vision
   ↓
2. Sr PM writes PRD
   ↓
3. Marketer creates brand guidelines (parallel)
   UX Designer builds style guide (parallel)
   ↓
4. Product Designer creates UI designs
   ↓
5. Software Architect designs architecture
   ↓
6. DBA designs database (parallel)
   Frontend Developer builds UI (parallel)
   Backend Developer builds APIs (parallel)
   ↓
7. App Security Engineer scans code
   ↓
8. Sr QA Engineer tests application
   ↓
9. DevOps Engineer deploys to production
```

### User Confirmation Protocol

Every agent MUST follow this pattern:

```markdown theme={null}
## Proposed Changes

[Agent describes what they plan to do]

### Artifacts to be created/modified:
- file1.ext
- file2.ext

### Rationale:
[Why these changes are needed]

---

**Do you approve these changes? (Y/n)**
```

Only after user confirmation can the agent proceed with implementation.

### Handoff Protocol

When an agent completes their work:

```markdown theme={null}
## Work Complete ✓

### Deliverables:
- [List of completed artifacts]

### Next Steps:
**Ready for handoff to: [Next Agent Name]**

To invoke next agent: `@[agent-name]`

### Notes for next agent:
- [Important context]
- [Key decisions made]
- [Any blockers or considerations]
```

## Agent Collaboration Patterns

### Information Sharing

Agents reference each other's work through:

* Reading artifact files (PRDs, designs, code, etc.)
* Following naming conventions
* Using consistent directory structures
* Documenting decisions

### Conflict Resolution

When agents have conflicting requirements:

1. Agent raises concern to user
2. User decides priority/approach
3. Affected agents update their artifacts
4. Changes are documented

### Parallel Work

Some agents can work in parallel:

* Marketer + UX Designer (design phase)
* DBA + Frontend + Backend (implementation phase)
* Security + QA (validation phase)

## Tool Access Matrix

| Agent              | Read | Write | Edit | Grep | Glob | Bash | Skill           | MCP            | WebSearch |
| ------------------ | ---- | ----- | ---- | ---- | ---- | ---- | --------------- | -------------- | --------- |
| CPO                | ✓    | ✓     | -    | ✓    | ✓    | -    | -               | -              | ✓         |
| Sr PM              | ✓    | ✓     | ✓    | ✓    | ✓    | -    | -               | -              | -         |
| Marketer           | ✓    | ✓     | ✓    | -    | -    | -    | -               | -              | ✓         |
| UX Designer        | ✓    | ✓     | ✓    | ✓    | ✓    | -    | -               | -              | -         |
| Product Designer   | ✓    | ✓     | ✓    | ✓    | ✓    | -    | -               | -              | -         |
| Software Architect | ✓    | ✓     | ✓    | ✓    | ✓    | ✓    | -               | -              | -         |
| DBA                | ✓    | ✓     | ✓    | -    | -    | ✓    | -               | ✓ (DB)         | -         |
| Frontend Dev       | ✓    | ✓     | ✓    | ✓    | ✓    | ✓    | -               | -              | -         |
| Backend Dev        | ✓    | ✓     | ✓    | ✓    | ✓    | ✓    | -               | -              | -         |
| App Security       | ✓    | -     | -    | ✓    | ✓    | ✓    | ✓ (secure-push) | -              | -         |
| Sr QA              | ✓    | ✓     | ✓    | -    | -    | ✓    | -               | ✓ (Playwright) | -         |
| DevOps             | ✓    | ✓     | ✓    | ✓    | ✓    | ✓    | -               | -              | -         |

## Directory Structure Standards

### Product Documents

```
docs/product/
├── vision/
│   └── product-vision-YYYY-MM.md
├── prds/
│   └── feature-name-prd.md
└── roadmaps/
    └── roadmap-YYYY-QN.md
```

### Design Assets

```
docs/design/
├── brand/
│   ├── brand-guidelines.md
│   └── color-palettes.md
├── ux/
│   ├── style-guide.md
│   └── design-system.md
└── ui/
    └── feature-name-ui-spec.md
```

### Architecture Documents

```
docs/architecture/
├── system-design.md
├── tech-stack.md
├── api-contracts/
│   └── api-name.yaml
└── adrs/
    └── NNNN-decision-title.md
```

### Database Documentation

```
docs/database/
├── schemas/
│   └── collection-name.json
├── migrations/
│   └── YYYYMMDD-migration-name.sql
└── data-models.md
```

### Code Structure

```
src/
├── frontend/
│   ├── components/
│   ├── pages/
│   └── styles/
├── backend/
│   ├── api/
│   ├── services/
│   └── models/
└── shared/
    └── types/
```

### Testing

```
tests/
├── unit/
├── integration/
├── e2e/
│   └── playwright/
└── security/
    └── secure-push-reports/
```

### Infrastructure

```
infra/
├── terraform/
├── kubernetes/
├── ci-cd/
└── monitoring/
```

## Success Metrics

### Agent Effectiveness

* Time from vision to deployment
* Number of revisions needed per phase
* User satisfaction with outputs
* Quality of handoffs between agents

### Quality Gates

* All PRDs approved by user
* Security scans passing
* All tests passing
* Infrastructure validated

### Process Metrics

* Adherence to user confirmation protocol
* Documentation completeness
* Artifact reusability
* Parallel work efficiency

## Implementation Phases

### Phase 1: Product & Design (Agents 1-5)

Create CPO, Sr PM, Marketer, UX Designer, Product Designer

### Phase 2: Architecture & Database (Agents 6-7)

Create Software Architect, DBA

### Phase 3: Development (Agents 8-9)

Create Frontend Developer, Backend Developer

### Phase 4: Quality & Operations (Agents 10-12)

Create App Security Engineer, Sr QA Engineer, DevOps Engineer

## Agent Model Selection

All agents use `model: inherit` by default, which uses the conversation's model (Sonnet 4.5).

For specialized needs:

* **CPO, Sr PM**: Use Sonnet for strategic thinking
* **Marketer, Designers**: Use Sonnet for creative work
* **Software Architect**: Use Sonnet for complex architecture
* **Developers**: Can use Haiku for simple, well-defined tasks
* **Security, QA**: Use Sonnet for thorough analysis
* **DevOps**: Use Sonnet for infrastructure decisions

## Integration with Existing Skills

### Secure-Push Skill Integration

The App Security Engineer agent will:

1. Invoke the secure-push skill before code reviews
2. Read scan reports from `.claude/skills/secure-push/`
3. Interpret findings and provide recommendations
4. Block merges if Critical/High issues found

### MCP Tool Integration

**DBA Agent**:

* MongoDB MCP server for database operations
* Supabase MCP server for managed database

**Sr QA Engineer**:

* Playwright MCP server for E2E testing
* Test execution and reporting

## Best Practices

### Agent Prompting

* Be specific about expected outputs
* Include examples of good deliverables
* Reference relevant documentation
* Specify file formats and naming conventions

### User Interaction

* Always show proposed changes before executing
* Provide clear rationale for decisions
* Offer alternatives when appropriate
* Document all user decisions

### Documentation

* Every agent creates artifacts in standard locations
* Use consistent naming conventions
* Include timestamps and version info
* Cross-reference related documents

### Error Handling

* Agents should validate inputs before proceeding
* Clearly communicate blockers to user
* Provide actionable next steps
* Don't make assumptions without confirmation

## Maintenance and Evolution

### Adding New Agents

1. Define role and responsibilities
2. Identify required tools
3. Map workflow and handoffs
4. Create agent file following format
5. Test with other agents
6. Document in this plan

### Updating Agents

1. Review agent performance
2. Gather user feedback
3. Update agent instructions
4. Test changes
5. Version control updates

### Agent Versioning

Use semantic versioning in agent descriptions:

```markdown theme={null}
description: [Role] v1.2.0 - [Brief description]
```

***

**Status**: Ready for implementation
**Last Updated**: 2025-11-09
**Version**: 1.0.0