# Mosaic Stack Orchestrator Guide

> Platform-specific orchestrator protocol for Mosaic Stack.

## Overview

The orchestrator **cold-starts** with just a review report location and minimal kickstart. It autonomously:

1. Parses review reports to extract findings
2. Categorizes findings into phases by severity
3. Estimates token usage per task
4. Creates Gitea issues (phase-level)
5. Bootstraps `docs/tasks.md` from scratch
6. Coordinates completion using worker agents

**Key principle:** The orchestrator is the **sole writer** of `docs/tasks.md`. Worker agents execute tasks and report results — they never modify the tracking file.

---

## Bootstrap Templates

Use templates from `docs/templates/` (relative to repo root):

```bash
# Set environment variables
export PROJECT="mosaic-stack"
export MILESTONE="M6-Feature"
export CURRENT_DATETIME=$(date -Iseconds)
export TASK_PREFIX="MS-SEC"
export PHASE_ISSUE="#337"
export PHASE_BRANCH="fix/security"

# Create tasks.md (then populate with findings)
envsubst < docs/templates/orchestrator/tasks.md.template > docs/tasks.md

# Create learnings tracking
envsubst < docs/templates/orchestrator/orchestrator-learnings.json.template > docs/orchestrator-learnings.json

# Create review report structure (if doing new review)
./docs/templates/reports/review-report-scaffold.sh codebase-review mosaic-stack
```

**Available templates:**

| Template                                            | Purpose                         |
| --------------------------------------------------- | ------------------------------- |
| `orchestrator/tasks.md.template`                    | Task tracking table with schema |
| `orchestrator/orchestrator-learnings.json.template` | Variance tracking               |
| `orchestrator/phase-issue-body.md.template`         | Gitea issue body                |
| `orchestrator/compaction-summary.md.template`       | 60% checkpoint format           |
| `reports/review-report-scaffold.sh`                 | Creates report directory        |
| `scratchpad.md.template`                            | Per-task working document       |

See `docs/templates/README.md` for full documentation.

---

## Phase 1: Bootstrap

### Step 1: Parse Review Reports

Review reports follow this structure:

```
docs/reports/{report-name}/
├── 00-executive-summary.md   # Start here - overview and counts
├── 01-security-review.md     # Security findings with IDs like SEC-*
├── 02-code-quality-review.md # Code quality findings like CQ-*
├── 03-qa-test-coverage.md    # Test coverage gaps like TEST-*
└── ...
```

**Extract findings by looking for:**

- Finding IDs (e.g., `SEC-API-1`, `CQ-WEB-3`, `TEST-001`)
- Severity labels: Critical, High, Medium, Low
- Affected files/components (use for `repo` column)
- Specific line numbers or code patterns

### Step 2: Categorize into Phases

| Severity | Phase | Focus                                   | Branch Pattern      |
| -------- | ----- | --------------------------------------- | ------------------- |
| Critical | 1     | Security vulnerabilities, data exposure | `fix/security`      |
| High     | 2     | Security hardening, auth gaps           | `fix/security`      |
| Medium   | 3     | Code quality, performance, bugs         | `fix/code-quality`  |
| Low      | 4     | Tests, documentation, cleanup           | `fix/test-coverage` |

**Within each phase, order tasks by:**

1. Blockers first (tasks that unblock others)
2. Same-file tasks grouped together
3. Simpler fixes before complex ones

### Step 3: Estimate Token Usage

| Task Type             | Estimate | Examples                                  |
| --------------------- | -------- | ----------------------------------------- |
| Single-line fix       | 3-5K     | Typo, wrong operator, missing null check  |
| Add guard/validation  | 5-8K     | Add auth decorator, input validation      |
| Fix error handling    | 8-12K    | Proper try/catch, error propagation       |
| Refactor pattern      | 10-15K   | Replace KEYS with SCAN, fix memory leak   |
| Add new functionality | 15-25K   | New service method, new component         |
| Write tests           | 15-25K   | Unit tests for untested service           |
| Complex refactor      | 25-40K   | Architectural change, multi-file refactor |

**Adjust estimates based on:**

- Number of files affected (+5K per additional file)
- Test requirements (+5-10K if tests needed)
- Documentation needs (+2-3K if docs needed)

