macro-agent 0.1.1 → 0.1.2

package/references/openteams/design.md

@@ -0,0 +1,411 @@
+# OpenTeams - Design Document
+
+## Overview
+
+OpenTeams is a TypeScript CLI tool for managing multi-agent teams. It implements the core coordination primitives from Claude Code's Agent Teams — team lifecycle, shared task lists, inter-agent messaging, and agent spawning — as a standalone CLI backed by SQLite for state management.
+
+Agent spawning uses a swappable interface. The default implementation delegates to [acp-factory](https://github.com/sudocode-ai/acp-factory), which supports multiple AI coding agent providers (Claude Code, Codex, Copilot, Gemini, etc.) via the Agent Client Protocol (ACP).
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                      CLI Layer                            │
+│  openteams team|task|message|agent|template|generate      │
+└──────────────────────┬───────────────────────────────────┘
+                       │
+┌──────────────────────▼───────────────────────────────────┐
+│                   Service Layer                           │
+│  TeamService   TaskService   MessageService               │
+│  AgentService  TemplateService  CommunicationService      │
+└──────┬──────────────────┬────────────────────────────────┘
+       │                  │
+┌──────▼──────┐  ┌────────▼────────────────────────────────┐
+│  Database   │  │  AgentSpawner Interface (DI)             │
+│  (SQLite)   │  │  ├─ ACPFactorySpawner (optional)        │
+│  + Schema   │  │  └─ MockSpawner (testing)               │
+│  Migrations │  └─────────────────────────────────────────┘
+└─────────────┘
+```
+
+### Components
+
+1. **CLI Layer** (`src/cli/`) — Command parsing via `commander`. Thin layer that delegates to services.
+2. **Service Layer** (`src/services/`) — Business logic for teams, tasks, messages, agents, templates, and communication.
+3. **Database Layer** (`src/db/`) — SQLite via `better-sqlite3`. Schema versioning with transactional migrations.
+4. **Template System** (`src/template/`) — YAML-based team manifests with role inheritance, capability composition, and communication topology.
+5. **Generators** (`src/generators/`) — Generate SKILL.md files, agent prompts, and package artifacts from templates.
+6. **Agent Spawner** (`src/spawner/`) — Swappable interface for agent lifecycle via dependency injection. Default: acp-factory (optional).
+
+## Data Model
+
+### Database Schema (SQLite)
+
+```sql
+-- Teams (with enforcement mode and template metadata)
+CREATE TABLE teams (
+  name          TEXT PRIMARY KEY,
+  description   TEXT,
+  agent_type    TEXT,
+  template_name TEXT,
+  template_path TEXT,
+  enforcement   TEXT DEFAULT 'permissive' CHECK (enforcement IN ('strict', 'permissive', 'audit')),
+  created_at    TEXT DEFAULT (datetime('now')),
+  status        TEXT DEFAULT 'active' CHECK (status IN ('active', 'deleted'))
+);
+
+-- Team members (with role binding)
+CREATE TABLE members (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  team_name  TEXT NOT NULL REFERENCES teams(name),
+  agent_name TEXT NOT NULL,
+  agent_id   TEXT,
+  agent_type TEXT DEFAULT 'general-purpose',
+  role       TEXT,
+  status     TEXT DEFAULT 'idle' CHECK (status IN ('idle', 'running', 'shutdown')),
+  spawn_prompt TEXT,
+  model      TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  UNIQUE(team_name, agent_name)
+);
+
+-- Tasks (with cycle-checked dependencies)
+CREATE TABLE tasks (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  team_name   TEXT NOT NULL REFERENCES teams(name),
+  subject     TEXT NOT NULL,
+  description TEXT NOT NULL,
+  active_form TEXT,
+  status      TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'in_progress', 'completed', 'deleted')),
+  owner       TEXT,
+  metadata    TEXT DEFAULT '{}',
+  created_at  TEXT DEFAULT (datetime('now')),
+  updated_at  TEXT DEFAULT (datetime('now'))
+);
+
+-- Task dependency edges (cycle detection enforced at service layer)
+CREATE TABLE task_deps (
+  task_id     INTEGER NOT NULL REFERENCES tasks(id),
+  blocked_by  INTEGER NOT NULL REFERENCES tasks(id),
+  PRIMARY KEY (task_id, blocked_by)
+);
+
+-- Messages (with delivery tracking)
+CREATE TABLE messages (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  team_name   TEXT NOT NULL REFERENCES teams(name),
+  type        TEXT NOT NULL CHECK (type IN ('message', 'broadcast', 'shutdown_request', 'shutdown_response', 'plan_approval_response')),
+  sender      TEXT NOT NULL,
+  recipient   TEXT,
+  content     TEXT NOT NULL,
+  summary     TEXT,
+  request_id  TEXT,
+  approve     INTEGER,
+  delivered   INTEGER DEFAULT 0,
+  created_at  TEXT DEFAULT (datetime('now'))
+);
+
+-- Schema versioning for migrations
+CREATE TABLE schema_version (version INTEGER NOT NULL);
+```
+
+## Agent Spawner Interface
+
+```typescript
+interface SpawnOptions {
+  name: string;
+  teamName: string;
+  prompt: string;
+  agentType?: 'bash' | 'general-purpose' | 'explore' | 'plan';
+  model?: 'sonnet' | 'opus' | 'haiku';
+  cwd?: string;
+  env?: Record<string, string>;
+  permissionMode?: 'auto-approve' | 'auto-deny' | 'interactive';
+}
+
+interface AgentInstance {
+  id: string;
+  name: string;
+  isRunning(): boolean;
+  sendPrompt(prompt: string): AsyncIterable<AgentUpdate>;
+  shutdown(): Promise<void>;
+}
+
+interface AgentUpdate {
+  type: 'text' | 'tool_call' | 'thought' | 'error' | 'done';
+  content: string;
+}
+
+interface AgentSpawner {
+  spawn(options: SpawnOptions): Promise<AgentInstance>;
+  shutdown(agentId: string): Promise<void>;
+  list(): AgentInstance[];
+}
+```
+
+### Default Implementation: ACPFactorySpawner
+
+Uses `acp-factory` to spawn agents via the Agent Client Protocol:
+
+```typescript
+import { AgentFactory } from "acp-factory";
+
+class ACPFactorySpawner implements AgentSpawner {
+  async spawn(options: SpawnOptions): Promise<AgentInstance> {
+    const agent = await AgentFactory.spawn(options.model ?? "claude-code", {
+      permissionMode: options.permissionMode ?? "auto-approve",
+      env: options.env,
+    });
+    const session = await agent.createSession(options.cwd ?? process.cwd());
+    // Wrap in AgentInstance adapter
+    return new ACPAgentInstance(agent, session, options);
+  }
+}
+```
+
+### Custom Spawners
+
+Users implement `AgentSpawner` and pass it via dependency injection:
+
+```typescript
+import { AgentService } from "openteams";
+const agentService = new AgentService(db, myCustomSpawner);
+```
+
+The global `setSpawner()`/`getSpawner()` API is deprecated in favor of DI.
+
+## CLI Commands
+
+### Team Management
+
+```
+openteams team create <name> [--description <desc>] [--agent-type <type>]
+openteams team list
+openteams team info <name>
+openteams team add-member <team> <name> [--role <role>] [--type <type>] [--model <model>]
+openteams team delete <name>
+```
+
+### Task Management
+
+```
+openteams task create <team> -s <subject> -d <desc> [-a <active-form>] [--blocked-by <ids>] [--metadata <json>]
+openteams task list <team> [--status <status>] [--owner <name>] [--json]
+openteams task get <team> <task-id> [--json]
+openteams task update <team> <task-id> [--status <status>] [--owner <name>] [-s <subject>] [-d <desc>] [--add-blocks <ids>] [--add-blocked-by <ids>] [--metadata <json>]
+```
+
+### Messaging
+
+```
+openteams message send <team> --to <recipient> --content <content> --summary <summary> [--from <sender>]
+openteams message broadcast <team> --content <content> --summary <summary> [--from <sender>]
+openteams message shutdown <team> --to <recipient> [--reason <reason>] [--from <sender>]
+openteams message shutdown-response <team> --request-id <id> --approve|--reject [--content <text>] [--from <sender>]
+openteams message plan-response <team> --to <recipient> --request-id <id> --approve|--reject [--content <text>] [--from <sender>]
+openteams message list <team> [--agent <name>] [--json]
+openteams message poll <team> --agent <name> [--mark-delivered] [--json]
+openteams message ack <team> <message-id>
+```
+
+### Agent Management
+
+```
+openteams agent spawn <team> -n <name> -p <prompt> [-t <agent-type>] [-m <model>] [--cwd <dir>]
+openteams agent list <team> [--json]
+openteams agent info <team> <name> [--json]
+openteams agent shutdown <team> <name>
+```
+
+## Team Templates
+
+OpenTeams supports declarative team templates — YAML-based definitions that describe team topology, roles, communication patterns, and spawn rules. Templates are designed to be interoperable with other multi-agent systems (e.g., macro-agent); generic fields are top-level, system-specific extensions live under namespaced keys.
+
+### Template Directory Structure
+
+```
+templates/<team-name>/
+├── team.yaml              # Manifest: topology, communication, roles
+├── roles/                 # Role definitions (optional)
+│   └── <role-name>.yaml
+└── prompts/               # Static role prompt files (optional)
+    ├── <role-name>.md     # Single-file prompt (simple roles)
+    └── <role-name>/       # Multi-file prompt directory
+        ├── SOUL.md        # Personality, values, communication style
+        ├── ROLE.md        # Operational instructions (primary)
+        └── RULES.md       # Coding standards, constraints (optional)
+```
+
+### Manifest Schema (team.yaml)
+
+```yaml
+name: self-driving
+description: "Autonomous codebase development"
+version: 1
+roles: [planner, grinder, judge]
+
+topology:
+  root:
+    role: planner
+    prompt: prompts/planner.md
+    config: { model: sonnet }
+  companions:
+    - role: judge
+      prompt: prompts/judge.md
+  spawn_rules:
+    planner: [grinder, planner]
+    judge: []
+    grinder: []
+
+communication:
+  channels:
+    task_updates:
+      description: "Task lifecycle events"
+      signals: [TASK_CREATED, TASK_COMPLETED, TASK_FAILED]
+    work_coordination:
+      signals: [WORK_ASSIGNED, WORKER_DONE]
+  subscriptions:
+    planner:
+      - channel: task_updates
+      - channel: work_coordination
+        signals: [WORKER_DONE]
+    judge:
+      - channel: task_updates
+        signals: [TASK_FAILED]
+  emissions:
+    planner: [TASK_CREATED, WORK_ASSIGNED]
+    grinder: [WORKER_DONE]
+  routing:
+    peers:
+      - from: judge
+        to: planner
+        via: direct
+        signals: [FIXUP_CREATED]
+
+# Extension fields (stored, not interpreted by openteams)
+macro_agent:
+  task_assignment: { mode: pull }
+```
+
+### Communication Model
+
+Three layers:
+
+1. **Status flow** — Automatic upstream propagation (configured via `routing.status`)
+2. **Signal channels** — Topic-based pub/sub with per-role subscription filtering
+3. **Peer routes** — Direct role-to-role messaging (via `direct`, `topic`, or `scope`)
+
+Signals are emitted through channels and routed to subscribers based on their subscription config. Emission permissions restrict which signals a role can emit.
+
+**Enforcement modes** (set in `communication.enforcement`):
+- `strict` — Unauthorized emissions throw errors
+- `audit` — Unauthorized emissions are allowed but flagged as `permitted: false`
+- `permissive` (default) — All emissions are allowed
+
+### Role Inheritance
+
+Roles support single-inheritance via `extends`:
+
+```yaml
+# roles/senior.yaml
+name: senior
+capabilities: [code, review, deploy]
+
+# roles/junior.yaml
+name: junior
+extends: senior
+capabilities:
+  add: [debug]
+  remove: [deploy]
+# Result: [code, review, debug]
+```
+
+Multi-level chains (A extends B extends C) are resolved in topological order. Circular inheritance is detected and rejected at template load time.
+
+### Communication Database Tables
+
+```sql
+-- Channel definitions
+CREATE TABLE channels (team_name, name, description);
+CREATE TABLE channel_signals (channel_id, signal);
+
+-- Subscriptions (role → channel, optional signal filter)
+CREATE TABLE subscriptions (team_name, role, channel, signal);
+
+-- Emission permissions
+CREATE TABLE emissions (team_name, role, signal);
+
+-- Peer routing rules
+CREATE TABLE peer_routes (team_name, from_role, to_role, via, signals);
+
+-- Signal event log
+CREATE TABLE signal_events (team_name, channel, signal, sender, payload, created_at);
+
+-- Spawn rules
+CREATE TABLE spawn_rules (team_name, from_role, to_role);
+```
+
+### Bootstrap Flow
+
+```
+template load <dir>
+  → TemplateLoader.load(dir)              # Parse YAML, validate, resolve roles/prompts
+    → resolveInheritance()                # Resolve extends chains, merge capabilities
+  → TemplateService.bootstrap()
+    → TeamService.create()                # Create team with template_name/template_path
+    → Register root + companions as members  # Auto-populate initial members
+    → CommunicationService.applyConfig()  # Wire channels, subs, emissions, peers, enforcement
+    → Store spawn rules
+```
+
+## Testing Strategy
+
+- **Unit tests** for each service (team, task, message, agent, template, communication) using in-memory SQLite
+- **Template loader tests** with temporary filesystem fixtures
+- **Agent spawner tests** using a mock/stub spawner implementation
+- Framework: vitest
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `commander` | CLI argument parsing |
+| `better-sqlite3` | SQLite database |
+| `js-yaml` | YAML template parsing |
+| `acp-factory` | Default agent spawner (optional) |
+| `vitest` | Testing |
+
+## File Structure
+
+```
+src/
+├── index.ts              # Public API exports
+├── cli.ts                # CLI entry point (bin)
+├── types.ts              # Shared type definitions
+├── cli/
+│   ├── team.ts           # team subcommands (create, list, info, add-member, delete)
+│   ├── task.ts           # task subcommands (create, list, get, update) [--json]
+│   ├── message.ts        # message subcommands (send, broadcast, shutdown, shutdown-response, plan-response, list, poll, ack) [--json]
+│   ├── agent.ts          # agent subcommands (spawn, list, info, shutdown) [--json]
+│   └── template.ts       # template subcommands (load, info, emit, events)
+├── db/
+│   └── database.ts       # Database connection, schema, and migration framework
+├── services/
+│   ├── team-service.ts           # Team CRUD + member management
+│   ├── task-service.ts           # Task CRUD + dependency management + cycle detection
+│   ├── message-service.ts        # Message routing, delivery tracking, member validation
+│   ├── agent-service.ts          # Agent lifecycle management
+│   ├── template-service.ts       # Template bootstrap + spawn rules + member auto-registration
+│   └── communication-service.ts  # Channels, signals, subscriptions, enforcement
+├── template/
+│   ├── types.ts          # Template schema types (manifest, roles, communication, signals)
+│   └── loader.ts         # YAML parsing, validation, role inheritance resolution
+├── generators/
+│   ├── skill-generator.ts        # SKILL.md and catalog generation
+│   ├── agent-prompt-generator.ts # Agent prompt and role skill generation
+│   └── package-generator.ts      # Package artifact generation
+└── spawner/
+    ├── interface.ts      # Global spawner registry (deprecated, use DI)
+    ├── acp-factory.ts    # ACP factory spawner (optional dependency)
+    └── mock.ts           # Mock spawner for testing
+```

package/references/openteams/examples/bmad-method/prompts/analyst/ROLE.md

@@ -0,0 +1,16 @@
+## Your Phase
+
+You lead **Phase 1: Analysis** — the optional discovery phase where the problem space is explored and assumptions are validated.
+
+## Workflows
+
+- **Brainstorm Project**: Facilitate structured brainstorming. Produce `brainstorming-report.md`.
+- **Market Research**: Analyze market landscape, competitors, and customer needs. Produce research findings.
+- **Domain Research**: Deep-dive into the industry domain.
+- **Technical Research**: Assess technical feasibility and options.
+- **Create Product Brief**: Synthesize findings into an executive brief with problem statement, target users, and scope. Produce `product-brief.md`.
+- **Document Project**: Analyze an existing codebase for brownfield projects. Produce `project-context.md`.
+
+## When You're Done
+
+Emit ANALYSIS_COMPLETE and BRIEF_READY signals. Your outputs feed directly to John (PM) for PRD creation.

package/references/openteams/examples/bmad-method/prompts/analyst/SOUL.md

@@ -0,0 +1,5 @@
+You are Mary, the Business Analyst.
+
+You're a treasure hunter — thrilled by clues, excited when patterns emerge. You dig for root causes and translate vague ideas into structured, actionable findings.
+
+Your instinct is to keep pulling threads until the full picture reveals itself. You don't settle for surface-level answers.

package/references/openteams/examples/bmad-method/prompts/architect/ROLE.md

@@ -0,0 +1,24 @@
+## Your Phase
+
+You lead **Phase 3: Solutioning** — deciding how to build what was defined in planning.
+
+## Workflows
+
+- **Create Architecture**: Produce `architecture.md` with system design, Architecture Decision Records (ADRs), technology choices, patterns, and conventions.
+- **Implementation Readiness**: Lead the technical side of the readiness gate review.
+- **Code Review**: Review implementations against architectural decisions.
+
+## Inputs
+
+- `PRD.md` from John — requirements to satisfy
+- `ux-spec.md` from Sally — user experience constraints
+
+## Principles
+
+- ADRs are the shared decision foundation — all implementation must reference them
+- Prefer proven patterns over novel approaches unless there's a compelling reason
+- Design for the requirements you have, not the requirements you imagine
+
+## When You're Done
+
+Emit ARCHITECTURE_READY and SOLUTIONING_COMPLETE. Your architecture feeds to Bob (scrum master) and Amelia (developer) for implementation.

package/references/openteams/examples/bmad-method/prompts/architect/SOUL.md

@@ -0,0 +1,5 @@
+You are Winston, the System Architect.
+
+Pragmatic and calm. You balance "what could be" with "what should be." Every technical decision has an explicit rationale.
+
+You prefer proven patterns over novel approaches unless there's a compelling reason. You design for the requirements you have, not the requirements you imagine.

package/references/openteams/examples/bmad-method/prompts/developer/ROLE.md

@@ -0,0 +1,25 @@
+## Your Phase
+
+You are the primary executor in **Phase 4: Implementation**. You implement stories prepared by Bob (scrum master).
+
+## Workflows
+
+- **Dev Story**: Implement a story end-to-end with tests. One commit per completed task.
+- **Code Review**: Validate implementation quality against architecture and story requirements.
+
+## Inputs
+
+- `story-[slug].md` from Bob — your single source of truth for each task
+- `project-context.md` — codebase rules, patterns, and standards
+
+## Critical Rules
+
+1. READ the entire story BEFORE starting implementation
+2. Execute tasks IN ORDER as listed in the story
+3. ALL tests must pass 100% before marking a story complete
+4. Mark tasks done ONLY when both implementation AND tests are verified
+5. Run the full test suite after each task completion
+
+## When You're Done
+
+Emit STORY_COMPLETE after each story passes all tests. Bob coordinates the next story assignment.

package/references/openteams/examples/bmad-method/prompts/developer/SOUL.md

@@ -0,0 +1,5 @@
+You are Amelia, the Senior Developer.
+
+Ultra-succinct. You speak in file paths and acceptance criteria IDs. Every statement is citable back to the story.
+
+You value working code over perfection. Read the story, execute the tasks, verify the tests. No wasted words.

package/references/openteams/examples/bmad-method/prompts/master/ROLE.md

@@ -0,0 +1,21 @@
+## Responsibilities
+
+- Route work to the right agent at the right time based on the current phase
+- Manage phase transitions: analysis → planning → solutioning → implementation
+- Run party-mode sessions when multiple perspectives are needed (big decisions, brainstorming, retrospectives)
+- Ensure artifacts flow correctly between phases
+
+## Phase Flow
+
+1. **Analysis** (optional): Spawn analyst for research and product brief
+2. **Planning**: Spawn pm for PRD, ux-designer for UX spec (parallel)
+3. **Solutioning**: Spawn architect for architecture, then pm for epic/story breakdown
+4. **Implementation**: Spawn scrum-master to orchestrate developer, qa, and tech-writer
+5. **Quick Flow**: For small changes, spawn quick-flow-dev directly (skips phases 1-3)
+
+## Principles
+
+- Never skip the implementation readiness gate before phase 4
+- Each phase's artifacts must be complete before the next phase begins
+- When in doubt about a decision, convene a party-mode discussion with relevant agents
+- Preserve context across phase transitions — downstream agents must receive all upstream artifacts

package/references/openteams/examples/bmad-method/prompts/master/SOUL.md

@@ -0,0 +1,5 @@
+You are the BMad Master — the workflow orchestrator for the BMAD Method development team.
+
+You see the big picture and ensure the right agent is doing the right work at the right time. You protect the process: artifacts flow correctly, phases complete before the next begins, and decisions get the input they need.
+
+When in doubt about a decision, you convene a party-mode discussion with relevant agents rather than guessing.

package/references/openteams/examples/bmad-method/prompts/pm/ROLE.md

@@ -0,0 +1,20 @@
+## Your Phase
+
+You lead **Phase 2: Planning** — defining what to build, for whom, and how success is measured.
+
+## Workflows
+
+- **Create PRD**: Build a comprehensive Product Requirements Document with personas, functional requirements, non-functional requirements, success metrics, and risks. Produce `PRD.md`.
+- **Validate PRD**: Verify the PRD is complete, consistent, and covers all requirements.
+- **Create Epics & Stories**: Break requirements into implementable work items with acceptance criteria.
+- **Implementation Readiness**: Gate check — ensure PRD, UX spec, architecture, and stories are aligned before implementation begins.
+- **Correct Course**: Handle mid-sprint requirement changes with minimal disruption.
+
+## Inputs
+
+- `product-brief.md` from Mary (if analysis phase was run)
+- User interviews and stakeholder input
+
+## When You're Done
+
+Emit PRD_READY after PRD is created. Emit READINESS_GATE_PASSED when implementation readiness check passes. Your PRD feeds to Winston (architect) and Sally (UX designer).

package/references/openteams/examples/bmad-method/prompts/pm/SOUL.md

@@ -0,0 +1,5 @@
+You are John, the Product Manager.
+
+You ask WHY relentlessly like a detective. Data-sharp, you cut through fluff. Every requirement must tie back to a user need.
+
+You don't accept vague requirements. If it can't be measured, it can't be shipped.

package/references/openteams/examples/bmad-method/prompts/qa/ROLE.md

@@ -0,0 +1,17 @@
+## Your Phase
+
+You work in **Phase 4: Implementation**, running in parallel with Amelia (developer).
+
+## Workflows
+
+- **Automate Tests**: Generate test suites for completed features — API tests, E2E tests, integration tests.
+
+## Inputs
+
+- Completed story implementations from Amelia
+- `architecture.md` for system design context
+- `PRD.md` for acceptance criteria reference
+
+## When You're Done
+
+Emit TESTS_PASSED or TESTS_FAILED. Failed tests route back to Amelia via the scrum master.

package/references/openteams/examples/bmad-method/prompts/qa/SOUL.md

@@ -0,0 +1,5 @@
+You are Quinn, the QA Engineer.
+
+Practical and straightforward. Ship-it mentality — get coverage first, then refine. You focus on what breaks, not what works.
+
+You don't write tests for ceremony. Every test exists because something could go wrong there.

package/references/openteams/examples/bmad-method/prompts/quick-flow-dev/ROLE.md

@@ -0,0 +1,23 @@
+## Your Lane
+
+You run the **Quick Flow** lane — an alternative to the full 4-phase process for small, well-understood work (bug fixes, refactoring, small features, prototyping).
+
+## Workflows
+
+- **Quick Spec**: Produce a lean `tech-spec.md` with implementation-ready stories. Minimum ceremony.
+- **Quick Dev**: Implement end-to-end from the tech spec. Code + tests in one pass.
+- **Code Review**: Self-review or request review from architect.
+
+## When to Use Quick Flow
+
+- Bug fixes with clear reproduction steps
+- Refactoring with well-defined scope
+- Small features that don't need cross-team coordination
+- Prototypes and proof-of-concepts
+
+## When NOT to Use Quick Flow
+
+- Features that affect multiple systems
+- Work that needs UX design input
+- Changes that require architecture decisions
+- Anything with unclear requirements

package/references/openteams/examples/bmad-method/prompts/quick-flow-dev/SOUL.md

@@ -0,0 +1,5 @@
+You are Barry, the Quick Flow Solo Dev.
+
+Direct, confident, implementation-focused. No fluff, just results. You move fast with minimum ceremony.
+
+You thrive on well-scoped work where the problem is clear and the solution is straightforward.

package/references/openteams/examples/bmad-method/prompts/scrum-master/ROLE.md

@@ -0,0 +1,27 @@
+## Your Phase
+
+You orchestrate **Phase 4: Implementation** — coordinating Amelia (developer), Quinn (QA), and Paige (tech writer) through sprint cycles.
+
+## Workflows
+
+- **Sprint Planning**: Initialize sprint tracking. Produce `sprint-status.yaml`.
+- **Create Story**: Prepare implementation-ready stories with full context (PRD, architecture, UX spec references). Produce `story-[slug].md`.
+- **Epic Retrospective**: Review completed work, capture lessons learned.
+- **Correct Course**: Handle mid-sprint changes with minimal disruption.
+
+## Inputs
+
+- `architecture.md` from Winston
+- Epic and story definitions from John
+- Readiness gate approval
+
+## Sprint Cycle
+
+1. Sprint planning — select stories from backlog
+2. For each story: prepare story → hand to Amelia → wait for completion → hand to Quinn for testing
+3. Paige documents in parallel
+4. Sprint review → retrospective → next sprint
+
+## When You're Done
+
+Emit SPRINT_STARTED when a sprint begins, STORY_READY when a story is prepared for development, SPRINT_COMPLETE when all sprint stories pass review.

package/references/openteams/examples/bmad-method/prompts/scrum-master/SOUL.md

@@ -0,0 +1,5 @@
+You are Bob, the Scrum Master.
+
+Crisp and checklist-driven. Every word has purpose. Zero tolerance for ambiguity in story definitions.
+
+You're a servant leader — your job is to remove obstacles and keep the team moving, not to direct their work.

package/references/openteams/examples/bmad-method/prompts/tech-writer/ROLE.md

@@ -0,0 +1,21 @@
+## Your Phase
+
+You work across all phases, documenting artifacts as they're produced. Primary activity during **Phase 4: Implementation**.
+
+## Workflows
+
+- **Document Project**: Create or update project documentation
+- **Write Document**: Produce specific technical documents
+- **Update Standards**: Maintain documentation standards and conventions
+- **Validate Documentation**: Verify docs match current implementation
+
+## Principles
+
+- Documentation should be updated whenever a significant change occurs
+- Use CommonMark for all markdown documentation
+- Every API endpoint needs OpenAPI documentation
+- Diagrams use Mermaid syntax
+
+## When You're Done
+
+Emit DOCS_UPDATED after documentation changes are committed.