stack/docs/reports/m4.1-orchestration-plan.md

# M4.1-Coordinator (0.0.4) - Orchestration Execution Plan

**Generated:** 2026-02-01
**Milestone Due:** 2026-02-22 17:59
**Total Issues:** 15
**Orchestrator:** Claude Sonnet 4.5

## Overview

This document tracks the autonomous development orchestration for the M4.1-Coordinator milestone. All coding tasks will be executed by specialized agents (Sonnet for standard tasks, Opus for complex tasks). Each task undergoes independent code review and QA gates that cannot be bypassed.

**Total Issues:** 21 (including 1 EPIC tracker, 1 documentation task, 19 implementation tasks)

## Execution Strategy

- **Maximum Parallel Agents:** 2
- **Quality Gates:** Mandatory for all code changes (via Quality Rails/Husky)
- **Code Review:** Independent review via pr-review-toolkit:code-reviewer
- **Token Tracking:** All estimates vs actuals recorded
- **Issue Closure:** All issues closed via git scripts with summary comments
- **EPIC Tracking:** Issue 142 (EPIC) closed when all child issues complete

## Monitoring Strategy

**Multi-layered automated monitoring:**

1. Real-time agent output logging to `docs/reports/agent-{issue#}-{timestamp}.log`
2. Quality gate enforcement via pre-commit hooks (already in place)
3. Post-implementation code review via pr-review-toolkit
4. Token usage tracking (estimate vs actual)
5. Dishonesty detection (monitoring for bypass attempts)

**Red flags triggering immediate intervention:**

- Modifications to `.git/hooks/`
- Use of `--no-verify` or bypass flags
- Trivial tests that don't validate functionality
- Completion claims without running quality gates
- Significant token overruns without justification

## Issue Dependency Map

```
Documentation (Start or End):
  140 (Document architecture) → Can run early or after implementation

Foundation Layer (Phase 0):
  156 (COORD-000) → 157 (COORD-001) → 158 (COORD-002) → 159 (COORD-003) → 160 (COORD-004) → 161 (COORD-005)

Context Management (Phase 1):
  143 (Validate 50% rule) ─┐
  154 (Context estimator) ─┼→ [Required for Phase 2]
  155 (Context monitor)   ─┘

Agent Assignment (Phase 2):
  144 (Agent profiles) → 145 (Assignment algorithm) → 146 (Test assignment)

Quality Layer (Phase 3):
  147 (Core gates) → 148 (Quality Orchestrator) → 149 (Test rejection loop)

Advanced Orchestration (Phase 4):
  150 (Orchestration loop) → 151 (Compaction) → 152 (Session rotation) → 153 (E2E test)

EPIC Tracker:
  142 (EPIC) → Closes when all child issues (140, 143-161) complete
```

## Execution Phases

### Documentation Task

| Issue | Title                               | Est. Tokens | Agent  | Blocks | Status          |
| ----- | ----------------------------------- | ----------- | ------ | ------ | --------------- |
| 140   | Document Non-AI Coordinator Pattern | TBD         | sonnet | -      | verify/complete |

### Phase 0: Foundation (Sequential Chain)

| Issue | Title                       | Est. Tokens | Agent  | Blocks | Status  |
| ----- | --------------------------- | ----------- | ------ | ------ | ------- |
| 156   | Create coordinator bot user | 15,000      | haiku  | 157    | pending |
| 157   | Set up webhook receiver     | 52,000      | sonnet | 158    | pending |
| 158   | Implement issue parser      | 46,800      | sonnet | 159    | pending |
| 159   | Implement queue manager     | 58,500      | sonnet | 160    | pending |
| 160   | Basic orchestration loop    | 71,500      | opus   | 161    | pending |
| 161   | E2E integration test        | 46,800      | sonnet | -      | pending |

**Phase 0 Total:** 290,600 tokens

### Phase 1: Context Management (Can run parallel with Phase 0 after 156)

| Issue | Title                       | Est. Tokens | Agent  | Blocks  | Status  |
| ----- | --------------------------- | ----------- | ------ | ------- | ------- |
| 143   | Validate 50% rule           | 40,300      | sonnet | Phase 2 | pending |
| 154   | Implement context estimator | 46,800      | sonnet | Phase 2 | pending |
| 155   | Build context monitor       | 49,400      | sonnet | Phase 2 | pending |

