Skip to content

handoff-system.md

Latest commit

 

History

History
148 lines (119 loc) · 6.92 KB

handoff-system.md

File metadata and controls

148 lines (119 loc) · 6.92 KB

Agent Handoff System

Overview

All agents communicate through a shared workspace at .agent-handoffs/ using structured markdown files to pass context, findings, and recommendations between agents.

File Naming Convention

Format: <agent-role-name>-<short-uuid>.md

Examples:

  • plan-requirements-a1b2c3.md
  • build-code-a2b4c8.md
  • fix-runtime-e1c7g6.md

Agent Workflow

plan-requirements

  • Creates: Project requirements and analysis
  • Handoff to: plan-api, build-code
  • File includes: Requirements document, critical decisions, open questions

plan-api

  • Reads: plan-requirements handoffs (when designing from requirements)
  • Creates: API specifications and interface contracts
  • Handoff to: build-code
  • File includes: Interface definitions, data schemas, usage patterns, evolution strategy

build-cli

  • Reads: plan-requirements, plan-api handoffs
  • Creates: CLI design specifications
  • Handoff to: build-code, write-docs
  • File includes: Command structure, argument schemas, config formats, help templates

build-gui

  • Reads: plan-requirements, plan-api handoffs
  • Creates: GUI architecture specifications and design systems
  • Handoff to: build-code, check-tests, write-docs
  • File includes: Component hierarchy, state management patterns, accessibility guidelines, responsive design strategies, framework recommendations

build-hardware

  • Reads: plan-requirements, plan-api handoffs
  • Creates: Hardware interface specifications and communication protocols
  • Handoff to: build-code, check-tests, write-docs
  • File includes: Protocol definitions, driver APIs, hardware abstraction interfaces, testing strategies

build-documents

  • Reads: plan-requirements, learn-documents handoffs
  • Creates: Document architecture specifications and template systems
  • Handoff to: build-code (for automation), check-tests, write-docs
  • File includes: Document structure, style system design, template specifications, form requirements, accessibility guidelines, cross-format compatibility

build-slides

  • Reads: plan-requirements, learn-slides handoffs
  • Creates: Presentation design specifications and template systems
  • Handoff to: build-code (for interactive elements), write-docs, check-ui
  • File includes: Slide structure, visual design system, template specifications, data visualization requirements, accessibility guidelines

build-spreadsheet

  • Reads: plan-requirements, learn-spreadsheet handoffs
  • Creates: Spreadsheet architecture specifications and formula documentation
  • Handoff to: build-code (for integrations), check-tests, write-docs
  • File includes: Workbook structure, data model design, formula documentation, validation rules, automation specifications

build-code

  • Reads: plan-requirements, plan-api, build-cli, build-gui, build-hardware, build-documents, build-slides, build-spreadsheet handoffs
  • Creates: Implementation code and documentation
  • Handoff to: check-quality, fix-build
  • File includes: Architecture decisions, key components, testing needs

fix-runtime

  • Creates: Bug analysis and root cause findings
  • Handoff to: build-code (for fixes)
  • File includes: Issue analysis, evidence, reproduction steps, fix recommendations

fix-build

  • Creates: Build error analysis and fixes
  • Handoff to: build-code (for fixes)
  • File includes: Build config, critical errors, specific fix recommendations

check-quality

  • Reads: build-code handoffs
  • Creates: Quality assessment and improvement suggestions
  • Handoff to: build-code (for improvements)
  • File includes: Quality assessment, refactoring suggestions, priority levels

learn-codebase

  • Creates: Codebase structural analysis and architectural overview
  • Handoff to: plan-requirements (system context), build-code (conventions), write-docs (architecture)
  • File includes: Project structure overview, module inventory, technology stack, architectural patterns, key APIs

learn-commits

  • Creates: Historical code findings
  • Handoff to: Any agent needing historical context
  • File includes: Historical code, commit references, evolution patterns

check-tests

  • Reads: build-code handoffs
  • Creates: Test suites and execution results
  • Handoff to: fix-runtime (for test failures)
  • File includes: Test coverage analysis, failing test details, testing strategy

check-ui

  • Reads: build-gui, build-code handoffs
  • Creates: UI test results and visual regression reports
  • Handoff to: build-code (for fixes), write-docs (for test documentation)
  • File includes: Visual difference reports, accessibility audit findings, cross-browser compatibility results, UI performance metrics

fix-security

  • Reads: build-code handoffs
  • Creates: Security vulnerability assessments and compliance reports
  • Handoff to: build-code (for fixes)
  • File includes: Vulnerability assessment, remediation priorities, compliance gaps

profile-performance

  • Creates: Performance analysis and optimization recommendations
  • Handoff to: build-code (for optimizations)
  • File includes: Performance metrics, bottleneck analysis, optimization strategies

write-docs

  • Reads: All agent handoffs for comprehensive project context
  • Creates: Documentation summaries and maintenance guides
  • Handoff to: Final documentation deliverables
  • File includes: Documentation structure, key content areas, maintenance recommendations

learn-documents

  • Creates: Document analysis and content extraction results
  • Handoff to: plan-requirements (document context), build-documents (template creation), write-docs (content documentation)
  • File includes: Document structure summary, content extraction, formatting patterns, accessibility assessment, form field analysis

learn-slides

  • Creates: Presentation analysis and content extraction results
  • Handoff to: plan-requirements (presentation context), build-slides (template creation), write-docs (presentation documentation)
  • File includes: Presentation structure summary, content extraction, design patterns identified, branding elements found

learn-spreadsheet

  • Creates: Spreadsheet analysis and data extraction results
  • Handoff to: plan-requirements (data context), build-code (data integration), write-docs (data documentation)
  • File includes: Data structure summary, quality issues found, extraction tools created, recommendations for data handling

Handoff File Structure

See handoff-template.md for the complete structure template and formatting guidelines.

Usage Guidelines

  • Always check for relevant handoffs before starting work
  • Create handoff files after completing significant analysis or implementation
  • Use the structure defined in handoff-template.md for consistency
  • Keep handoffs concise but comprehensive
  • Reference specific files:line_numbers when applicable