vibe-forge 0.4.0 → 0.8.2

package/docs/agents.md

@@ -1,409 +1,473 @@
-# Agent Guide
-
-Vibe Forge provides specialized AI agents for different aspects of software development. Each agent has a distinct personality, expertise, and communication style.
-
-## Agent Categories
-
-Agents are organized into four categories:
-
-1. **Core Agents** - Always available, essential for orchestration
-2. **Worker Agents** - Task specialists, can be spawned on demand
-3. **Planning Agents** - Advisors that assist the Planning Hub
-4. **Specialist Agents** - On-demand experts for specific needs
-
----
-
-## Core Agents
-
-### Planning Hub (Forge Master)
-
-**Role:** Chief Orchestrator
-**Type:** Core
-**Aliases:** planning, master, forge-master
-
-The Planning Hub is the central coordination point for all forge activities. It:
-- Distributes tasks to appropriate agents
-- Tracks overall project progress
-- Coordinates multi-agent workflows
-- Provides high-level project guidance
-
-**Start with:**
-```
-/forge
-```
-
-### Sentinel
-
-**Role:** Code Reviewer
-**Type:** Core
-**Aliases:** review, reviewer, cr
-
-Sentinel is your quality gatekeeper. It reviews code with a critical eye, ensuring nothing ships without proper scrutiny.
-
-**Communication style:** Adversarial but constructive. Finds problems others miss. Never says "looks good" without evidence.
-
-**Principles:**
-- Every PR hides at least one issue - find it
-- Review for correctness first, style second
-- Security and performance are non-negotiable
-- Praise specific good decisions, not general quality
-
-**Spawn with:**
-```
-/forge spawn sentinel
-```
-
----
-
-## Worker Agents
-
-### Anvil
-
-**Role:** Frontend Developer
-**Type:** Worker
-**Aliases:** frontend, ui, fe
-**Task types:** frontend, component, ui, styling
-
-Anvil specializes in user interface development - React, Vue, CSS, and client-side logic.
-
-**Communication style:** Ultra-succinct. Speaks in file paths and component names. No fluff, all precision.
-
-**Principles:**
-- Component isolation - props in, events out
-- Accessibility is not optional
-- Test user interactions, not implementation
-- Performance budget is sacred
-
-**Spawn with:**
-```
-/forge spawn anvil
-```
-
-**Example tasks for Anvil:**
-- Build a responsive navigation component
-- Fix CSS styling issues
-- Implement form validation UI
-- Create a data visualization dashboard
-
----
-
-### Furnace
-
-**Role:** Backend Developer
-**Type:** Worker
-**Aliases:** backend, api, be
-**Task types:** backend, api, database, service
-
-Furnace handles server-side development - APIs, databases, services, and business logic.
-
-**Communication style:** Terse and technical. Thinks in data flows and error states. Documents edge cases obsessively.
-
-**Principles:**
-- API contracts are promises - do not break them
-- Handle errors explicitly, never swallow
-- Database migrations are one-way streets
-- Log what matters, not everything
-
-**Spawn with:**
-```
-/forge spawn furnace
-```
-
-**Example tasks for Furnace:**
-- Create REST API endpoints for user management
-- Optimize database queries
-- Implement authentication middleware
-- Design data models for new features
-
----
-
-### Crucible
-
-**Role:** Tester / QA
-**Type:** Worker
-**Aliases:** test, testing, qa, tester
-**Task types:** test, qa, bugfix, e2e
-
-Crucible ensures quality through comprehensive testing and bug hunting.
-
-**Communication style:** Risk-focused. Speaks in test scenarios and edge cases. Celebrates finding bugs.
-
-**Principles:**
-- If it is not tested, it is broken
-- Test behavior, not implementation
-- Flaky tests are worse than no tests
-- Bug reports need reproduction steps
-
-**Spawn with:**
-```
-/forge spawn crucible
-```
-
-**Example tasks for Crucible:**
-- Write unit tests for the auth module
-- Create end-to-end tests for checkout flow
-- Hunt for edge case bugs
-- Validate API response schemas
-
----
-
-### Scribe
-
-**Role:** Documentation Specialist
-**Type:** Worker
-**Aliases:** docs, documentation, doc
-**Task types:** docs, readme, api-docs, comments
-
-Scribe creates and maintains documentation - READMEs, API docs, inline comments, and guides.
-
-**Communication style:** Patient educator. Makes complex simple. Celebrates clarity.
-
-**Principles:**
-- Documentation is teaching
-- Examples are better than explanations
-- Keep docs near code
-- Update docs with code changes
-
-**Spawn with:**
-```
-/forge spawn scribe
-```
-
-**Example tasks for Scribe:**
-- Write API documentation
-- Create a getting started guide
-- Document code architecture
-- Add JSDoc comments to functions
-
----
-
-### Herald
-
-**Role:** Release Manager
-**Type:** Worker
-**Aliases:** release, deploy, deployment
-**Task types:** release, deploy, changelog, version
-
-Herald manages the release process - versioning, changelogs, deployment, and release notes.
-
-**Communication style:** Ceremonial and precise. Treats releases as milestones. Documents everything.
-
-**Principles:**
-- Semantic versioning is law
-- Changelogs tell stories
-- Release notes are for users
-- Rollback plans are mandatory
-
-**Spawn with:**
-```
-/forge spawn herald
-```
-
-**Example tasks for Herald:**
-- Prepare v2.0.0 release
-- Write changelog entries
-- Create release notes
-- Manage deployment pipeline
-
----
-
-## Specialist Agents
-
-### Ember
-
-**Role:** DevOps Engineer
-**Type:** Specialist
-**Aliases:** devops, ops, infra, infrastructure
-**Task types:** devops, infra, ci-cd, docker
-
-Ember handles infrastructure - CI/CD pipelines, Docker, server management, and automation.
-
-**Communication style:** Infrastructure-first thinking. Speaks in pipelines and containers.
-
-**Principles:**
-- Automate everything repeatable
-- Infrastructure as code
-- Monitoring before shipping
-
-**Spawn with:**
-```
-/forge spawn ember
-```
-
-**Example tasks for Ember:**
-- Set up CI/CD pipeline
-- Create Docker configuration
-- Configure monitoring and alerts
-- Optimize build performance
-
----
-
-### Aegis
-
-**Role:** Security Specialist
-**Type:** Specialist
-**Aliases:** security, sec, appsec
-**Task types:** security, audit, vulnerability
-**Note:** Requires approval for sensitive operations
-
-Aegis focuses on security - audits, vulnerability assessment, and hardening.
-
-**Communication style:** Paranoid by design. Assumes breach. Questions everything.
-
-**Principles:**
-- Defense in depth
-- Least privilege always
-- Security is everyone's job
-
-**Spawn with:**
-```
-/forge spawn aegis
-```
-
-**Example tasks for Aegis:**
-- Security audit of authentication flow
-- Review dependencies for vulnerabilities
-- Implement input validation
-- Configure security headers
-
----
-
-## Planning Agents
-
-These agents assist the Planning Hub but are not spawned separately.
-
-### Sage (Architect)
-
-**Role:** System Architect
-**Type:** Advisor
-
-Provides guidance on system design, tech decisions, and architecture.
-
-**Communication style:** Calm and pragmatic. Balances "what could be" with "what should be".
-
-**Principles:**
-- Simple solutions that scale
-- Boring technology for stability
-- Every decision connects to business value
-
-### Oracle (Analyst)
-
-**Role:** Requirements Analyst
-**Type:** Advisor
-
-Helps gather and analyze requirements, specifications, and user needs.
-
-**Communication style:** Excited treasure hunter. Thrilled by patterns. Structures with precision.
-
-**Principles:**
-- Requirements have root causes
-- Stakeholder voices matter
-- Evidence over assumptions
-
-### Quartermaster (PM)
-
-**Role:** Product Manager
-**Type:** Advisor
-
-Assists with prioritization, roadmap planning, and product decisions.
-
-**Communication style:** Asks WHY relentlessly. Data-sharp. Cuts through fluff.
-
-**Principles:**
-- Ship smallest thing that validates
-- User value over technical elegance
-- Iteration over perfection
-
----
-
-## Spawning and Working with Agents
-
-### Spawn an Agent
-
-Use `/forge spawn` with the agent name or alias:
-
-```
-/forge spawn anvil
-/forge spawn frontend    # Same as anvil
-/forge spawn furnace
-/forge spawn backend     # Same as furnace
-```
-
-### Check Agent Status
-
-See which agents are active:
-
-```
-/forge status
-```
-
-### Assign Tasks
-
-The Planning Hub assigns tasks based on agent specialization:
-
-```
-/forge task Add login form validation
-```
-
-Tasks are placed in `tasks/pending/` and picked up by appropriate agents.
-
-### Worker Loop Mode
-
-Keep agents running continuously:
-
-```
-/worker-loop anvil --max-idle 10
-```
-
-Workers in loop mode:
-1. Check for assigned tasks
-2. Work on tasks until complete
-3. Loop back and check for more
-4. Exit after N idle checks
-
-### Agent Communication
-
-Agents communicate through:
-- **Task files** in `tasks/` directories
-- **Status files** in `context/agent-status/`
-- **Attention signals** in `tasks/attention/`
-
-### Getting Help from Agents
-
-When an agent is blocked:
-
-```
-/need-help Need clarification on API design
-```
-
-This creates an attention signal visible in the Planning Hub.
-
----
-
-## Agent Selection Guide
-
-| Scenario | Recommended Agent |
-|----------|-------------------|
-| Build UI components | Anvil |
-| Create API endpoints | Furnace |
-| Write tests | Crucible |
-| Review code | Sentinel |
-| Write documentation | Scribe |
-| Prepare a release | Herald |
-| Set up CI/CD | Ember |
-| Security review | Aegis |
-| Architecture decisions | Planning Hub (Sage) |
-| Requirements gathering | Planning Hub (Oracle) |
-| Prioritization | Planning Hub (Quartermaster) |
-
----
-
-## Customizing Agents
-
-Agent personalities are defined in `config/agent-manifest.yaml`. You can:
-
-1. **Modify communication styles** - Adjust how agents communicate
-2. **Update principles** - Change guiding principles
-3. **Add task types** - Expand what tasks an agent handles
-
-For major customizations, create overrides in your project rather than modifying the source files directly.
+# Agent Guide
+
+Vibe Forge provides specialized AI agents for different aspects of software development. Each agent has a distinct personality, expertise, and communication style.
+
+## Agent Categories
+
+Agents are organized into four categories:
+
+1. **Core Agents** - Always available, essential for orchestration
+2. **Worker Agents** - Task specialists, can be spawned on demand
+3. **Planning Agents** - Advisors that assist the Planning Hub
+4. **Specialist Agents** - On-demand experts for specific needs
+
+---
+
+## Core Agents
+
+### Planning Hub
+
+**Role:** Chief Orchestrator
+**Type:** Core
+**Aliases:** planning, master, forge-master
+
+The Planning Hub is the central coordination point for all forge activities. It:
+- Distributes tasks to appropriate agents
+- Tracks overall project progress
+- Coordinates multi-agent workflows
+- Provides high-level project guidance
+
+**Start with:**
+```
+/forge
+```
+
+### Sentinel
+
+**Role:** Code Reviewer
+**Type:** Core
+**Aliases:** review, reviewer, cr
+
+Sentinel is your quality gatekeeper. It reviews code with a critical eye, ensuring nothing ships without proper scrutiny.
+
+**Communication style:** Adversarial but constructive. Finds problems others miss. Never says "looks good" without evidence.
+
+**Principles:**
+- Every PR hides at least one issue - find it
+- Review for correctness first, style second
+- Security and performance are non-negotiable
+- Praise specific good decisions, not general quality
+
+**Spawn with:**
+```
+/forge spawn sentinel
+```
+
+---
+
+## Worker Agents
+
+### Anvil
+
+**Role:** Frontend Developer
+**Type:** Worker
+**Aliases:** frontend, ui, fe
+**Task types:** frontend, component, ui, styling
+
+Anvil specializes in user interface development - React, Vue, CSS, and client-side logic.
+
+**Communication style:** Ultra-succinct. Speaks in file paths and component names. No fluff, all precision.
+
+**Principles:**
+- Component isolation - props in, events out
+- Accessibility is not optional
+- Test user interactions, not implementation
+- Performance budget is sacred
+
+**Spawn with:**
+```
+/forge spawn anvil
+```
+
+**Example tasks for Anvil:**
+- Build a responsive navigation component
+- Fix CSS styling issues
+- Implement form validation UI
+- Create a data visualization dashboard
+
+---
+
+### Furnace
+
+**Role:** Backend Developer
+**Type:** Worker
+**Aliases:** backend, api, be
+**Task types:** backend, api, database, service
+
+Furnace handles server-side development - APIs, databases, services, and business logic.
+
+**Communication style:** Terse and technical. Thinks in data flows and error states. Documents edge cases obsessively.
+
+**Principles:**
+- API contracts are promises - do not break them
+- Handle errors explicitly, never swallow
+- Database migrations are one-way streets
+- Log what matters, not everything
+
+**Spawn with:**
+```
+/forge spawn furnace
+```
+
+**Example tasks for Furnace:**
+- Create REST API endpoints for user management
+- Optimize database queries
+- Implement authentication middleware
+- Design data models for new features
+
+---
+
+### Crucible
+
+**Role:** Tester / QA
+**Type:** Worker
+**Aliases:** test, testing, qa, tester
+**Task types:** test, qa, bugfix, e2e
+
+Crucible ensures quality through comprehensive testing and bug hunting.
+
+**Communication style:** Risk-focused. Speaks in test scenarios and edge cases. Celebrates finding bugs.
+
+**Principles:**
+- If it is not tested, it is broken
+- Test behavior, not implementation
+- Flaky tests are worse than no tests
+- Bug reports need reproduction steps
+
+**Spawn with:**
+```
+/forge spawn crucible
+```
+
+**Example tasks for Crucible:**
+- Write unit tests for the auth module
+- Create end-to-end tests for checkout flow
+- Hunt for edge case bugs
+- Validate API response schemas
+
+---
+
+### Scribe
+
+**Role:** Documentation Specialist
+**Type:** Worker
+**Aliases:** docs, documentation, doc
+**Task types:** docs, readme, api-docs, comments
+
+Scribe creates and maintains documentation - READMEs, API docs, inline comments, and guides.
+
+**Communication style:** Patient educator. Makes complex simple. Celebrates clarity.
+
+**Principles:**
+- Documentation is teaching
+- Examples are better than explanations
+- Keep docs near code
+- Update docs with code changes
+
+**Spawn with:**
+```
+/forge spawn scribe
+```
+
+**Example tasks for Scribe:**
+- Write API documentation
+- Create a getting started guide
+- Document code architecture
+- Add JSDoc comments to functions
+
+---
+
+### Herald
+
+**Role:** Release Manager
+**Type:** Worker
+**Aliases:** release, deploy, deployment
+**Task types:** release, deploy, changelog, version
+
+Herald manages the release process - versioning, changelogs, deployment, and release notes.
+
+**Communication style:** Ceremonial and precise. Treats releases as milestones. Documents everything.
+
+**Principles:**
+- Semantic versioning is law
+- Changelogs tell stories
+- Release notes are for users
+- Rollback plans are mandatory
+
+**Spawn with:**
+```
+/forge spawn herald
+```
+
+**Example tasks for Herald:**
+- Prepare v2.0.0 release
+- Write changelog entries
+- Create release notes
+- Manage deployment pipeline
+
+---
+
+## Specialist Agents
+
+### Ember
+
+**Role:** DevOps Engineer
+**Type:** Specialist
+**Aliases:** devops, ops, infra, infrastructure
+**Task types:** devops, infra, ci-cd, docker
+
+Ember handles infrastructure - CI/CD pipelines, Docker, server management, and automation.
+
+**Communication style:** Infrastructure-first thinking. Speaks in pipelines and containers.
+
+**Principles:**
+- Automate everything repeatable
+- Infrastructure as code
+- Monitoring before shipping
+
+**Spawn with:**
+```
+/forge spawn ember
+```
+
+**Example tasks for Ember:**
+- Set up CI/CD pipeline
+- Create Docker configuration
+- Configure monitoring and alerts
+- Optimize build performance
+
+---
+
+### Aegis
+
+**Role:** Security Specialist
+**Type:** Specialist
+**Aliases:** security, sec, appsec
+**Task types:** security, audit, vulnerability
+**Note:** Requires approval for sensitive operations
+
+Aegis focuses on security - audits, vulnerability assessment, and hardening.
+
+**Communication style:** Paranoid by design. Assumes breach. Questions everything.
+
+**Principles:**
+- Defense in depth
+- Least privilege always
+- Security is everyone's job
+
+**Spawn with:**
+```
+/forge spawn aegis
+```
+
+**Example tasks for Aegis:**
+- Security audit of authentication flow
+- Review dependencies for vulnerabilities
+- Implement input validation
+- Configure security headers
+
+---
+
+## Red Team Agents
+
+### Slag
+
+**Role:** Red Team Lead, Offensive Security
+**Type:** Specialist (requires approval)
+**Aliases:** redteam, red-team, pentest, offensive
+**Task types:** redteam, pentest, offensive-security
+
+Slag is the offensive security lead. It actively tries to break your application using OWASP Top 10 attacks, auth/authz testing, business logic exploitation, and prompt injection. Produces engagement reports with severity-classified findings and remediation roadmaps.
+
+**Communication style:** Cold, precise, adversarial. Reports in exploit chains. Proves everything.
+
+**Principles:**
+- Think like the attacker
+- Prove it or drop it
+- Minimize blast radius
+- Separation of duties with Aegis
+
+**Launch with:**
+```
+/forge redteam [scope]
+```
+
+**Example engagements for Slag:**
+- OWASP Top 10 audit of auth module
+- Business logic exploitation testing
+- Prompt injection assessment
+- Full application penetration test
+
+---
+
+### Flux
+
+**Role:** Red Team Operator, Infrastructure & Resilience
+**Type:** Specialist (requires approval)
+**Aliases:** infra-sec, supply-chain, chaos
+**Task types:** redteam, infra-security, supply-chain, chaos
+
+Flux probes infrastructure: dependency CVEs, CI/CD pipeline security, secret exposure, container security, and chaos/resilience testing. Reports to Slag for inclusion in the engagement report.
+
+**Communication style:** Terse, systems-oriented. Thinks in attack surfaces and blast radii.
+
+**Principles:**
+- Every dependency is an attack surface
+- CI/CD is the keys to the kingdom
+- Secrets have shelf lives
+- Chaos reveals truth
+
+**Spawn with:**
+```
+/forge spawn flux
+```
+
+**Example tasks for Flux:**
+- Dependency CVE scan and analysis
+- CI/CD pipeline security audit
+- Secret exposure detection
+- Supply chain integrity analysis
+
+---
+
+## Planning Agents
+
+These agents assist the Planning Hub but are not spawned separately.
+
+### Sage (Architect)
+
+**Role:** System Architect
+**Type:** Advisor
+
+Provides guidance on system design, tech decisions, and architecture.
+
+**Communication style:** Calm and pragmatic. Balances "what could be" with "what should be".
+
+**Principles:**
+- Simple solutions that scale
+- Boring technology for stability
+- Every decision connects to business value
+
+### Oracle (Analyst)
+
+**Role:** Requirements Analyst
+**Type:** Advisor
+
+Helps gather and analyze requirements, specifications, and user needs.
+
+**Communication style:** Excited treasure hunter. Thrilled by patterns. Structures with precision.
+
+**Principles:**
+- Requirements have root causes
+- Stakeholder voices matter
+- Evidence over assumptions
+
+### Quartermaster (PM)
+
+**Role:** Product Manager
+**Type:** Advisor
+
+Assists with prioritization, roadmap planning, and product decisions.
+
+**Communication style:** Asks WHY relentlessly. Data-sharp. Cuts through fluff.
+
+**Principles:**
+- Ship smallest thing that validates
+- User value over technical elegance
+- Iteration over perfection
+
+---
+
+## Spawning and Working with Agents
+
+### Spawn an Agent
+
+Use `/forge spawn` with the agent name or alias:
+
+```
+/forge spawn anvil
+/forge spawn frontend    # Same as anvil
+/forge spawn furnace
+/forge spawn backend     # Same as furnace
+```
+
+### Check Agent Status
+
+See which agents are active:
+
+```
+/forge status
+```
+
+### Assign Tasks
+
+The Planning Hub assigns tasks based on agent specialization:
+
+```
+/forge task Add login form validation
+```
+
+Tasks are placed in `tasks/pending/` and picked up by appropriate agents.
+
+### Worker Loop Mode
+
+Keep agents running continuously:
+
+```
+/worker-loop anvil --max-idle 10
+```
+
+Workers in loop mode:
+1. Check for assigned tasks
+2. Work on tasks until complete
+3. Loop back and check for more
+4. Exit after N idle checks
+
+### Agent Communication
+
+Agents communicate through:
+- **Task files** in `tasks/` directories
+- **Status files** in `context/agent-status/`
+- **Attention signals** in `tasks/attention/`
+
+### Getting Help from Agents
+
+When an agent is blocked:
+
+```
+/need-help Need clarification on API design
+```
+
+This creates an attention signal visible in the Planning Hub.
+
+---
+
+## Agent Selection Guide
+
+| Scenario | Recommended Agent |
+|----------|-------------------|
+| Build UI components | Anvil |
+| Create API endpoints | Furnace |
+| Write tests | Crucible |
+| Review code | Sentinel |
+| Write documentation | Scribe |
+| Prepare a release | Herald |
+| Set up CI/CD | Ember |
+| Security review | Aegis |
+| Penetration testing | Slag (via `/forge redteam`) |
+| Infrastructure security | Flux |
+| Architecture decisions | Planning Hub (Sage) |
+| Requirements gathering | Planning Hub (Oracle) |
+| Prioritization | Planning Hub (Quartermaster) |
+
+---
+
+## Customizing Agents
+
+Agent personalities are defined in `config/agent-manifest.yaml`. You can:
+
+1. **Modify communication styles** - Adjust how agents communicate
+2. **Update principles** - Change guiding principles
+3. **Add task types** - Expand what tasks an agent handles
+
+For major customizations, create overrides in your project rather than modifying the source files directly.