claude-code-swarm 0.3.2 → 0.3.4

package/references/openteams/docs/visual-editor-design.md

@@ -1,1225 +0,0 @@
-# OpenTeams Visual Team Editor — Design Specification
-
-## 1. Overview
-
-A standalone browser-based visual editor for designing, visualizing, and exporting OpenTeams team configurations. Users compose team topologies, communication patterns, role definitions, and signal flows on an interactive graph canvas, then export valid `team.yaml` + `roles/*.yaml` files.
-
-**Reference implementation**: The [self-driving-repo editor](https://github.com/alexngai/self-driving-repo/tree/main/editor) — a React Flow-based visual editor for DAG agent configs. Our editor adapts its architecture to handle OpenTeams' richer multi-layer relationship model (topology, communication, spawn rules, role inheritance).
-
-### Goals
-
-- Visualize complex inter-role relationships that are hard to reason about in raw YAML
-- Provide a bidirectional editor: import existing templates, modify visually, export valid YAML
-- Real-time validation with actionable error/warning feedback
-- Support all existing templates (gsd, bmad-method) as proof of generalization
-- Inline markdown editing for role prompts
-
-### Non-Goals (v1)
-
-- Runtime monitoring (live signal events, agent status) — this is a config editor, not a dashboard
-- Direct filesystem write-back — export produces YAML for copy/download
-- MCP server configuration UI — file path references only for v1
-
----
-
-## 2. Architecture
-
-### Tech Stack
-
-| Dependency | Version | Purpose |
-|---|---|---|
-| React | 19.x | UI framework |
-| @xyflow/react | 12.x | Graph canvas (React Flow) |
-| Zustand | 5.x | State management (5 stores) |
-| @dagrejs/dagre | 1.x | Hierarchical auto-layout |
-| js-yaml | 4.x | YAML serialization |
-| ajv | 8.x | JSON Schema validation (reuse existing schemas) |
-| Vite | 6.x | Build tooling |
-| Tailwind CSS | 4.x | Styling |
-| TypeScript | 5.x | Type safety (strict mode) |
-
-### Project Structure
-
-```
-editor/
-├── src/
-│   ├── App.tsx                          # Root layout + ReactFlowProvider
-│   ├── main.tsx                         # Vite entry point
-│   ├── index.css                        # Tailwind imports + CSS variables
-│   │
-│   ├── types/
-│   │   └── editor.ts                    # Canvas-specific types (nodes, edges, data)
-│   │
-│   ├── components/
-│   │   ├── canvas/
-│   │   │   ├── Canvas.tsx               # ReactFlow container, drag-drop, edge creation
-│   │   │   └── QuickAddMenu.tsx         # Double-click context menu
-│   │   │
-│   │   ├── nodes/
-│   │   │   ├── RoleNode.tsx             # Role node with capabilities, model, signal summary
-│   │   │   ├── ChannelNode.tsx          # Channel node with signal list
-│   │   │   └── node-styles.ts           # Color constants, topology-based styling
-│   │   │
-│   │   ├── edges/
-│   │   │   ├── PeerRouteEdge.tsx        # Bold direct route with signal labels
-│   │   │   ├── SignalFlowEdge.tsx       # Emission/subscription through channels
-│   │   │   └── SpawnEdge.tsx            # Dashed "can spawn" relationship
-│   │   │
-│   │   ├── inspector/
-│   │   │   ├── Inspector.tsx            # Dispatcher (role/channel/edge/team)
-│   │   │   ├── RoleInspector.tsx        # Tabs: Identity, Communication, Capabilities
-│   │   │   ├── ChannelInspector.tsx     # Signal list editor, emitter/subscriber summary
-│   │   │   ├── EdgeInspector.tsx        # Signal/route details (read-only for derived)
-│   │   │   ├── TeamInspector.tsx        # Name, enforcement, extension metadata
-│   │   │   └── PromptEditor.tsx         # Inline markdown editor for role prompts
-│   │   │
-│   │   ├── sidebar/
-│   │   │   ├── Sidebar.tsx              # Block palette + config tree
-│   │   │   ├── ConfigTree.tsx           # Hierarchical template view
-│   │   │   └── TemplateGallery.tsx      # Load from bundled example templates
-│   │   │
-│   │   ├── toolbar/
-│   │   │   ├── Toolbar.tsx              # Top action bar
-│   │   │   ├── LayerToggle.tsx          # Toggle visibility of edge types
-│   │   │   ├── ValidationBar.tsx        # Real-time validation status
-│   │   │   ├── ImportModal.tsx          # YAML import dialog (paste or upload)
-│   │   │   └── ExportModal.tsx          # Multi-file YAML preview + copy/download
-│   │   │
-│   │   └── shared/
-│   │       ├── CapabilityInput.tsx       # Tag-style capability editor
-│   │       ├── SignalPicker.tsx          # Autocomplete for signal names
-│   │       ├── ArrayInput.tsx           # Generic multi-value input
-│   │       └── ThemeToggle.tsx          # Dark/light mode switch
-│   │
-│   ├── stores/
-│   │   ├── canvas-store.ts              # Nodes, edges, selection state
-│   │   ├── config-store.ts              # Roles, channels, team metadata, prompts
-│   │   ├── history-store.ts             # Undo/redo state snapshots
-│   │   ├── validation-store.ts          # Errors/warnings per node
-│   │   └── ui-store.ts                  # Panel visibility, active layers
-│   │
-│   ├── lib/
-│   │   ├── serializer.ts               # Config <-> Canvas bidirectional conversion
-│   │   ├── auto-layout.ts              # Dagre hierarchical layout
-│   │   ├── validator.ts                # Schema + semantic validation (browser-safe)
-│   │   ├── compiler.ts                 # Canvas -> multi-file YAML output
-│   │   └── signal-catalog.ts           # Known signal name suggestions
-│   │
-│   └── hooks/
-│       ├── use-validation.ts            # Debounced validation on state change
-│       ├── use-keyboard.ts              # Ctrl+Z/Y, Delete, Ctrl+I shortcuts
-│       └── use-autosave.ts              # localStorage persistence
-│
-├── tests/
-│   ├── serializer.test.ts              # Round-trip conversion tests
-│   ├── validator.test.ts               # Validation rule tests
-│   └── compiler.test.ts                # YAML output tests
-│
-├── index.html
-├── package.json
-├── vite.config.ts
-├── tsconfig.json
-└── tailwind.config.ts
-```
-
-### Relationship to Main Package
-
-The editor is a **standalone Vite app** in the `editor/` directory. It imports OpenTeams types via a path alias:
-
-```typescript
-// vite.config.ts
-resolve: {
-  alias: {
-    '@openteams': path.resolve(__dirname, '../src'),
-  },
-}
-```
-
-This gives the editor access to `TeamManifest`, `CommunicationConfig`, `RoleDefinition`, etc. from `src/template/types.ts` without duplicating type definitions. The editor does not import any Node.js-specific code (database, services, spawner).
-
----
-
-## 3. Data Model
-
-### 3.1 Editor Types
-
-```typescript
-// types/editor.ts
-
-// ── Node Data ──────────────────────────────────────────
-
-interface RoleNodeData {
-  kind: 'role';
-  roleName: string;                    // Key in roles list
-  displayName: string;                 // From role definition
-  description: string;
-  topologyPosition: 'root' | 'companion' | 'spawned';
-  model?: string;                      // From topology node config
-  capabilities: string[];
-  extends?: string;                    // Parent role name
-  emits: string[];                     // Signal names this role emits
-  subscribesTo: SubscriptionSummary[]; // Channel+signal subscriptions
-  peerRoutesOut: number;               // Count of outgoing peer routes
-  peerRoutesIn: number;                // Count of incoming peer routes
-  canSpawn: string[];                  // Roles this role can spawn
-  errors: string[];                    // Validation errors
-  warnings: string[];                  // Validation warnings
-}
-
-interface SubscriptionSummary {
-  channel: string;
-  signals: string[] | 'all';          // 'all' when no filter
-}
-
-interface ChannelNodeData {
-  kind: 'channel';
-  channelName: string;
-  description: string;
-  signals: string[];
-  emitterCount: number;               // Derived: how many roles emit to this
-  subscriberCount: number;            // Derived: how many roles subscribe
-}
-
-// ── Edge Data ──────────────────────────────────────────
-
-interface PeerRouteEdgeData {
-  kind: 'peer-route';
-  signals: string[];                   // Signals carried on this route
-  via: 'direct' | 'topic' | 'scope';
-}
-
-interface SignalFlowEdgeData {
-  kind: 'signal-flow';
-  direction: 'emission' | 'subscription';
-  channel: string;
-  signals: string[];                   // Specific signals, or all if empty
-}
-
-interface SpawnEdgeData {
-  kind: 'spawn';
-}
-
-// ── Unions ─────────────────────────────────────────────
-
-type EditorNode = Node<RoleNodeData, 'role'> | Node<ChannelNodeData, 'channel'>;
-type EditorEdge =
-  | Edge<PeerRouteEdgeData>
-  | Edge<SignalFlowEdgeData>
-  | Edge<SpawnEdgeData>;
-
-// ── Canvas State ───────────────────────────────────────
-
-interface CanvasState {
-  nodes: EditorNode[];
-  edges: EditorEdge[];
-  viewport: { x: number; y: number; zoom: number };
-}
-```
-
-### 3.2 Config Store Types
-
-```typescript
-// Stored separately from canvas (not embedded in node data)
-
-interface EditorRoleConfig {
-  name: string;
-  displayName: string;
-  description: string;
-  extends?: string;
-  capabilities: string[];
-  promptContent?: string;             // Inline markdown (primary prompt)
-  additionalPrompts?: { name: string; content: string }[];
-}
-
-interface EditorTeamConfig {
-  name: string;
-  description: string;
-  version: 1;
-  enforcement: 'strict' | 'permissive' | 'audit';
-  extensions: Record<string, unknown>; // gsd:, bmad:, etc.
-}
-```
-
----
-
-## 4. Visual Design
-
-### 4.1 Layout
-
-```
-┌──────────────────────────────────────────────────────────────────┐
-│  Toolbar                                                          │
-│  [=] New  Import  Export  |  Auto Layout  |  Undo Redo  |  [?]  │
-│  Layer: [Peer Routes ✓] [Channels ✓] [Spawn Rules] [Inheritance] │
-├────────────┬─────────────────────────────────┬───────────────────┤
-│            │                                 │                   │
-│  Sidebar   │         Canvas                  │    Inspector      │
-│  (240px)   │      (React Flow)               │    (340px)        │
-│            │                                 │                   │
-│  Blocks    │   ┌──────────┐   ┌──────────┐   │  [Role Inspector] │
-│  ────────  │   │ research │───│ roadmap  │   │                   │
-│  ● Role    │   │ -synth.  │   │ -per     │   │  Identity         │
-│  ◆ Channel │   └──────────┘   └──────────┘   │  Communication    │
-│            │        │              │          │  Capabilities     │
-│  Config    │   ┌────┴────┐   ┌────┴────┐     │  Prompts          │
-│  ────────  │   │ planner │◄──│ plan-   │     │                   │
-│  Tree view │   │         │──►│ checker │     │                   │
-│            │   └─────────┘   └─────────┘     │                   │
-│            │                                 │                   │
-│  Gallery   │   Background grid + minimap     │                   │
-│  ────────  │   Controls (zoom/fit)           │                   │
-│  Templates │                                 │                   │
-│            │                                 │                   │
-├────────────┴─────────────────────────────────┴───────────────────┤
-│  Validation Bar: ✓ 12 roles, 4 channels, 0 errors, 2 warnings   │
-└──────────────────────────────────────────────────────────────────┘
-```
-
-### 4.2 Node Types
-
-#### RoleNode
-
-```
-┌─────────────────────────────────────┐
-│  ★ orchestrator               opus  │  ← topology badge + model
-│  GSD Orchestrator                   │  ← display_name (muted)
-├─────────────────────────────────────┤
-│  command-routing · wave-orch. · +3  │  ← capabilities (truncated)
-├─────────────────────────────────────┤
-│  ▲ emits 3    ▼ subs 4    → routes 2│  ← signal summary
-└─────────────────────────────────────┘
-  ●                                 ●     ← handles (left=target, right=source)
-```
-
-**Topology-based styling:**
-
-| Position | Border | Badge | Default Color |
-|---|---|---|---|
-| root | 2px solid | ★ | Blue (#3b82f6) |
-| companion | 2px solid | ◆ | Teal (#14b8a6) |
-| spawned | 1px dashed | (none) | Gray (#6b7280) |
-
-**State-based border overrides:**
-- Validation errors: red border
-- Validation warnings: yellow border
-- Selected: amber/orange border
-
-#### ChannelNode
-
-```
-┌───────────────────────────────┐
-│  ◆ planning_events            │
-│  "Planning and research..."   │
-├───────────────────────────────┤
-│  RESEARCH_COMPLETE            │
-│  ROADMAP_READY                │
-│  PLAN_READY                   │
-│  PLAN_VALIDATED               │
-│  PLAN_REJECTED                │
-├───────────────────────────────┤
-│  3 emitters · 4 subscribers   │
-└───────────────────────────────┘
-```
-
-**Styling:** Purple (#8b5cf6) border, smaller than role nodes. Rounded corners.
-
-### 4.3 Edge Types
-
-| Edge | Style | When Visible | Label |
-|---|---|---|---|
-| **PeerRouteEdge** | Bold (2.5px), colored (#f59e0b amber) | Layer: Peer Routes | Signal names |
-| **SignalFlowEdge** | Medium (1.5px), muted (#6b7280) | Layer: Channels | Channel name |
-| **SpawnEdge** | Thin dashed (1px), light gray | Layer: Spawn Rules | "can spawn" |
-
-All edges use Bezier curves with invisible wider hit areas (16px) for hover/selection.
-
-**PeerRouteEdge** is the highest-priority visual element — these represent the actual handoff patterns that drive workflow (e.g., `planner ↔ plan-checker` loop, `research-synthesizer → roadmapper` handoff).
-
-**SignalFlowEdge** connects roles to/from channel nodes. These are medium priority — they show the pub/sub topology.
-
-**SpawnEdge** is lowest priority and off by default — spawn rules are important for config but less relevant for understanding communication flow.
-
-### 4.4 Layer System
-
-The toolbar contains toggle buttons that control edge visibility:
-
-| Layer | Default | Controls |
-|---|---|---|
-| Peer Routes | **ON** | PeerRouteEdge visibility |
-| Channels | **ON** | ChannelNode + SignalFlowEdge visibility |
-| Spawn Rules | OFF | SpawnEdge visibility |
-| Inheritance | OFF | Dashed edge for `extends` relationships |
-
-When **Channels** layer is OFF, channel nodes are hidden. Signal flow information is still available in the role inspector.
-
-Layer state is stored in `ui-store` and persisted via autosave.
-
----
-
-## 5. Stores
-
-### 5.1 Canvas Store (`canvas-store.ts`)
-
-```typescript
-interface CanvasStore {
-  // State
-  nodes: EditorNode[];
-  edges: EditorEdge[];
-  selectedNodeId: string | null;
-  selectedEdgeId: string | null;
-
-  // ReactFlow callbacks
-  onNodesChange: OnNodesChange<EditorNode>;
-  onEdgesChange: OnEdgesChange<EditorEdge>;
-
-  // Actions
-  setSelection(nodeId: string | null, edgeId: string | null): void;
-  addNode(node: EditorNode): void;
-  removeNode(nodeId: string): void;
-  addEdge(edge: EditorEdge): void;
-  removeEdge(edgeId: string): void;
-  updateNodeData(nodeId: string, data: Partial<RoleNodeData | ChannelNodeData>): void;
-
-  // Serialization
-  loadFromConfig(manifest: TeamManifest, roles: Map<string, RoleDefinition>): void;
-  applyAutoLayout(): void;
-}
-```
-
-### 5.2 Config Store (`config-store.ts`)
-
-```typescript
-interface ConfigStore {
-  // State
-  team: EditorTeamConfig;
-  roles: Map<string, EditorRoleConfig>;
-  channels: Record<string, ChannelDefinition>;
-  subscriptions: Record<string, SubscriptionEntry[]>;
-  emissions: Record<string, string[]>;
-  peerRoutes: PeerRoute[];
-  spawnRules: Record<string, string[]>;
-  topologyRoot: string;               // Role name of root
-  topologyCompanions: string[];       // Role names of companions
-
-  // Actions
-  setTeam(team: Partial<EditorTeamConfig>): void;
-  setRole(name: string, role: EditorRoleConfig): void;
-  removeRole(name: string): void;
-  renameRole(oldName: string, newName: string): void;
-  setChannel(name: string, channel: ChannelDefinition): void;
-  removeChannel(name: string): void;
-  setSubscriptions(role: string, subs: SubscriptionEntry[]): void;
-  setEmissions(role: string, signals: string[]): void;
-  addPeerRoute(route: PeerRoute): void;
-  removePeerRoute(index: number): void;
-  setSpawnRules(role: string, canSpawn: string[]): void;
-  setTopologyRoot(role: string): void;
-  setTopologyCompanions(roles: string[]): void;
-
-  // Serialization
-  loadFromConfig(manifest: TeamManifest, roles: Map<string, RoleDefinition>): void;
-  toManifest(): TeamManifest;
-  toRoleDefinitions(): Map<string, RoleDefinition>;
-}
-```
-
-### 5.3 History Store (`history-store.ts`)
-
-```typescript
-interface HistoryStore {
-  undoStack: Snapshot[];              // Max 50
-  redoStack: Snapshot[];
-  pushSnapshot(): void;               // Deep-clone canvas + config stores
-  undo(): void;
-  redo(): void;
-  canUndo(): boolean;
-  canRedo(): boolean;
-}
-
-interface Snapshot {
-  canvas: { nodes: EditorNode[]; edges: EditorEdge[] };
-  config: { /* all config-store fields */ };
-}
-```
-
-### 5.4 Validation Store (`validation-store.ts`)
-
-```typescript
-interface ValidationStore {
-  errors: ValidationIssue[];
-  warnings: ValidationIssue[];
-  isValidating: boolean;
-  setResults(errors: ValidationIssue[], warnings: ValidationIssue[]): void;
-}
-
-interface ValidationIssue {
-  path: string;                        // e.g. "communication.emissions.planner"
-  message: string;
-  severity: 'error' | 'warning';
-  nodeId?: string;                     // For highlighting on canvas
-}
-```
-
-### 5.5 UI Store (`ui-store.ts`)
-
-```typescript
-interface UIStore {
-  sidebarOpen: boolean;
-  inspectorOpen: boolean;
-  importModalOpen: boolean;
-  exportModalOpen: boolean;
-  layers: {
-    peerRoutes: boolean;              // default: true
-    channels: boolean;                // default: true
-    spawnRules: boolean;              // default: false
-    inheritance: boolean;             // default: false
-  };
-  toggleSidebar(): void;
-  toggleInspector(): void;
-  toggleLayer(layer: keyof UIStore['layers']): void;
-}
-```
-
----
-
-## 6. Serialization
-
-### 6.1 Import: YAML -> Canvas
-
-`serializer.ts: configToCanvas(manifest, roleDefinitions)`
-
-**Input:** `TeamManifest` (parsed team.yaml) + `Map<string, RoleDefinition>` (parsed roles/*.yaml)
-
-**Algorithm:**
-
-```
-1. Create RoleNodes
-   For each role in manifest.roles:
-     a. Look up RoleDefinition (if exists)
-     b. Determine topology position:
-        - manifest.topology.root.role → 'root'
-        - manifest.topology.companions[].role → 'companion'
-        - else → 'spawned'
-     c. Extract model from topology node config (if exists)
-     d. Look up emissions for this role
-     e. Look up subscriptions for this role
-     f. Count peer routes from/to this role
-     g. Look up spawn rules for this role
-     h. Create EditorNode with RoleNodeData
-
-2. Create ChannelNodes
-   For each channel in manifest.communication.channels:
-     a. Count emitters (roles that emit any of this channel's signals)
-     b. Count subscribers (roles with subscriptions to this channel)
-     c. Create EditorNode with ChannelNodeData
-
-3. Create PeerRouteEdges
-   For each route in manifest.communication.routing.peers:
-     a. Create edge: source=role-{from}, target=role-{to}
-     b. Data: signals, via
-
-4. Create SignalFlowEdges
-   For each role in emissions:
-     For each signal the role emits:
-       a. Find which channel contains this signal
-       b. Create edge: source=role-{role}, target=channel-{channel}
-       c. Data: direction='emission', channel, signals
-   For each role in subscriptions:
-     For each subscription entry:
-       a. Create edge: source=channel-{channel}, target=role-{role}
-       b. Data: direction='subscription', channel, signals (or all)
-
-5. Create SpawnEdges
-   For each role in spawn_rules:
-     For each target in spawn_rules[role]:
-       a. Create edge: source=role-{role}, target=role-{target}
-       b. Data: kind='spawn'
-
-6. Apply dagre auto-layout
-   Return CanvasState { nodes, edges, viewport }
-```
-
-### 6.2 Export: Canvas -> YAML
-
-`compiler.ts: canvasToYaml(canvasStore, configStore)`
-
-**Output:** `Map<string, string>` — filepath → YAML content
-
-**Algorithm:**
-
-```
-1. Build team.yaml
-   a. team name, description, version from config store
-   b. roles: all role names from config store
-   c. topology:
-      root: { role: topologyRoot, config: { model } }
-      companions: topologyCompanions.map(role => ({ role, config: { model } }))
-      spawn_rules: from config store
-   d. communication:
-      enforcement: from config store
-      channels: from config store
-      subscriptions: from config store
-      emissions: from config store
-      routing.peers: from config store
-   e. Extension fields: from config store (pass-through)
-   f. Serialize with js-yaml
-
-2. Build roles/<name>.yaml for each role
-   a. name, display_name, description, capabilities
-   b. extends (if set)
-   c. Serialize with js-yaml
-
-3. Build prompts (as content map, not files)
-   For each role with promptContent:
-     a. prompts/<role>/ROLE.md → promptContent
-     b. Additional prompts → prompts/<role>/<name>.md
-
-4. Return Map<filepath, content>
-```
-
-### 6.3 YAML Serialization Options
-
-```typescript
-yaml.dump(config, {
-  lineWidth: -1,          // No auto-wrapping
-  noRefs: true,           // No YAML anchors/aliases
-  quotingType: '"',       // Double quotes when needed
-  forceQuotes: false,     // Smart quoting
-  sortKeys: false,        // Preserve insertion order
-});
-```
-
----
-
-## 7. Validation
-
-### 7.1 Validation Pipeline
-
-Triggered on every state change (debounced 300ms via `use-validation` hook).
-
-**Layer 1: JSON Schema** (AJV)
-- Validate assembled config against `team.schema.json` and `role.schema.json`
-- These schemas are already defined in `schema/` — reuse directly
-
-**Layer 2: Topology Integrity**
-- Exactly one root role
-- Root and all companion roles exist in the roles list
-- All roles referenced in spawn_rules exist in the roles list
-- No role appears as both root and companion
-
-**Layer 3: Communication Integrity**
-- Every signal in emissions exists in at least one channel's signal list
-- Every signal in subscription filters exists in its channel's signal list
-- Every channel referenced in subscriptions exists in channels
-- Every role in subscriptions/emissions exists in the roles list
-- Peer route from/to roles exist in the roles list
-
-**Layer 4: Inheritance Integrity**
-- No circular `extends` chains
-- Referenced parent roles exist
-- Capability composition is valid (removed capabilities exist on parent)
-
-**Layer 5: Semantic Warnings** (non-blocking)
-- Roles with no subscriptions and not reachable via spawn rules from root
-- Signals defined in a channel but never emitted by any role
-- Signals defined in a channel but never subscribed to by any role
-- Roles that emit signals but have no emission entry (permissive mode)
-- Peer routes carrying signals not defined in any channel
-
-### 7.2 Error Display
-
-- **Per-node**: Error/warning badge count on node corners
-- **Validation bar**: Summary in bottom toolbar ("12 roles, 4 channels, 0 errors, 2 warnings")
-- **Inspector**: Detailed error list when node selected
-- **Node highlighting**: Red/yellow border for nodes with errors/warnings
-
----
-
-## 8. Inspector Panels
-
-### 8.1 RoleInspector (4 tabs)
-
-**Tab 1: Identity**
-```
-Name:           [orchestrator      ]
-Display Name:   [GSD Orchestrator  ]
-Description:    [Command-level...  ]
-                [                  ]
-Model:          [sonnet ▼]
-Position:       [root ▼]  (root / companion / spawned)
-Extends:        [— none — ▼]  (dropdown of other roles)
-```
-
-**Tab 2: Communication**
-```
-Emits:
-  [PROJECT_INITIALIZED] [PHASE_STARTED] [WAVE_STARTED] [+]
-
-Subscribes:
-  ┌─────────────────────────────────────────┐
-  │ project_lifecycle     (all signals)  [×]│
-  │ planning_events       (all signals)  [×]│
-  │ execution_events      (all signals)  [×]│
-  │ verification_events   (all signals)  [×]│
-  └─────────────────────────────────────────┘
-  [+ Add Subscription]
-
-Peer Routes (outgoing):
-  → roadmapper via direct [RESEARCH_COMPLETE]
-  [+ Add Route]
-
-Peer Routes (incoming):
-  ← verifier via direct [GAPS_FOUND]
-```
-
-**Tab 3: Capabilities**
-```
-Capabilities:
-  [command-routing    ×]
-  [wave-orchestration ×]
-  [state-management   ×]
-  [checkpoint-handling×]
-  [context-budgeting  ×]
-  [+ Add capability             ]
-
-Spawn Rules (can spawn):
-  [✓] roadmapper
-  [✓] planner
-  [✓] plan-checker
-  [✓] executor
-  [✓] verifier
-  [ ] debugger
-  ...
-```
-
-**Tab 4: Prompts**
-```
-Primary Prompt (ROLE.md):
-  ┌─────────────────────────────────────────┐
-  │ # GSD Orchestrator                      │
-  │                                         │
-  │ You are the command-level orchestrator   │
-  │ for the GSD multi-agent system...       │
-  │                                         │
-  │ ## Responsibilities                     │
-  │ - Route user commands to agent chains   │
-  │ - Manage project state transitions      │
-  │ ...                                     │
-  └─────────────────────────────────────────┘
-
-Additional Prompts:
-  ┌─ SOUL.md ──────────────────────────────┐
-  │ # Personality & Values                  │
-  │ ...                                     │
-  └─────────────────────────────────────────┘
-  [+ Add Prompt Section]
-```
-
-The markdown editor is a plain `<textarea>` with monospace font and basic syntax highlighting (headers, bold, lists). Not a full WYSIWYG editor — keeps it simple and predictable for prompt authoring.
-
-### 8.2 ChannelInspector
-
-```
-Name:           [planning_events    ]
-Description:    [Planning and research workflow signals]
-
-Signals:
-  [RESEARCH_COMPLETE ] [×]
-  [ROADMAP_READY     ] [×]
-  [PLAN_READY        ] [×]
-  [PLAN_VALIDATED    ] [×]
-  [PLAN_REJECTED     ] [×]
-  [+ Add Signal                    ]
-
-Emitters (derived, read-only):
-  project-researcher  → RESEARCH_COMPLETE
-  roadmapper          → ROADMAP_READY
-  planner             → PLAN_READY
-  plan-checker        → PLAN_VALIDATED, PLAN_REJECTED
-
-Subscribers (derived, read-only):
-  orchestrator        ← all signals
-  roadmapper          ← RESEARCH_COMPLETE
-  planner             ← ROADMAP_READY, PLAN_REJECTED
-  plan-checker        ← PLAN_READY
-```
-
-### 8.3 TeamInspector (nothing selected)
-
-```
-Team Name:      [gsd      ]
-Description:    [GSD — prompt-native multi-agent...]
-                [                                  ]
-Version:        1 (read-only)
-Enforcement:    [permissive ▼]
-
-Extension Metadata:
-  ┌─ gsd: ─────────────────────────────────┐
-  │ context_management:                     │
-  │   description: "Each spawned agent..."  │
-  │   plan_budget: "50%"                    │
-  │ execution_model:                        │
-  │   type: "wave-based-parallel"           │
-  │ ...                                     │
-  └─────────────────────────────────────────┘
-  (raw YAML editor, monospace textarea)
-```
-
-### 8.4 EdgeInspector
-
-**For PeerRouteEdge:**
-```
-Type: Peer Route
-From: [planner]  →  To: [plan-checker]
-Via:  [direct ▼]
-Signals:
-  [PLAN_READY] [×]
-  [+ Add Signal]
-[Delete Route]
-```
-
-**For SignalFlowEdge (read-only):**
-```
-Type: Signal Flow (emission)
-Role: planner
-Channel: planning_events
-Signal: PLAN_READY
-(Modify in Role Inspector → Communication tab)
-```
-
----
-
-## 9. Interactions
-
-### 9.1 Creating Nodes
-
-**Drag from sidebar:**
-1. Sidebar palette has draggable blocks: "Role" and "Channel"
-2. User drags block onto canvas
-3. `onDrop` handler parses MIME data, creates node at drop position
-4. For Role: creates a default `EditorRoleConfig` in config store + `RoleNode` on canvas
-5. For Channel: prompts for name, creates `ChannelDefinition` in config store + `ChannelNode` on canvas
-6. Pushes history snapshot
-
-**Double-click on canvas:**
-1. Opens QuickAddMenu at mouse position
-2. Options: "New Role", "New Channel"
-3. Same creation flow as drag-and-drop
-
-### 9.2 Creating Edges
-
-**Peer route (drag handle to handle):**
-1. User drags from a role's right handle to another role's left handle
-2. `onConnect` callback fires, stores pending connection
-3. SignalPicker dialog opens — user selects signals for this route
-4. On confirm: creates PeerRouteEdge + updates config store (adds to peerRoutes)
-5. Pushes history snapshot
-
-**Signal flow edges are derived, not manually created.** They are computed from the config store's emissions and subscriptions. When a user adds an emission or subscription in the inspector, the corresponding edges appear automatically.
-
-**Spawn edges are derived from spawn rules.** Updated via the role inspector's spawn rules checkboxes.
-
-### 9.3 Selection
-
-- Click node → select node, deselect edge
-- Click edge → select edge, deselect node
-- Click canvas background → deselect all → show TeamInspector
-- Selection state in canvas store drives Inspector panel content
-
-### 9.4 Deletion
-
-- Select node/edge → press Delete/Backspace
-- For RoleNode deletion:
-  - Remove from config store (role, emissions, subscriptions, spawn rules, peer routes)
-  - Remove all connected edges
-  - Push history snapshot
-- For ChannelNode deletion:
-  - Remove channel definition
-  - Remove all subscriptions referencing it
-  - Remove all connected SignalFlowEdges
-  - Push history snapshot
-- For PeerRouteEdge deletion:
-  - Remove from config store peerRoutes
-  - Push history snapshot
-
-### 9.5 Import
-
-1. User clicks "Import" in toolbar → ImportModal opens
-2. Two input methods:
-   - **Paste YAML**: textarea for team.yaml content + separate textareas for role YAMLs
-   - **Load Template**: dropdown of bundled example templates (gsd, bmad-method)
-3. On confirm:
-   - Parse YAML with js-yaml
-   - Call `configToCanvas()` to build nodes + edges
-   - Load into canvas store + config store
-   - Apply auto-layout
-   - Clear history, push initial snapshot
-
-### 9.6 Export
-
-1. User clicks "Export" in toolbar → ExportModal opens
-2. Modal shows tabbed file preview:
-   - Tab per output file: `team.yaml`, `roles/orchestrator.yaml`, `roles/planner.yaml`, ...
-   - Each tab shows syntax-highlighted YAML
-   - Prompt files shown as additional tabs: `prompts/orchestrator/ROLE.md`, etc.
-3. Actions:
-   - **Copy** (per file): copies individual file content to clipboard
-   - **Copy All**: copies all files concatenated with `--- filename ---` separators
-   - **Download ZIP**: bundles all files into a downloadable zip
-
----
-
-## 10. Auto-Layout
-
-### Algorithm
-
-Uses `@dagrejs/dagre` with left-to-right hierarchical layout.
-
-```typescript
-// auto-layout.ts
-
-const ROLE_NODE_WIDTH = 280;
-const ROLE_NODE_HEIGHT = 120;
-const CHANNEL_NODE_WIDTH = 220;
-const CHANNEL_NODE_HEIGHT = 100;
-
-function computeLayout(nodes: EditorNode[], edges: EditorEdge[]): EditorNode[] {
-  const g = new dagre.graphlib.Graph();
-  g.setGraph({
-    rankdir: 'LR',         // Left-to-right
-    ranksep: 140,           // Horizontal spacing between ranks
-    nodesep: 60,            // Vertical spacing between nodes in same rank
-    marginx: 40,
-    marginy: 40,
-  });
-  g.setDefaultEdgeLabel(() => ({}));
-
-  for (const node of nodes) {
-    const isChannel = node.data.kind === 'channel';
-    g.setNode(node.id, {
-      width: isChannel ? CHANNEL_NODE_WIDTH : ROLE_NODE_WIDTH,
-      height: isChannel ? CHANNEL_NODE_HEIGHT : ROLE_NODE_HEIGHT,
-    });
-  }
-
-  for (const edge of edges) {
-    // Only layout based on visible edges (peer routes + signal flow)
-    // Skip spawn edges to avoid pulling layout
-    if (edge.data?.kind !== 'spawn') {
-      g.setEdge(edge.source, edge.target);
-    }
-  }
-
-  dagre.layout(g);
-
-  return nodes.map(node => {
-    const pos = g.node(node.id);
-    const isChannel = node.data.kind === 'channel';
-    const w = isChannel ? CHANNEL_NODE_WIDTH : ROLE_NODE_WIDTH;
-    const h = isChannel ? CHANNEL_NODE_HEIGHT : ROLE_NODE_HEIGHT;
-    return {
-      ...node,
-      position: { x: pos.x - w / 2, y: pos.y - h / 2 },
-    };
-  });
-}
-```
-
-The layout uses only peer routes and signal flow edges for positioning — spawn edges are excluded to prevent distorting the communication-centric layout.
-
----
-
-## 11. Template Gallery
-
-The editor bundles the existing example templates for quick loading:
-
-```typescript
-// Bundled as static JSON (compiled from YAML at build time)
-const BUNDLED_TEMPLATES = {
-  'gsd': { manifest: {...}, roles: {...} },
-  'bmad-method': { manifest: {...}, roles: {...} },
-};
-```
-
-The TemplateGallery component in the sidebar shows these as cards:
-
-```
-┌────────────────────────────────┐
-│  gsd                 │
-│  12 roles · 4 channels         │
-│  Wave-based parallel execution  │
-│  [Load]                        │
-├────────────────────────────────┤
-│  bmad-method                   │
-│  10 roles · 4 channels         │
-│  Full agile development team    │
-│  [Load]                        │
-└────────────────────────────────┘
-```
-
----
-
-## 12. Keyboard Shortcuts
-
-| Shortcut | Action |
-|---|---|
-| `Ctrl+Z` / `Cmd+Z` | Undo |
-| `Ctrl+Y` / `Cmd+Shift+Z` | Redo |
-| `Delete` / `Backspace` | Delete selected node or edge |
-| `Ctrl+I` / `Cmd+I` | Toggle inspector panel |
-| `Ctrl+E` / `Cmd+E` | Open export modal |
-| `Ctrl+Shift+L` | Apply auto-layout |
-| `Escape` | Deselect / close modal |
-
----
-
-## 13. Theme System
-
-CSS custom properties for dark/light mode, following the SDR editor pattern:
-
-```css
-:root {
-  --ot-bg: #ffffff;
-  --ot-surface: #f9fafb;
-  --ot-text: #111827;
-  --ot-text-muted: #6b7280;
-  --ot-border: #e5e7eb;
-  --ot-accent: #f59e0b;           /* Amber for selection */
-  --ot-role-root: #3b82f6;       /* Blue */
-  --ot-role-companion: #14b8a6;  /* Teal */
-  --ot-role-spawned: #6b7280;    /* Gray */
-  --ot-channel: #8b5cf6;         /* Purple */
-  --ot-peer-route: #f59e0b;      /* Amber */
-  --ot-signal-flow: #6b7280;     /* Gray */
-  --ot-spawn-edge: #d1d5db;      /* Light gray */
-  --ot-error: #ef4444;
-  --ot-warning: #eab308;
-  --ot-success: #22c55e;
-}
-
-.dark {
-  --ot-bg: #0f172a;
-  --ot-surface: #1e293b;
-  --ot-text: #f1f5f9;
-  --ot-text-muted: #94a3b8;
-  --ot-border: #334155;
-  /* ... accent and semantic colors stay the same */
-}
-```
-
----
-
-## 14. Phased Implementation Plan
-
-### Phase 1: Foundation (scaffold, types, canvas, basic nodes)
-
-**Goal:** Standalone Vite app with React Flow canvas that renders role and channel nodes from hardcoded data.
-
-**Tasks:**
-1. Scaffold `editor/` directory with Vite + React + TypeScript + Tailwind
-2. Configure `vite.config.ts` with `@openteams` path alias to `../src`
-3. Create `package.json` with all dependencies
-4. Define editor types in `types/editor.ts` (RoleNodeData, ChannelNodeData, edge data types)
-5. Implement `RoleNode.tsx` — memoized custom node with topology styling, capability summary, signal counts
-6. Implement `ChannelNode.tsx` — memoized custom node with signal list, emitter/subscriber counts
-7. Implement `Canvas.tsx` — ReactFlow container with node type registration, background grid, controls, minimap
-8. Implement `App.tsx` — root layout shell (sidebar placeholder, canvas, inspector placeholder)
-9. Create `node-styles.ts` — color constants, topology-based style functions
-10. Create CSS variables for theming (`index.css`)
-
-**Verification:** `npm run dev` renders a canvas with sample hardcoded role + channel nodes.
-
-### Phase 2: State Management (stores, serializer, auto-layout)
-
-**Goal:** Import a team.yaml + roles and render it on the canvas with auto-layout.
-
-**Tasks:**
-1. Implement `canvas-store.ts` — nodes, edges, selection, ReactFlow callbacks
-2. Implement `config-store.ts` — roles, channels, subscriptions, emissions, peer routes, spawn rules, topology
-3. Implement `history-store.ts` — undo/redo with snapshot deep-clone
-4. Implement `ui-store.ts` — sidebar, inspector, layers, modals
-5. Implement `validation-store.ts` — errors, warnings, isValidating
-6. Implement `serializer.ts: configToCanvas()` — full import pipeline (roles → nodes, communication → edges)
-7. Implement `auto-layout.ts: computeLayout()` — dagre LR layout with role/channel sizing
-8. Wire up canvas store to use serializer + layout for `loadFromConfig()`
-9. Bundle example templates (gsd, bmad-method) as static JSON
-10. Load gsd on startup as default, verify all nodes + edges render correctly
-11. Write round-trip tests for serializer: `configToCanvas` → `canvasToConfig` → assert structural equality
-
-**Verification:** Both gsd (12 roles, 4 channels) and bmad-method (10 roles, 4 channels) render correctly with auto-layout. All node types, edge types, and topology positions display properly.
-
-### Phase 3: Edge Types + Layer System
-
-**Goal:** Three distinct edge types with layer toggles to manage visual complexity.
-
-**Tasks:**
-1. Implement `PeerRouteEdge.tsx` — bold amber Bezier with signal labels, hover animation
-2. Implement `SignalFlowEdge.tsx` — medium gray Bezier with channel label, emission/subscription direction indicator
-3. Implement `SpawnEdge.tsx` — thin dashed gray with "can spawn" tooltip
-4. Implement `LayerToggle.tsx` — toolbar toggle buttons for 4 layers
-5. Wire layer visibility to edge filtering in Canvas (filter edges by `data.kind` + layer state)
-6. Wire channel node visibility to the Channels layer toggle
-7. Ensure selection works across all edge types
-8. Implement `EdgeInspector.tsx` — display edge details, editable for peer routes
-
-**Verification:** Toggling layers hides/shows the correct edges. GSD template's 5 peer routes are visually distinct from signal flow edges. Spawn rules can be toggled on to see the orchestrator's spawn tree.
-
-### Phase 4: Inspector + Editing
-
-**Goal:** Full property editing via inspector panels. Changes flow back to stores and canvas.
-
-**Tasks:**
-1. Implement `Inspector.tsx` — dispatcher based on selection state
-2. Implement `RoleInspector.tsx` — 4 tabs (Identity, Communication, Capabilities, Prompts)
-3. Implement `ChannelInspector.tsx` — signal list editor, derived emitter/subscriber lists
-4. Implement `TeamInspector.tsx` — team metadata + raw YAML extension editor
-5. Implement `PromptEditor.tsx` — monospace textarea for markdown prompt content
-6. Implement shared inputs: `CapabilityInput.tsx`, `SignalPicker.tsx`, `ArrayInput.tsx`
-7. Wire inspector edits back to config store → trigger derived edge recomputation
-8. Implement derived edge recomputation: when emissions/subscriptions change, rebuild SignalFlowEdges
-9. Connect history store: push snapshots before each inspector edit
-
-**Verification:** Select a role, edit its emissions in the inspector → signal flow edges update on canvas. Edit capabilities → node display updates. Write prompt content → stored in config store.
-
-### Phase 5: Canvas Interactions (create, connect, delete)
-
-**Goal:** Full interactive editing on the canvas itself.
-
-**Tasks:**
-1. Implement drag-and-drop from sidebar palette (Role + Channel blocks)
-2. Implement `QuickAddMenu.tsx` — double-click to add nodes
-3. Implement edge creation: drag handle → handle → SignalPicker dialog → create PeerRouteEdge
-4. Implement node/edge deletion via Delete key
-5. Implement `Sidebar.tsx` with block palette and `ConfigTree.tsx` for hierarchical view
-6. Implement `TemplateGallery.tsx` — load bundled templates
-7. Wire all interactions to history store for undo/redo
-8. Implement `use-keyboard.ts` — keyboard shortcuts
-
-**Verification:** Create a new team from scratch by dragging roles and channels, connecting peer routes, and editing properties. Undo/redo works across all operations.
-
-### Phase 6: Validation
-
-**Goal:** Real-time validation with per-node error/warning display.
-
-**Tasks:**
-1. Implement `validator.ts` — 5-layer validation pipeline (browser-safe, no fs)
-2. Import existing JSON schemas (`team.schema.json`, `role.schema.json`) for AJV validation
-3. Implement `use-validation.ts` hook — debounced 300ms, triggers on store changes
-4. Wire validation results to node data (update error/warning counts on nodes)
-5. Implement `ValidationBar.tsx` — bottom status bar with summary counts
-6. Add error/warning border styling to RoleNode and ChannelNode
-7. Write validation tests covering all 5 layers
-
-**Verification:** Delete a channel that has subscribers → error appears on subscribing roles. Add a signal to emissions that doesn't exist in any channel → warning. Circular inheritance → error.
-
-### Phase 7: Import/Export
-
-**Goal:** Full YAML import and multi-file export.
-
-**Tasks:**
-1. Implement `compiler.ts: canvasToYaml()` — convert stores to multi-file YAML output
-2. Implement `ImportModal.tsx` — paste YAML or load template
-3. Implement `ExportModal.tsx` — tabbed file preview with copy + download
-4. Implement multi-file YAML parsing for import (team.yaml + individual role YAMLs)
-5. Add "New" button that resets all stores
-6. Implement `signal-catalog.ts` — collect all known signal names for autocomplete
-7. Implement `use-autosave.ts` — localStorage persistence
-8. Implement `ThemeToggle.tsx` — dark/light mode
-9. Write compiler tests: build config → compile → parse output → assert matches input
-
-**Verification:** Import gsd template → edit roles → export → resulting YAML is valid and matches expected structure. Auto-save persists across browser refresh.
-
-### Phase 8: Polish + Testing
-
-**Goal:** Production-quality UX, comprehensive tests, and documentation.
-
-**Tasks:**
-1. Refine auto-layout for both template topologies (verify GSD and BMAD render cleanly)
-2. Add hover states, transitions, and animations to edges
-3. Responsive sidebar/inspector (collapsible on narrow viewports)
-4. Add validation for real-time feedback as user types (debounced input validation)
-5. Add "Fit View" button and initial viewport positioning
-6. Cross-browser testing (Chrome, Firefox, Safari)
-7. Write integration tests: full round-trip (import → edit → export → reimport → verify)
-8. Add `npm run dev` and `npm run build` scripts + verify production build
-9. Update project README and CLAUDE.md with editor documentation
-10. Add `openteams editor` CLI command that launches `vite dev` for the editor
-
----
-
-## Appendix A: Example Visualizations
-
-### A.1 gsd (Peer Routes + Channels ON)
-
-```
-                                                ┌──────────────────┐
-                                           ┌───→│ [planning_events]│───→ orchestrator
-    ┌────────────────┐   ┌──────────────┐  │    │ RESEARCH_COMPLETE│───→ roadmapper
-    │ project-       │──→│ research-    │──┘    │ ROADMAP_READY    │───→ planner
-    │ researcher     │   │ synthesizer  │═══════│ PLAN_READY       │───→ plan-checker
-    ├────────────────┤   └──────────────┘       │ PLAN_VALIDATED   │
-    │ phase-         │                          │ PLAN_REJECTED    │───→ planner
-    │ researcher     │──→ (also emits           └──────────────────┘
-    ├────────────────┤    RESEARCH_COMPLETE)
-    │ codebase-      │                    ┌─────────────────────────┐
-    │ mapper         │──→ ...             │ planner ◄══PLAN_REJECTED══ plan-checker
-    └────────────────┘                    │ planner ══PLAN_READY══► plan-checker
-                                          │ verifier ══GAPS_FOUND══► planner
- ┌──────────────┐                         └─────────────────────────┘
- │ ★ orchestrator│                            (peer route loop)
- │ (root)        │──emit──→ [project_lifecycle] ──sub──→ verifier
- └──────────────┘          [execution_events]  ──sub──→ executor
-                                                        integration-checker
-```
-
-### A.2 bmad-method (Peer Routes + Channels ON)
-
-```
-  ┌──────────┐    ┌────────┐    ┌─────────────┐    ┌──────────────┐
-  │ ★ master │    │ analyst│═══►│ pm          │═══►│ architect    │
-  │ (root)   │    │        │    │             │    │              │
-  └──────────┘    └────────┘    └──────┬──────┘    └──────┬───────┘
-       │                               │                   │
-       │                          ┌────┴─────┐       ┌─────┴──────┐
-       │                          │ux-designer│      │ scrum-master│
-       │                          └──────────┘       └──────┬──────┘
-       │                                                    │
-       │                                              ┌─────┴──────┐
-       │                                              │  developer │◄═══►
-       │                                              └─────┬──────┘
-       │                                                    │
-       │              ┌────────────┐                  ┌─────┴──┐
-       │              │ tech-writer│                  │   qa   │
-       │              └────────────┘                  └────────┘
-       │
-  ┌────┴──────────┐
-  │ quick-flow-dev│  (standalone)
-  └───────────────┘
-```
-
-### A.3 Node ID Conventions
-
-```
-Nodes:   role-{roleName}         e.g. role-orchestrator, role-planner
-         channel-{channelName}   e.g. channel-planning_events
-
-Edges:   peer-{from}-{to}-{index}     e.g. peer-planner-plan-checker-0
-         emit-{role}-{channel}         e.g. emit-planner-planning_events
-         sub-{channel}-{role}          e.g. sub-planning_events-planner
-         spawn-{from}-{to}             e.g. spawn-orchestrator-planner
-```
-
----
-
-## Appendix B: Decisions Log
-
-| Decision | Choice | Rationale |
-|---|---|---|
-| Channel nodes default visibility | ON (hidden = default OFF was considered) | Showing channels makes the pub/sub topology explicit; users can toggle off if noisy |
-| Extension metadata editor | Raw YAML textarea | Structured editors for gsd:/bmad: are low ROI for v1; schemas vary per system |
-| Prompt editing | Inline markdown textarea | Full WYSIWYG is overkill for prompt authoring; monospace textarea is closer to the file format |
-| Signal flow edges | Derived from config, not manually drawn | Manual edge creation for subscriptions/emissions would duplicate the inspector workflow and create sync issues |
-| Spawn edges | Hidden by default | Spawn rules add visual noise; less relevant for understanding communication flow |
-| Layout algorithm | Dagre LR, spawn edges excluded | LR matches the natural left-to-right flow; excluding spawn edges prevents layout distortion |
-| State management | Zustand (5 stores) | Matches SDR pattern, lightweight, no boilerplate |
-| Multi-file export | Tabbed preview + zip download | OpenTeams configs are multi-file (team.yaml + roles/*.yaml + prompts/); single-file export wouldn't be useful |