storybook/TEAM_PLAN.md

# Storybook Stabilization & Enhancement Team Plan

## Overview

This plan outlines a multi-agent team structure to tackle six critical workstreams:
1. **LSP Testing & Stabilization** - Comprehensive testing and bug fixing for the Language Server Protocol implementation
2. **Behavior Tree Refactoring** - Replacing symbolic syntax with human-friendly keywords (repeat, if, etc.)
3. **Resource Linking System** - Designing how to link behavior trees and schedules to characters and institutions
4. **SBIR Specification Validation** - Identifying gaps and missing elements in the IR spec
5. **Schedule System Enhancement** - Implementing year-long, composable schedule support
6. **Language Documentation** - Creating comprehensive, beginner-friendly documentation for non-programmer world builders

**Note:** The codebase uses "characters" not "entities". We can reuse existing infrastructure where possible.

## Team Structure

### Team Lead (Coordinator)
**Role:** Overall coordination, task assignment, progress tracking, and integration oversight

**Responsibilities:**
- Create and manage task board
- Assign tasks to specialists
- Monitor progress and unblock agents
- Coordinate dependencies between workstreams
- Synthesize findings into cohesive deliverables
- Handle final integration validation

---

### Agent 1: LSP Test Engineer
**Subagent Type:** `general-purpose` (needs full read/write/edit access)

**Primary Focus:** Testing and stabilizing the LSP implementation

**Assigned Tasks:**
- Task #1: Audit LSP implementation and create test strategy
- Task #2: Implement test suite and stabilization fixes

**Key Responsibilities:**
- Inventory all LSP features (hover, completion, go-to-definition, diagnostics, references, etc.)
- Analyze Tree-sitter grammar coverage
- Document current test coverage gaps
- Create comprehensive test strategy with prioritization
- Implement unit tests for each LSP feature
- Implement integration tests for multi-file scenarios
- Add edge case and error condition tests
- Fix identified stability issues
- Create regression tests
- Set up CI/CD for automated testing

**Deliverables:**
- LSP feature inventory document
- Test strategy and plan document
- Comprehensive test suite (unit + integration)
- Stability fixes and bug reports
- CI/CD configuration
- Testing documentation

**Success Criteria:**
- All LSP features have test coverage
- No known stability issues remain
- Tests run automatically in CI
- Documentation enables future contributors to add tests

---

### Agent 2: Behavior Tree Language Designer
**Subagent Type:** `general-purpose` (needs full read/write/edit access)

**Primary Focus:** Redesigning behavior tree syntax with human-friendly keywords

**Assigned Tasks:**
- Task #3: Analyze current syntax and design keyword system
- Task #4: Implement transformation system

**Key Responsibilities:**
- Catalog all current symbolic behavior tree representations
- Design keyword mappings:
  - Decorators: `repeat(N)`, `retry(N)`, `timeout(seconds)`, `cooldown(seconds)`, `invert`, `if(condition)`
  - Control: `if(condition)`, `sequence`, `selector`, `parallel`
  - Actions: Human-readable action calls
- Create comprehensive grammar specification
- Update Tree-sitter grammar
- Modify parser to support new keywords
- Update compiler to translate keywords → SBIR
- Implement backward compatibility (if needed)
- Validate with existing examples (Alice in Wonderland)
- Update language documentation

**Deliverables:**
- Current syntax inventory
- Keyword mapping specification
- Grammar design document
- Example transformations (before/after)
- Updated Tree-sitter grammar
- Parser modifications
- Compiler updates
- Migration guide (if backward compatibility breaks)
- Updated documentation with new syntax examples

**Success Criteria:**
- All symbolic constructs have keyword equivalents
- Syntax is intuitive and readable
- Parser handles new keywords correctly
- Compiler generates correct SBIR
- Examples validate successfully
- Documentation is complete

---

### Agent 3: Resource Linking Architect
**Subagent Type:** `general-purpose` (needs full read/write/edit access)

**Primary Focus:** Designing and implementing comprehensive linking system for behaviors and schedules

**Assigned Tasks:**
- Task #5: Design resource linking system (behaviors + schedules)
- Task #6: Implement linking system

**Important:** Agent must discuss design and implementation with user at key checkpoints to ensure correctness.

**Key Responsibilities:**

