stack/docs/claude/orchestrator.md

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):

# 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:

# 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:

# 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

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

## 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

## 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.