**Phase 1 Total:** 136,500 tokens

### Phase 2: Agent Assignment (Sequential Chain)

| Issue | Title                      | Est. Tokens | Agent  | Blocks  | Status  |
| ----- | -------------------------- | ----------- | ------ | ------- | ------- |
| 144   | Implement agent profiles   | 31,200      | haiku  | 145     | pending |
| 145   | Build assignment algorithm | 46,800      | sonnet | 146     | pending |
| 146   | Test assignment scenarios  | 40,300      | sonnet | Phase 3 | pending |

**Phase 2 Total:** 118,300 tokens

### Phase 3: Quality Layer (Sequential Chain)

| Issue | Title                      | Est. Tokens | Agent  | Blocks  | Status  |
| ----- | -------------------------- | ----------- | ------ | ------- | ------- |
| 147   | Implement core gates       | 62,400      | sonnet | 148     | pending |
| 148   | Build Quality Orchestrator | 64,350      | sonnet | 149     | pending |
| 149   | Test rejection loop        | 40,300      | sonnet | Phase 4 | pending |

**Phase 3 Total:** 167,050 tokens

### Phase 4: Advanced Orchestration (Sequential Chain)

| Issue | Title                      | Est. Tokens | Agent  | Blocks | Status  |
| ----- | -------------------------- | ----------- | ------ | ------ | ------- |
| 150   | Build orchestration loop   | 71,500      | opus   | 151    | pending |
| 151   | Implement compaction       | 46,800      | sonnet | 152    | pending |
| 152   | Implement session rotation | 46,800      | sonnet | 153    | pending |
| 153   | End-to-end test            | 58,500      | sonnet | -      | pending |

**Phase 4 Total:** 223,600 tokens

### EPIC Tracker

| Issue | Title                             | Est. Tokens | Agent  | Blocks     | Status  |
| ----- | --------------------------------- | ----------- | ------ | ---------- | ------- |
| 142   | [EPIC] Non-AI Coordinator Pattern | 0           | manual | All issues | pending |

**Note:** Issue 142 closes when all child issues (140, 143-161) are complete.

## Total Context Budget

**Total Estimated:** 936,050 tokens across 20 implementation/doc issues

- Documentation: TBD (verify issue 140)
- Phase 0: 290,600 tokens
- Phase 1: 136,500 tokens
- Phase 2: 118,300 tokens
- Phase 3: 167,050 tokens
- Phase 4: 223,600 tokens
- EPIC Tracker: 0 tokens (manual closure)

## Parallel Execution Opportunities

1. **Phase 0 + Phase 1:** Can run Phase 1 issues (154, 155) in parallel with Phase 0 after issue 156 completes
2. **Within Phase 1:** Issues 154 and 155 can run in parallel (2 agents)
3. All other phases are sequential due to dependencies

## Quality Gates (Mandatory)

Every code change must pass:

1. ✅ Build verification (type checking)
2. ✅ Linting (zero warnings)
3. ✅ Unit tests (100% pass rate)
4. ✅ Coverage (≥85%)
5. ✅ Independent code review
6. ✅ QA validation

**No bypasses permitted. Agent dishonesty will terminate execution.**

## Token Tracking

Each completed issue will record:

- Estimated tokens (from issue)
- Actual tokens used
- Variance percentage
- Agent type used
- Completion time

## Issue Closure Protocol

Upon completion:

1. Agent commits code
2. Code review performed
3. QA gates executed
4. All gates pass → Issue closed with summary comment
5. Any gate fails → Forced continuation, gates re-run
6. Update this tracking document with actuals

## Status Legend

- `pending` - Not yet started
- `in_progress` - Agent actively working
- `review` - Code review in progress
- `qa` - QA gates running
- `blocked` - Waiting on dependency
- `completed` - All gates passed, issue closed
- `failed` - Gates failed, requires remediation

## Execution Log

| Timestamp | Event | Issue | Agent | Notes |
| --------- | ----- | ----- | ----- | ----- |
| -         | -     | -     | -     | -     |

---

**Next Action:** Execute Phase 0, Issue 156 (Create coordinator bot user in Gitea)