### Step 4: Determine Dependencies

**Automatic dependency rules:**

1. All tasks in Phase N depend on the Phase N-1 verification task
2. Tasks touching the same file should be sequential (earlier blocks later)
3. Auth/security foundation tasks block tasks that rely on them
4. Each phase ends with a verification task that depends on all phase tasks

### Step 5: Create Gitea Issues (Phase-Level)

Create ONE issue per phase:

```bash
# Use tea directly for Mosaic Stack (Gitea)
tea issue create \
  --title "Phase 1: Critical Security Fixes" \
  --description "## Findings
- SEC-API-1: Description
- SEC-WEB-2: Description

## Acceptance Criteria
- [ ] All critical findings remediated
- [ ] Quality gates passing" \
  --labels "security" \
  --milestone "{milestone-name}"
```

### Step 6: Create docs/tasks.md

Create the file with this exact schema:

```markdown
# Tasks

| id         | status      | description                  | issue | repo | branch       | depends_on | blocks     | agent | started_at | completed_at | estimate | used |
| ---------- | ----------- | ---------------------------- | ----- | ---- | ------------ | ---------- | ---------- | ----- | ---------- | ------------ | -------- | ---- |
| MS-SEC-001 | not-started | SEC-API-1: Brief description | #337  | api  | fix/security |            | MS-SEC-002 |       |            |              | 8K       |      |
```

**Column definitions:**

| Column         | Format                                               | Purpose                                     |
| -------------- | ---------------------------------------------------- | ------------------------------------------- |
| `id`           | `MS-{CAT}-{NNN}`                                     | Unique task ID                              |
| `status`       | `not-started` \| `in-progress` \| `done` \| `failed` | Current state                               |
| `description`  | `{FindingID}: Brief summary`                         | What to fix                                 |
| `issue`        | `#NNN`                                               | Gitea issue (phase-level)                   |
| `repo`         | Workspace name                                       | `api`, `web`, `orchestrator`, `coordinator` |
| `branch`       | Branch name                                          | `fix/security`, `fix/code-quality`, etc.    |
| `depends_on`   | Comma-separated IDs                                  | Must complete first                         |
| `blocks`       | Comma-separated IDs                                  | Tasks waiting on this                       |
| `agent`        | Agent identifier                                     | Assigned worker                             |
| `started_at`   | ISO 8601                                             | When work began                             |
| `completed_at` | ISO 8601                                             | When work finished                          |
| `estimate`     | `5K`, `15K`, etc.                                    | Predicted token usage                       |
| `used`         | `4.2K`, `12.8K`, etc.                                | Actual usage                                |

### Step 7: Commit Bootstrap

```bash
git add docs/tasks.md docs/orchestrator-learnings.json
git commit -m "chore(orchestrator): Bootstrap tasks.md from review report

Parsed {N} findings into {M} tasks across {P} phases.
Estimated total: {X}K tokens."
git push
```

---

## Phase 2: Execution Loop

```
1. git pull --rebase
2. Read docs/tasks.md
3. Find next task: status=not-started AND all depends_on are done
4. If no task available:
   - All done? → Report success, run final retrospective, STOP
   - Some blocked? → Report deadlock, STOP
5. Update tasks.md: status=in-progress, agent={identifier}, started_at={now}
6. Spawn worker agent (Task tool) with task details
7. Wait for worker completion
8. Parse worker result (JSON)
9. Variance check: Calculate (actual - estimate) / estimate × 100
   - If |variance| > 50%: Capture learning
   - If |variance| > 100%: Flag as CRITICAL
10. Update tasks.md: status=done/failed, completed_at={now}, used={actual}
11. Cleanup reports: Remove processed report files
12. Commit + push: git add docs/tasks.md && git commit && git push
13. If phase verification task: Run phase retrospective
14. Check context usage
15. If >= 60%: Persist learnings, Compact, go to step 1
16. If < 60%: Go to step 1
```

---

## Worker Prompt Template

````markdown
## Task Assignment: {id}

**Description:** {description}
**Repository:** apps/{repo}
**Branch:** {branch}

**Reference:** See `docs/reports/` for detailed finding description. Search for the finding ID.

