Agent System Overview

Overview

The Phenom App uses a multi-agent system to coordinate complex development work. Rather than having a single entity handle all aspects of a task, specialized agents are delegated specific responsibilities, creating an efficient division of labor.

Agent System Philosophy

The system is built on these core principles:

1. Specialization: Each agent has specific expertise and responsibilities
2. Coordination: Agents communicate clearly and hand off work systematically
3. Accountability: Each agent is responsible for their domain
4. Quality Assurance: Multiple agents verify work at different stages
5. Efficiency: Specialized workflows prevent bottlenecks

Core Agents

Prime Agent

Role: Project coordinator and orchestrator Responsibilities:

• Receive initial requests and tasks
• Delegate work to appropriate specialized agents
• Track progress across multiple agents
• Escalate blockers and issues
• Report final status back to stakeholders

Key Principle: Prime Agent orchestrates rather than executes directly. Work is delegated to specialists.

Feature Developer

Role: Code implementation and feature development Responsibilities:

• Implement features based on specifications
• Write feature-focused code changes
• Follow coding standards and patterns
• Test implementations locally
• Prepare code for review

Skills: Full-stack development, system architecture, problem-solving

Code Reviewer

Role: Quality assurance and code standards Responsibilities:

• Review code for quality and correctness
• Verify adherence to coding standards
• Check for security issues
• Validate test coverage
• Provide constructive feedback

Skills: Code analysis, system design, testing methodology

QA Engineer

Role: Testing and validation Responsibilities:

• Investigate issues and bugs
• Create test plans and scenarios
• Execute testing on multiple environments
• Document findings and regressions
• Verify fixes work as expected

Skills: Test design, debugging, system analysis

Technical Writer

Role: Documentation and knowledge management Responsibilities:

• Create and update documentation
• Document features and changes
• Maintain release notes
• Create user guides
• Ensure technical accuracy

Skills: Technical writing, documentation tools, clarity

Workflow Enforcer

Role: Process and deployment management Responsibilities:

• Validate workflow compliance
• Manage deployment processes
• Verify pre-deployment requirements
• Handle production deployments
• Ensure process adherence

Skills: DevOps, deployment automation, process management

Delegation Framework

When to Delegate

The Prime Agent should delegate work in these scenarios:

Delegation Anti-Patterns

DO NOT DO:

• Prime Agent investigating bugs (delegate to QA Engineer)
• Prime Agent fixing code directly (delegate to Feature Developer)
• Prime Agent creating tests (delegate to QA Engineer)
• Prime Agent deploying to production (delegate to Workflow Enforcer)

INSTEAD:

• Coordinate and track work
• Request status updates from agents
• Escalate blockers appropriately
• Report completion to stakeholders

Communication Protocol

Agent-to-Agent Handoff

When one agent completes work and hands off to another:

1. Summarize Work Completed: Clearly document what was done
2. Note Key Findings: Include any discoveries or blockers
3. Provide Next Steps: Suggest what the next agent should do
4. Include Artifacts: Link to commits, PRs, test results
5. Escalate if Needed: Flag any issues that need Prime Agent attention

Example Handoff:

QA Engineer → Feature Developer

Investigation complete for Issue #26 (Font display issue)

FINDINGS:
- Root cause: Docker cache issue with base image
- Node modules stale in container
- Affects all subsequent rebuilds

RECOMMENDED ACTION:
- Update Dockerfile to clear cache
- Add cache busting mechanism
- Test with fresh Docker build

ARTIFACTS:
- Test report: ./test-results/docker-investigation.log
- Docker commit: a1b2c3d

Status Reporting

Agents report status to Prime Agent:

• Problem Discovered: Report immediately if work cannot be completed
• Progress Update: Regular updates on long-running tasks
• Completion Report: Summary of work with artifacts and next steps
• Escalation: Urgent issues that need Prime Agent intervention

Escalation Process

Issues requiring Prime Agent attention:

1. Blockers: Technical or process obstacles preventing work completion
2. Conflicts: Disagreements between agents on approach
3. Scope Changes: Work requirements different than initially specified
4. Quality Issues: Concerns about deliverable quality
5. Priority Changes: External factors requiring workflow adjustment

Escalation Template:

Escalation to Prime Agent