**Behavior Linking:**
- Design behavior linking mechanisms for **characters** (note: codebase uses "characters" not "entities"):
  - Direct assignment: `entity Alice { link behavior: WorkAtBakery }`
  - Multiple behaviors: `link behaviors: [WorkAtBakery, SocialRoutine, RestAndRecover]`
  - Priority system: `link behaviors: [{ tree: WorkAtBakery, priority: normal }, ...]`
  - Conditional selection: `link behavior: WorkAtBakery when role == baker`
  - Context-based: Link behaviors based on location/institution/state
- Design behavior linking for **institutions**:
  - Institution default behaviors: `institution Bakery { link behavior: BakeryOperations }`
  - Role-specific behaviors: `role worker { link behavior: BakeryWork }`

**Schedule Linking:**
- Design schedule linking mechanisms for **characters**:
  - Direct assignment: `entity Alice { link schedule: BakerSchedule }`
  - Conditional schedules: `link schedule: WorkdaySchedule when employed`
  - State-based schedules: Different schedules for different life arc states
  - Override system: Special schedules for events/holidays
- Design schedule linking for **institutions**:
  - Operating hours: `institution Bakery { link schedule: BakeryHours }`
  - Seasonal variations: `link schedule: WinterHours when season == winter`

**General Linking Design:**
- Design unified `link` keyword syntax
- Support linking in:
  - Character definitions
  - Species definitions (default links)
  - Template definitions (inherited links)
  - Institution definitions
  - Institution role definitions
- Design SBIR representation:
  - Link metadata in CHARACTERS section (currently ENTITIES in spec)
  - Link metadata in INSTITUTIONS section
  - Link resolution rules
  - Priority and selection metadata
- Reuse existing infrastructure where possible
- Consider use cases:
  - Character with multiple behaviors selected by context
  - Character schedule changes based on life events
  - Institution behaviors for different roles
  - Institution schedules (hours of operation)
  - Dynamic link resolution at runtime
- Coordinate with Behavior Tree Designer, Schedule Architect, and SBIR Analyst
- **Checkpoint 1:** Present linking design to user for review before implementation
- Implement parser support for `link` keyword (reuse existing parser infrastructure)
- Implement compiler translation to SBIR
- Create runtime link resolver
- **Checkpoint 2:** Review implementation approach with user before finalizing
- Validate with examples
- **Checkpoint 3:** Demo working implementation to user

**Deliverables:**
- Resource linking system architecture document
- Syntax specification for `link` keyword (behaviors + schedules)
- SBIR format proposal for links in CHARACTERS and INSTITUTIONS sections
- Selection/resolution algorithm specification
- Updated language syntax
- Parser modifications for `link` keyword
- Compiler updates
- Link resolver implementation
- Comprehensive examples:
  - Entity with linked behavior
  - Entity with linked schedule
  - Entity with multiple linked behaviors
  - Institution with linked behavior
  - Institution with linked schedule (operating hours)
  - Conditional/contextual linking
  - State-based linking
  - Priority-based selection
- Test suite for linking system
- Documentation

**Success Criteria:**
- Unified `link` keyword works for both behaviors and schedules
- Characters can link to behaviors AND schedules
- Institutions can link to behaviors AND schedules
- User has approved design and implementation approach
- Support for multiple links with selection rules
- Support for conditional/contextual selection
- Runtime resolver selects correct behavior/schedule
- Examples demonstrate real-world use cases
- SBIR encoding captures all linking semantics
- Integration with schedule system and life arcs works seamlessly

---

### Agent 4: Language Documentation Writer
**Subagent Type:** `general-purpose` (needs read access + ability to write documentation)

**Primary Focus:** Creating accessible, beginner-friendly language documentation for non-programmers

**Assigned Tasks:**
- Task #10: Create comprehensive language documentation for end users

**Key Responsibilities:**
- Create documentation for **non-technical world builders** (like Lonni)
- Document language from a **storyteller's perspective**, not a programmer's perspective
- Cover all language features with:
  - Clear, simple explanations
  - Practical examples from storytelling contexts
  - Progressive complexity (beginner → intermediate → advanced)
  - Common patterns and recipes
  - Troubleshooting guides
- Structure documentation by use case:
  - "Creating your first character"
  - "Making characters behave realistically"
  - "Setting up daily schedules"
  - "Creating relationships between characters"
  - "Designing locations and institutions"
  - "Making characters respond to events"
  - "Building complex behaviors"