## Workflow

1. Checkout branch: `git checkout {branch} || git checkout -b {branch} develop && git pull`
2. Read the finding details from the report
3. Implement the fix following existing code patterns
4. Run quality gates (ALL must pass):
   ```bash
   pnpm lint && pnpm typecheck && pnpm test
   ```
5. If gates fail: Fix and retry. Do NOT report success with failures.
6. Commit: `git commit -m "fix({finding_id}): brief description"`
7. Push: `git push origin {branch}`
8. Report result as JSON (see format below)

## Result Format (MANDATORY)

```json
{
  "task_id": "{id}",
  "status": "success|failed",
  "used": "5.2K",
  "commit_sha": "abc123",
  "notes": "Brief summary of what was done"
}
```

## Rules

- DO NOT modify docs/tasks.md
- DO NOT claim other tasks
- Complete this single task, report results, done
````

---

## Compaction Protocol

**Threshold:** 60% context usage

**Why 60%?** System overhead is ~26%. Real capacity is ~74%. Triggering at 60% = ~81% actual usage — safe margin before the 91-95% emergency wall.

**Compaction steps:**

1. Update docs/tasks.md with all current progress
2. Commit + push tasks.md
3. Output summary (completed, quality status, remaining, next task)
4. Clear detailed worker outputs and execution history from context
5. Resume with next unblocked task

**Compaction does NOT require user permission.**

---

## Learning & Retrospective

### Variance Thresholds

| Variance | Action                                                 |
| -------- | ------------------------------------------------------ |
| 0-30%    | Log only (acceptable)                                  |
| 30-50%   | Flag for review                                        |
| 50-100%  | Capture learning to `docs/orchestrator-learnings.json` |
| >100%    | CRITICAL — review task classification                  |

### Task Type Classification

| Type         | Keywords                               | Base Estimate    |
| ------------ | -------------------------------------- | ---------------- |
| STYLE_FIX    | "formatting", "prettier", "lint"       | 3-5K             |
| BULK_CLEANUP | "unused", "warnings", "~N files"       | file_count × 550 |
| GUARD_ADD    | "add guard", "decorator", "validation" | 5-8K             |
| SECURITY_FIX | "sanitize", "injection", "XSS"         | 8-12K × 2.5      |
| AUTH_ADD     | "authentication", "auth"               | 15-25K           |
| REFACTOR     | "refactor", "replace", "migrate"       | 10-15K           |
| TEST_ADD     | "add tests", "coverage"                | 15-25K           |

---

## Report Cleanup

QA automation generates report files in `docs/reports/qa-automation/pending/`. Clean up after processing.

| Event              | Action                                  |
| ------------------ | --------------------------------------- |
| Task success       | Delete matching reports from `pending/` |
| Task failed        | Move reports to `escalated/`            |
| Phase verification | Clean up all `pending/` reports         |
| Milestone complete | Archive or delete `escalated/`          |

---

## Stopping Criteria

**ONLY stop if:**

1. All tasks in docs/tasks.md are `done`
2. Critical blocker preventing progress (document and alert)
3. Absolute context limit reached AND cannot compact further

**DO NOT stop to ask "should I continue?"** — the answer is always YES.

---

## Kickstart Message Format

```markdown
## Mission

Remediate findings from the codebase review.

## Setup

- Project: /home/localadmin/src/mosaic-stack
- Review: docs/reports/{report-name}/
- Quality gates: pnpm lint && pnpm typecheck && pnpm test
- Milestone: {milestone-name}
- Task prefix: MS

## Protocol

Read docs/claude/orchestrator.md for full instructions.

## Start

Bootstrap from the review report, then execute until complete.
```

---

## Quick Reference

| Phase     | Action                                                                  |
| --------- | ----------------------------------------------------------------------- |
| Bootstrap | Parse reports → Categorize → Estimate → Create issues → Create tasks.md |
| Execute   | Loop: claim → spawn worker → update → commit                            |
| Compact   | At 60%: summarize, clear history, continue                              |
| Stop      | Queue empty, blocker, or context limit                                  |

**Orchestrator owns tasks.md. Workers execute and report. Single writer eliminates conflicts.**