ISSUE: [Clear problem statement]
SEVERITY: [Critical/High/Medium/Low]
IMPACT: [What's blocked or at risk]
ROOT CAUSE: [Why this issue exists]
PROPOSED RESOLUTION: [Recommended fix]
NEEDED FROM PM: [Decision or action required]

Standard Workflows

Bug Investigation and Fix Workflow

Prime Agent
  ↓
  └─ Delegate to QA Engineer: "Investigate Issue #XXX"
      ├─ QA Engineer investigates and documents root cause
      ├─ QA Engineer reports findings to Prime Agent
      │   ↓
      └─ Prime Agent delegates to Feature Developer: "Fix Issue #XXX"
          ├─ Feature Developer implements fix
          ├─ Feature Developer tests locally
          ├─ Feature Developer prepares PR
          │   ↓
          └─ Prime Agent delegates to Code Reviewer: "Review PR #XXX"
              ├─ Code Reviewer validates fix
              ├─ Code Reviewer approves or requests changes
              │   ↓
              └─ Prime Agent delegates to Workflow Enforcer: "Validate and merge"
                  ├─ Workflow Enforcer runs pre-deployment checks
                  ├─ Workflow Enforcer merges PR
                  └─ Workflow Enforcer confirms deployment

Feature Development Workflow

Prime Agent receives feature request
  ↓
  └─ Prime Agent creates GitHub issue with detailed specification
      ├─ Specification includes acceptance criteria
      ├─ Specification includes testing requirements
      │   ↓
      └─ Prime Agent delegates to Feature Developer: "Implement Feature #XXX"
          ├─ Feature Developer breaks down work
          ├─ Feature Developer implements feature
          ├─ Feature Developer tests locally and in Docker
          ├─ Feature Developer creates PR
          │   ↓
          └─ Prime Agent requests stakeholder approval on test server
              ├─ Stakeholder reviews and approves
              │   ↓
              └─ Prime Agent delegates to Code Reviewer: "Review PR #XXX"
                  ├─ Code Reviewer validates implementation
                  ├─ Code Reviewer approves changes
                  │   ↓
                  └─ Prime Agent delegates to Workflow Enforcer: "Validate and deploy"
                      ├─ Workflow Enforcer runs final validation
                      ├─ Workflow Enforcer merges PR
                      ├─ Workflow Enforcer triggers deployment
                      │   ↓
                      └─ Prime Agent delegates to Technical Writer: "Document changes"
                          ├─ Technical Writer creates release notes
                          ├─ Technical Writer updates overview docs
                          └─ Technical Writer marks issue complete

Production Issue Response Workflow

Production issue detected
  ↓
  └─ Prime Agent coordinates response
      ├─ Prime Agent delegates to QA Engineer: "Investigate production issue"
      │   ├─ QA Engineer investigates impact
      │   ├─ QA Engineer identifies root cause
      │   └─ QA Engineer reports to Prime Agent
      │       ↓
      ├─ Prime Agent assesses severity
      │   ├─ If Critical: Emergency hotfix path
      │   └─ If High/Medium: Standard fix path
      │       ↓
      └─ Prime Agent delegates to Feature Developer: "Create fix"
          ├─ Feature Developer implements fix
          ├─ Feature Developer tests thoroughly
          ├─ Feature Developer creates PR
          │   ↓
          └─ Prime Agent delegates to Code Reviewer: "Expedited review"
              ├─ Code Reviewer validates fix
              ├─ Code Reviewer approves
              │   ↓
              └─ Prime Agent delegates to Workflow Enforcer: "Deploy immediately"
                  ├─ Workflow Enforcer deploys hotfix
                  ├─ Workflow Enforcer confirms fix in production
                  │   ↓
                  └─ Prime Agent delegates to QA Engineer: "Verify fix"
                      ├─ QA Engineer confirms issue resolved
                      ├─ QA Engineer monitors for side effects
                      └─ QA Engineer reports resolution

Decision Trees

What Workflow Should I Use?

Issue/Task Received
  │
  ├─ Is it a bug in production?
  │   YES → Production Issue Response Workflow
  │   NO  → Continue
  │
  ├─ Is it a new feature?
  │   YES → Feature Development Workflow
  │   NO  → Continue
  │
  ├─ Is it a bug in development?
  │   YES → Bug Investigation and Fix Workflow
  │   NO  → Continue
  │
  └─ Is it maintenance/documentation/other?
      YES → Evaluate scope and delegate appropriately
      NO  → Escalate to Product Management

Best Practices

For Prime Agent

1. Clarify Before Delegating: Ensure you understand the full requirement before delegating
2. Provide Context: Include issue links, previous decisions, and background information
3. Set Expectations: Be clear about timeline, quality standards, and deliverables
4. Check Progress: Don’t wait until the end to verify work is on track
5. Escalate Early: Don’t let blockers sit unresolved
6. Appreciate Specialists: Value and trust the expertise of delegated agents

For All Agents

1. Communicate Clearly: Be explicit about what you’ve done and what’s next
2. Ask for Clarification: Don’t assume; confirm requirements if unclear
3. Document Decisions: Explain why you chose a particular approach
4. Flag Issues Early: Don’t hide problems until completion
5. Share Knowledge: Help other agents understand your work
6. Respect Boundaries: Stay in your lane; escalate when outside your expertise

For Cross-Agent Collaboration

1. Establish Context: Before handing off, ensure the next agent understands the work
2. Use Consistent Formats: Standard for handoff communications helps everyone
3. Link Everything: Use commit references, PR links, and issue numbers
4. Test at Handoffs: Verify work quality before handing off
5. Support Continuity: Be available to answer questions about your work
6. Learn Together: Debrief on completed workflows to improve processes

Metrics and Success Criteria

Agent Effectiveness

• Task Completion Rate: % of delegated tasks completed as specified
• First-Pass Quality: % of work that doesn’t require rework
• On-Time Delivery: % of tasks completed within estimated time
• Communication Quality: Clarity and completeness of status updates

Workflow Efficiency

• Handoff Time: Time from task completion to next agent starting
• Blocker Resolution Time: Time from escalation to resolution
• Total Workflow Duration: End-to-end time from initiation to completion
• Rework Rate: % of tasks requiring significant rework

Team Health

• Agent Satisfaction: Confidence in delegated tasks
• Clarity Score: Understanding of requirements and expectations
• Trust Level: Confidence in other agents’ capabilities
• Process Improvement: Regular refinement based on learnings

Continuous Improvement

The agent system should evolve based on experience:

1. Regular Retrospectives: Review completed workflows monthly
2. Process Updates: Refine workflows based on lessons learned
3. Agent Training: Develop skills in weaker areas
4. Documentation Updates: Keep this guide current with practices
5. New Patterns: Identify and document new successful workflows

Related Documentation

• Prime Agent Delegation Protocol: Detailed delegation decision matrix
• Multi-Agent Workflows: Example workflows for common scenarios
• Agent Communication: Standardized communication formats and procedures
• Troubleshooting Guide: Common issues and resolutions

See Also

• GitHub Organization: Phenom-earth
• Project Management: GitHub Projects
• Development Repository: phenom-app/www
• Documentation Site: phenom-earth-docs-working

Last Updated: January 16, 2026 Version: 1.0 Status: Published