- Document new features as they're implemented:
  - Human-friendly behavior tree keywords (from Task #3/#4)
  - Resource linking syntax (from Task #5/#6)
  - Schedule composition (from Task #8/#9)
- Include:
  - Tutorials
  - How-to guides
  - Reference documentation
  - Concept explanations
  - Glossary of terms
- Use consistent terminology throughout
- Coordinate with all other agents to document their features
- Get user feedback on documentation clarity

**Deliverables:**
- Getting Started Guide
- Language Tutorial (progressive lessons)
- Feature-by-feature reference
- Recipe/pattern library
- Troubleshooting guide
- Glossary
- Example storybooks (annotated)
- Quick reference card

**Success Criteria:**
- A non-programmer can learn the language from the documentation alone
- Documentation covers all language features
- Examples are compelling and storytelling-focused
- User (and test readers like Lonni) approve documentation clarity
- Documentation stays up-to-date with new features

---

### Agent 5: SBIR Specification Analyst
**Subagent Type:** `Explore` (read-only, deep analysis focus)

**Primary Focus:** Validating SBIR spec completeness and identifying gaps

**Assigned Tasks:**
- Task #7: Conduct comprehensive SBIR specification validation

**Key Responsibilities:**
- Review entire SBIR spec section-by-section
- Cross-reference spec against actual .sb language features
- Identify missing functionality:
  - Type system gaps
  - Missing instruction opcodes
  - Incomplete constraint system
  - Schedule representation limitations
  - **Behavior linking representation** (coordinate with Agent 3)
  - Debug information gaps
  - Extensibility concerns
- Identify ambiguities or underspecified semantics
- Validate against use cases (especially schedules and behavior linking)
- Check binary format efficiency
- Review codegen contract completeness
- Propose additions and modifications

**Deliverables:**
- Specification gap analysis report
- List of ambiguities requiring clarification
- Proposed additions organized by section
- Use case validation results
- Priority ranking of issues

**Success Criteria:**
- Every .sb language feature is representable in SBIR
- All ambiguities are documented
- Schedule system gaps are clearly identified
- Behavior linking gaps are clearly identified
- Codegen contract covers all implementation needs
- Spec is sufficient for third-party implementations

---

### Agent 6: Schedule System Architect
**Subagent Type:** `general-purpose` (needs full read/write/edit access)

**Primary Focus:** Designing and implementing year-long composable schedules

**Assigned Tasks:**
- Task #8: Design year-long composable schedule system
- Task #9: Implement schedule system

**Key Responsibilities:**
- Design schedule composition hierarchy:
  - Base: Daily schedule templates
  - Week: 7-day compositions with variations
  - Month: Weekly compositions with irregular handling
  - Season: Quarterly templates
  - Year: Full calendar year representation
- Design composition operators:
  - Inheritance (extends base schedule)
  - Override (replace blocks)
  - Merge (combine schedules)
  - Exception (one-off modifications)
- Design override system for:
  - Holidays and festivals
  - Special events
  - Seasonal variations
  - Life events
- Address calendar concerns:
  - Leap years
  - Different calendar systems
  - Date arithmetic
- **Design integration with resource linking:**
  - Schedule blocks can optionally specify behaviors
  - Behavior selection based on time of day via schedule
  - Schedule selection via `link schedule` in entities/institutions
  - Coordinate with Agent 3 (Resource Linking Architect)
- Design SBIR representation:
  - Schedule composition metadata
  - Efficient encoding for repetition
  - Override/exception format
  - Behavior references in schedule blocks
- Implement in language:
  - Syntax for schedule composition
  - Parser support
  - Compiler translation to SBIR
- Create runtime evaluation strategy
- Validate with realistic examples

**Deliverables:**
- Schedule system architecture document
- Composition operator specification
- SBIR format proposal (updates to section 9)
- Calendar system specification
- Updated language syntax for schedules
- Parser and compiler changes
- Schedule resolver/evaluator implementation
- Comprehensive examples:
  - Simple daily schedule
  - Weekly variations
  - Seasonal schedules
  - Holiday calendars
  - Year-long character schedules with behavior links
- Test suite for schedule composition
- Documentation

**Success Criteria:**
- Can represent schedules up to one calendar year
- Schedules are composable with clear semantics
- Schedules can reference behaviors
- Minimal redundancy in representation
- Examples demonstrate real-world use cases
- Implementation matches specification
- SBIR encoding is space-efficient
- Integration with behavior linking works correctly

---

## Task Breakdown & Dependencies

### Phase 1: Analysis & Design (Parallel)
Can be worked on simultaneously by different agents:

**Task #1:** Audit LSP implementation and create test strategy
- **Agent:** LSP Test Engineer
- **Dependencies:** None
- **Duration Estimate:** Research/analysis phase

**Task #3:** Analyze current behavior tree syntax and design keyword system
- **Agent:** Behavior Tree Language Designer
- **Dependencies:** None
- **Duration Estimate:** Design phase

**Task #5:** Design resource linking system (behaviors + schedules)
- **Agent:** Resource Linking Architect
- **Dependencies:** None (but should coordinate with Tasks #3, #7, and #8)
- **Duration Estimate:** Design phase

**Task #7:** Conduct comprehensive SBIR specification validation
- **Agent:** SBIR Specification Analyst (Agent 5)
- **Dependencies:** None
- **Duration Estimate:** Analysis phase

**Task #8:** Design year-long composable schedule system
- **Agent:** Schedule System Architect (Agent 6)
- **Dependencies:** None (but should coordinate with Task #5 for behavior linking)
- **Duration Estimate:** Design phase

---

### Phase 2: Implementation (Partially Parallel)

**Task #2:** Implement LSP test suite and stabilization fixes
- **Agent:** LSP Test Engineer
- **Dependencies:** Task #1 (test strategy must be complete)
- **Duration Estimate:** Implementation phase

**Task #4:** Implement behavior tree keyword transformation system
- **Agent:** Behavior Tree Language Designer
- **Dependencies:** Task #3 (design must be complete)
- **Duration Estimate:** Implementation phase

**Task #6:** Implement resource linking system
- **Agent:** Resource Linking Architect
- **Dependencies:** Task #5 (design must be complete), Task #4 (behavior tree syntax should be stable)
- **Duration Estimate:** Implementation phase

**Task #9:** Implement year-long composable schedule system
- **Agent:** Schedule System Architect (Agent 6)
- **Dependencies:** Task #8 (design must be complete), Task #6 (behavior linking should be implemented for integration)
- **Duration Estimate:** Implementation phase

**Task #10:** Create comprehensive language documentation for end users
- **Agent:** Language Documentation Writer (Agent 4)
- **Dependencies:** None initially, but continuously updated as Tasks #4, #6, #9 complete
- **Duration Estimate:** Ongoing throughout all phases

---

### Phase 3: Consolidation (Sequential)

**Task #11:** Update SBIR specification with all enhancements
- **Agent:** Team Lead (or designated spec writer)
- **Dependencies:** Tasks #3, #5, #7, #8 (all designs and analysis must be complete)
- **Duration Estimate:** Documentation phase

**Responsibilities:**
- Incorporate findings from SBIR validation (Task #7)
- Add year-long schedule system spec (Task #8 output)
- Add behavior tree keyword documentation (Task #3 output)
- Add entity-behavior linking spec (Task #5 output)
- Update ENTITIES section for behavior links
- Update SCHEDULES section for behavior references
- Update instruction set if needed
- Add new sections if required
- Update examples throughout
- Increment version number (likely 0.2.0)
- Create migration guide

**Deliverables:**
- Updated SBIR specification (v0.2.0)
- Migration guide from v0.1.0
- Version changelog
- Updated examples

---

### Phase 4: Integration & Validation (Final)

**Task #12:** Integration validation and documentation
- **Agent:** Team Lead + all agents for their domains
- **Dependencies:** Tasks #2, #4, #6, #9, #10 (all implementations and spec must be complete)
- **Duration Estimate:** Testing and documentation phase

**Responsibilities:**
- Run full integration tests across all systems
- Validate LSP with new behavior tree keywords AND linking syntax
- Validate compiler with new schedule system
- Validate behavior linking and selection at runtime
- Test schedule + behavior linking integration
- Test SBIR serialization/deserialization
- Run Alice in Wonderland example through full pipeline
- Create end-to-end examples demonstrating all features
- Update user documentation
- Create developer guide
- Document breaking changes
- Create release notes

**Deliverables:**
- Integration test results
- End-to-end examples showing:
  - Character with multiple behaviors
  - Schedule-based behavior selection
  - Conditional behavior linking
  - Full lifecycle from .sb → .sbc → runtime
- User documentation (updated)
- Developer guide
- Release notes for v0.2.0

**Success Criteria:**
- All systems work together seamlessly
- Can create entity with behaviors linked via all supported mechanisms
- Schedule integration with behaviors works correctly
- LSP supports all new syntax
- Examples validate end-to-end

---

## Dependency Graph

```
┌───────────────────────────────────────────────────────────────────────┐
│ Phase 1: Analysis & Design (Parallel, with coordination)             │
├───────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  Task #1: LSP Audit          Task #3: BT Design                      │
│  (LSP Test Engineer)         (BT Designer)                           │
│           │                           │                               │
│           │                           │ ← coordinates with →          │
│           │                           │                       ↓       │
│           │                  Task #5: Linking Design    Task #8: Sched│
│           │                  (Linking Architect)        (Sched Arch)  │
│           │                           │                       │       │
│           │                           │ ← coordinates with →  │       │
│           │                           │                               │
│  Task #7: SBIR Validation ←──────────┼───────────────────────────────│
│  (SBIR Analyst)                       │                               │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘
                              │
                              ↓
┌───────────────────────────────────────────────────────────────────────┐
│ Phase 2: Implementation (Partially Sequential)                        │
├───────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  Task #2: LSP Tests          Task #4: BT Implementation              │
│  (depends on #1)             (depends on #3)                         │
│                                       │                               │
│                                       ↓                               │
│                              Task #6: Linking Implementation          │
│                              (depends on #4, #5)                      │
│                                       │                               │
│                                       ↓                               │
│                              Task #9: Schedule Implementation         │
│                              (depends on #6, #8)                      │
│                                                                       │
│  ┌─────────────────────────────────────────────────────────┐         │
│  │ Task #10: Language Documentation (ongoing, updates as   │         │
│  │           features complete: #4, #6, #9)                │         │
│  └─────────────────────────────────────────────────────────┘         │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘
                              │
                              ↓
┌───────────────────────────────────────────────────────────────────────┐
│ Phase 3: Consolidation                                                │
├───────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  Task #11: Update SBIR Spec                                          │
│  (depends on Tasks #3, #5, #7, #8)                                   │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘
                              │
                              ↓
┌───────────────────────────────────────────────────────────────────────┐
│ Phase 4: Integration                                                  │
├───────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  Task #12: Integration Validation & Technical Docs                   │
│  (depends on Tasks #2, #4, #6, #9, #10, #11)                         │
│                                                                       │
│  Note: Task #10 (Language Docs) continues updating throughout        │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘
```

---

## Resource Linking: Design Considerations

### Linking Mechanisms to Support

#### 1. Character Behavior Linking

**Simple Direct Link:**
```sb
character Alice : Human {
  link behavior: CuriousExplorer
}
```

**Multiple Behaviors with Priorities:**
```sb
character Alice : Human {
  link behaviors: [
    { tree: HandleUrgentNeeds, priority: critical }
    { tree: WorkAtBakery, priority: normal, when: schedule.activity == work }
    { tree: SocialInteraction, priority: normal, when: schedule.activity == leisure }
    { tree: Sleep, priority: normal, when: schedule.activity == sleep }
    { tree: Idle, priority: low }
  ]
}
```

**Context-Based Behavior:**
```sb
character Alice : Human {
  link behaviors: [
    { tree: WorkAtBakery, when: at_location(Bakery) }
    { tree: HomeRoutine, when: at_location(Home) }
    { tree: Wander, default: true }
  ]
}
```

#### 2. Character Schedule Linking

**Direct Schedule Link:**
```sb
character Alice : Human {
  link schedule: BakerSchedule
}
```

**Conditional Schedule Link:**
```sb
character Alice : Human {
  link schedule: WorkdaySchedule when employed == true
  link schedule: UnemployedSchedule when employed == false
}
```

**State-Based Schedule:**
```sb
character Alice : Human {
  life_arc: PersonArc at Adult
  link schedules: [
    { schedule: ChildSchedule, when: state == Child }
    { schedule: AdultSchedule, when: state == Adult }
    { schedule: ElderSchedule, when: state == Elder }
  ]
}
```

#### 3. Institution Behavior Linking

**Institution-Level Behavior:**
```sb
institution Bakery {
  link behavior: BakeryOperations

  roles {
    owner {
      link behavior: ManageBakery
    }
    worker {
      link behavior: BakeryWork
    }
  }
}
```

**Contextual Institution Behavior:**
```sb
institution Bakery {
  link behaviors: [
    { tree: BusyService, when: customer_queue > 5 }
    { tree: NormalService, default: true }
  ]
}
```

#### 4. Institution Schedule Linking

**Operating Hours:**
```sb
institution Bakery {
  link schedule: BakeryHours
}
```

**Seasonal Schedules:**
```sb
institution Bakery {
  link schedules: [
    { schedule: SummerHours, when: season == summer }
    { schedule: WinterHours, when: season == winter }
    { schedule: StandardHours, default: true }
  ]
}
```

**Role-Specific Schedules:**
```sb
institution Bakery {
  roles {
    owner {
      link schedule: OwnerSchedule
    }
    worker {
      link schedule: WorkerSchedule
    }
  }
}
```

#### 5. Species Default Links

**Default Behavior and Schedule:**
```sb
species Human {
  components: HumanComponents
  link behaviors: [HandleBasicNeeds, SocialDrive, CuriosityDrive]
  link schedule: DefaultHumanSchedule
}
```

#### 6. Template Inherited Links

**Template with Links:**
```sb
template WonderlandCreature {
  link behavior: WonderlandBehavior
  link schedule: WonderlandSchedule
}

character CheshireCat : Cat using WonderlandCreature {
  // inherits links from template
  // can override with own links
  link behavior: CheshireBehavior  // overrides template
}
```

### SBIR Representation Questions

Agent 3 (Resource Linking Architect) should address:

**For Behavior Links:**
1. How are behavior references encoded in the CHARACTERS section (ENTITIES in spec)?
2. How are behavior references encoded in the INSTITUTIONS section?
3. How are selection rules/predicates encoded?
4. How are priorities represented?
5. How does the runtime resolve which behavior to execute?
6. Can multiple behaviors run simultaneously (parallel execution)?
7. How do conditions inject behaviors (override system)?

**For Schedule Links:**
8. How are schedule references encoded in the CHARACTERS section?
9. How are schedule references encoded in the INSTITUTIONS section?
10. How are conditional schedule links resolved at runtime?
11. How do schedule links interact with behavior links?
12. Can a character have both a direct schedule link AND schedule blocks with inline behaviors?

**General:**
13. What is the precedence order for link resolution (species → template → character)?
14. How are link overrides represented in SBIR?
15. What happens when multiple links match at runtime (conflict resolution)?
16. What existing infrastructure can be reused (parser, compiler, etc.)?

---

## Coordination Strategy

### Communication Patterns

1. **Phase Kickoffs:** Team lead provides context and coordinates agent startup for each phase
2. **Design Reviews with User:** After Tasks #1, #3, #5, #7, #8 complete, agents present designs to USER for approval before implementation
   - **Critical:** Task #5 (linking design) MUST be reviewed by user before Task #6 (implementation)
3. **Cross-Agent Coordination:**
   - Agent 3 (Linking) coordinates with Agent 2 (BT) on syntax
   - Agent 3 (Linking) coordinates with Agent 5 (Schedule) on integration
   - Agent 4 (SBIR) reviews all designs for spec implications
4. **Progress Updates:** Agents report completion and blockers to team lead AND user at checkpoints
5. **Implementation Checkpoints:** Agent 3 (Linking) discusses implementation approach with user before finalizing
6. **Integration Checkpoints:** Before Task #10, synchronize all design outputs
7. **Final Review:** Before Task #11, validate all implementations with user

### Handoff Points

- **LSP → BT Designer:** If LSP tests reveal issues with behavior tree parsing
- **BT Designer → Linking Architect:** Behavior tree syntax must be stable before implementing linking
- **Linking Architect → Schedule Architect:** Linking design informs schedule-behavior integration
- **SBIR Analyst → All Designers:** Gap analysis informs all designs
- **SBIR Analyst → Team Lead:** Findings inform Task #10 (spec updates)
- **All Designers → Team Lead:** Design outputs feed into Task #10
- **All Implementers → Team Lead:** Implementations validated in Task #11

---

## Risk Mitigation

### Potential Issues

1. **Backward Compatibility Breaks:** Behavior tree refactoring may break existing .sb files
   - **Mitigation:** Design migration path; consider supporting both syntaxes temporarily

2. **SBIR Binary Format Changes:** Schedule and linking enhancements will require breaking changes
   - **Mitigation:** Version bump to 0.2.0; provide conversion tooling

3. **LSP Instability During Development:** Changes to parser/compiler may break LSP
   - **Mitigation:** LSP tests run continuously; prioritize stability fixes

4. **Linking System Complexity:** Multiple linking mechanisms may create ambiguity
   - **Mitigation:** Clear precedence rules; comprehensive examples; runtime warnings for conflicts

5. **Scope Creep:** Each workstream could expand significantly
   - **Mitigation:** Strict adherence to task definitions; defer non-essential work

6. **Integration Failures:** Systems may not work together cleanly
   - **Mitigation:** Early integration checkpoints; continuous testing; coordination meetings

7. **Performance Concerns:** Complex behavior selection could impact runtime
   - **Mitigation:** Design efficient selection algorithm; benchmark early

---

## Success Metrics

### LSP Workstream
- [ ] 90%+ test coverage for LSP features
- [ ] Zero known critical bugs
- [ ] All LSP features work with new syntax (BT keywords + linking)
- [ ] CI tests pass

### Behavior Tree Workstream
- [ ] All symbolic constructs have keyword replacements
- [ ] Alice in Wonderland example validates with new syntax
- [ ] Documentation includes before/after examples
- [ ] Compiler generates correct SBIR

### Resource Linking Workstream
- [ ] User approves linking design (Checkpoint 1)
- [ ] Unified `link` keyword supports behaviors and schedules
- [ ] Character behavior linking works (single + multiple + conditional)
- [ ] Character schedule linking works (single + multiple + conditional)
- [ ] Institution behavior linking works
- [ ] Institution schedule linking works (operating hours)
- [ ] All linking mechanisms implemented and tested
- [ ] User approves implementation approach (Checkpoint 2)
- [ ] Clear syntax for all use cases
- [ ] Runtime link resolver works correctly for behaviors
- [ ] Runtime link resolver works correctly for schedules
- [ ] Examples demonstrate all linking patterns
- [ ] SBIR encoding captures all linking semantics
- [ ] Integration between behavior links and schedule links works
- [ ] User validates working implementation (Checkpoint 3)

### SBIR Validation Workstream
- [ ] All identified gaps documented
- [ ] Priority recommendations provided
- [ ] Schedule system requirements captured
- [ ] Linking system requirements captured
- [ ] Spec ambiguities clarified

### Schedule System Workstream
- [ ] Can represent 365-day schedules
- [ ] Schedules compose with clear semantics
- [ ] Schedules can reference behaviors
- [ ] Examples demonstrate real-world use
- [ ] SBIR encoding is efficient
- [ ] Runtime resolver works correctly
- [ ] Integration with behavior linking works

### Integration
- [ ] All systems work together seamlessly
- [ ] End-to-end pipeline validated (source → SBIR → runtime)
- [ ] Can create complex entities with schedules + behaviors
- [ ] Documentation complete
- [ ] Release ready

---

## Next Steps

1. **Review this plan** - Approve, modify, or expand as needed
2. **Prioritize workstreams** - Determine if any workstream is more critical
3. **Spawn team** - Create agents with assigned roles
4. **Phase 1 kickoff** - Start analysis and design tasks with coordination meetings
5. **Design review** - Gate between Phase 1 and Phase 2
6. **Implementation** - Execute Phase 2 tasks sequentially where needed
7. **Specification update** - Execute Task #10
8. **Integration** - Execute Task #11
9. **Release** - Publish v0.2.0 with all enhancements

---

## Questions for Review

1. **Linking mechanisms:** Are all the proposed linking mechanisms necessary? Should we start with a subset?
2. **Link keyword scope:** Should `link` be the unified keyword for both behaviors and schedules, or use `link behavior:` and `link schedule:` explicitly?
3. **Institution linking:** Should institutions support the same linking flexibility as entities, or a simpler subset?
4. **Agent allocation:** Should any workstream have multiple agents (e.g., separate linking designer and implementer)?
5. **Timeline:** Are there hard deadlines or priorities among the five workstreams?
6. **Backward compatibility:** How important is maintaining compatibility with v0.1.0?
7. **Scope:** Should we defer any feature (e.g., parallel behavior execution, complex conditional linking) to v0.3.0?
8. **Integration complexity:** Should linking and schedules be designed together from the start, or sequentially?
9. **Success criteria:** Are the metrics sufficient, or should we add more specific targets?
10. **Link resolution algorithm:** Should behavior/schedule selection be designed upfront, or emerge from the linking design?
11. **Schedule-behavior interaction:** When a schedule block specifies a behavior AND the entity has linked behaviors, which takes precedence?