centralize guides and rails under mosaic with runtime compatibility links
This commit is contained in:
Jason Woltje
866
guides/orchestrator.md
Normal file
866
guides/orchestrator.md
Normal file
@@ -0,0 +1,866 @@
|
||||
# Autonomous Orchestrator Guide
|
||||
|
||||
> Load this guide when orchestrating autonomous task completion across any project.
|
||||
|
||||
## Overview
|
||||
|
||||
The orchestrator **cold-starts** on any project 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.
|
||||
|
||||
---
|
||||
|
||||
## Orchestrator Boundaries (CRITICAL)
|
||||
|
||||
**The orchestrator NEVER:**
|
||||
- Edits source code directly (*.ts, *.tsx, *.js, *.py, etc.)
|
||||
- Runs quality gates itself (that's the worker's job)
|
||||
- Makes commits containing code changes
|
||||
- "Quickly fixes" something to save time — this is how drift starts
|
||||
|
||||
**The orchestrator ONLY:**
|
||||
- Reads/writes `docs/tasks.md`
|
||||
- Reads/writes `docs/orchestrator-learnings.json`
|
||||
- Spawns workers via the Task tool for ALL code changes
|
||||
- Parses worker JSON results
|
||||
- Commits task tracking updates (tasks.md, learnings)
|
||||
- Outputs status reports and handoff messages
|
||||
|
||||
**If you find yourself about to edit source code, STOP.**
|
||||
Spawn a worker instead. No exceptions. No "quick fixes."
|
||||
|
||||
**Worker Limits:**
|
||||
- Maximum **2 parallel workers** at any time
|
||||
- Wait for at least one worker to complete before spawning more
|
||||
- This optimizes token usage and reduces context pressure
|
||||
|
||||
---
|
||||
|
||||
## Bootstrap Templates
|
||||
|
||||
Use templates from `jarvis-brain/docs/templates/` to scaffold tracking files:
|
||||
|
||||
```bash
|
||||
# Set environment variables
|
||||
export PROJECT="project-name"
|
||||
export MILESTONE="M1-Feature"
|
||||
export CURRENT_DATETIME=$(date -Iseconds)
|
||||
export TASK_PREFIX="PR-SEC"
|
||||
export PHASE_ISSUE="#1"
|
||||
export PHASE_BRANCH="fix/security"
|
||||
|
||||
# Copy templates
|
||||
TEMPLATES=~/src/jarvis-brain/docs/templates
|
||||
|
||||
# Create tasks.md (then populate with findings)
|
||||
envsubst < $TEMPLATES/orchestrator/tasks.md.template > docs/tasks.md
|
||||
|
||||
# Create learnings tracking
|
||||
envsubst < $TEMPLATES/orchestrator/orchestrator-learnings.json.template > docs/orchestrator-learnings.json
|
||||
|
||||
# Create review report structure (if doing new review)
|
||||
$TEMPLATES/reports/review-report-scaffold.sh codebase-review
|
||||
```
|
||||
|
||||
**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 `jarvis-brain/docs/templates/README.md` for full documentation.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Bootstrap
|
||||
|
||||
### Step 1: Parse Review Reports
|
||||
|
||||
Review reports typically 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
|
||||
|
||||
**Parse each finding into:**
|
||||
```
|
||||
{
|
||||
id: "SEC-API-1",
|
||||
severity: "critical",
|
||||
title: "Brief description",
|
||||
component: "api", // For repo column
|
||||
file: "path/to/file.ts", // Reference for worker
|
||||
lines: "45-67" // Specific location
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Categorize into Phases
|
||||
|
||||
Map severity to 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
|
||||
|
||||
Use these heuristics based on task type:
|
||||
|
||||
| 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
|
||||
|
||||
**Create verification tasks:**
|
||||
- `{PREFIX}-SEC-{LAST}`: Phase 1 verification (run security tests)
|
||||
- `{PREFIX}-HIGH-{LAST}`: Phase 2 verification
|
||||
- `{PREFIX}-CQ-{LAST}`: Phase 3 verification
|
||||
- `{PREFIX}-TEST-{LAST}`: Phase 4 verification (final quality gates)
|
||||
|
||||
### Step 5: Create Gitea Issues (Phase-Level)
|
||||
|
||||
Create ONE issue per phase using git scripts:
|
||||
|
||||
```bash
|
||||
~/.mosaic/rails/git/issue-create.sh \
|
||||
-t "Phase 1: Critical Security Fixes" \
|
||||
-b "$(cat <<'EOF'
|
||||
## Findings
|
||||
|
||||
- SEC-API-1: Description
|
||||
- SEC-WEB-2: Description
|
||||
- SEC-ORCH-1: Description
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] All critical findings remediated
|
||||
- [ ] Quality gates passing
|
||||
- [ ] No new regressions
|
||||
EOF
|
||||
)" \
|
||||
-l "security,critical" \
|
||||
-m "{milestone-name}"
|
||||
```
|
||||
|
||||
**Capture issue numbers** — you'll link tasks to these.
|
||||
|
||||
### 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 |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| {PREFIX}-SEC-001 | not-started | SEC-API-1: Brief description | #{N} | api | fix/security | | {PREFIX}-SEC-002 | | | | 8K | |
|
||||
```
|
||||
|
||||
**Column definitions:**
|
||||
|
||||
| Column | Format | Purpose |
|
||||
|--------|--------|---------|
|
||||
| `id` | `{PREFIX}-{CAT}-{NNN}` | Unique task ID (e.g., MS-SEC-001) |
|
||||
| `status` | `not-started` \| `in-progress` \| `done` \| `failed` | Current state |
|
||||
| `description` | `{FindingID}: Brief summary` | What to fix |
|
||||
| `issue` | `#NNN` | Gitea issue (phase-level, all tasks in phase share) |
|
||||
| `repo` | Workspace name | `api`, `web`, `orchestrator`, etc. |
|
||||
| `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 (fill when claiming) |
|
||||
| `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 (fill on completion) |
|
||||
|
||||
**Category prefixes:**
|
||||
- `SEC` — Security (Phase 1-2)
|
||||
- `HIGH` — High priority (Phase 2)
|
||||
- `CQ` — Code quality (Phase 3)
|
||||
- `TEST` — Test coverage (Phase 4)
|
||||
- `PERF` — Performance (Phase 3)
|
||||
|
||||
### Step 7: Commit Bootstrap
|
||||
|
||||
```bash
|
||||
git add docs/tasks.md
|
||||
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 (see Learning & Retrospective)
|
||||
- If |variance| > 100%: Flag as CRITICAL — review task classification
|
||||
10. **Post-Coding Review** (see Phase 2b below)
|
||||
11. Update tasks.md: status=done/failed/needs-qa, completed_at={now}, used={actual}
|
||||
12. **Cleanup reports**: Remove processed report files for completed task
|
||||
```bash
|
||||
# Find and remove reports matching the finding ID
|
||||
find docs/reports/qa-automation/pending/ -name "*{finding_id}*" -delete 2>/dev/null || true
|
||||
# If task failed, move reports to escalated/ instead
|
||||
```
|
||||
13. Commit + push: git add docs/tasks.md .gitignore && git commit && git push
|
||||
14. If phase verification task: Run phase retrospective, clean up all phase reports
|
||||
15. Check context usage
|
||||
16. If >= 55%: Output COMPACTION REQUIRED checkpoint, STOP, wait for user
|
||||
17. If < 55%: Go to step 1
|
||||
18. After user runs /compact and says "continue": Go to step 1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2b: Post-Coding Review (MANDATORY)
|
||||
|
||||
**CRITICAL:** After any worker completes a task that modifies source code, the orchestrator MUST run an independent review before marking the task as done. This catches bugs, security issues, and regressions that the worker missed.
|
||||
|
||||
### When to Review
|
||||
|
||||
Run review when the worker's result includes code changes (commits). Skip for tasks that only modify docs, config, or tracking files.
|
||||
|
||||
### Step 1: Run Codex Review (Primary)
|
||||
|
||||
```bash
|
||||
# Navigate to the project directory
|
||||
cd {project_path}
|
||||
|
||||
# Code quality review
|
||||
~/.mosaic/rails/codex/codex-code-review.sh -b {base_branch} -o /tmp/review-{task_id}.json
|
||||
|
||||
# Security review
|
||||
~/.mosaic/rails/codex/codex-security-review.sh -b {base_branch} -o /tmp/security-{task_id}.json
|
||||
```
|
||||
|
||||
### Step 2: Parse Review Results
|
||||
|
||||
```bash
|
||||
# Check code review
|
||||
CODE_BLOCKERS=$(jq '.stats.blockers // 0' /tmp/review-{task_id}.json)
|
||||
CODE_VERDICT=$(jq -r '.verdict // "comment"' /tmp/review-{task_id}.json)
|
||||
|
||||
# Check security review
|
||||
SEC_CRITICAL=$(jq '.stats.critical // 0' /tmp/security-{task_id}.json)
|
||||
SEC_HIGH=$(jq '.stats.high // 0' /tmp/security-{task_id}.json)
|
||||
```
|
||||
|
||||
### Step 3: Decision Tree
|
||||
|
||||
```
|
||||
IF Codex is unavailable (command not found, auth failure, API error):
|
||||
→ Use fallback review (Step 4)
|
||||
|
||||
IF CODE_BLOCKERS > 0 OR SEC_CRITICAL > 0 OR SEC_HIGH > 0:
|
||||
→ Mark task as "needs-qa" in tasks.md
|
||||
→ Create a remediation task:
|
||||
- ID: {task_id}-QA
|
||||
- Description: Fix findings from review (list specific issues)
|
||||
- depends_on: (none — it's a follow-up, not a blocker)
|
||||
- Notes: Include finding titles and file locations
|
||||
→ Continue to next task (remediation task will be picked up in order)
|
||||
|
||||
IF CODE_VERDICT == "request-changes" (but no blockers):
|
||||
→ Log should-fix findings in task notes
|
||||
→ Mark task as done (non-blocking suggestions)
|
||||
→ Consider creating a tech-debt issue for significant suggestions
|
||||
|
||||
IF CODE_VERDICT == "approve" AND SEC_CRITICAL == 0 AND SEC_HIGH == 0:
|
||||
→ Mark task as done
|
||||
→ Log: "Review passed — no issues found"
|
||||
```
|
||||
|
||||
### Step 4: Fallback Review (When Codex is Unavailable)
|
||||
|
||||
If the `codex` CLI is not installed or authentication fails, use Claude's built-in review capabilities:
|
||||
|
||||
```markdown
|
||||
## Fallback: Spawn a Review Agent
|
||||
|
||||
Use the Task tool to spawn a review subagent:
|
||||
|
||||
Prompt:
|
||||
---
|
||||
## Independent Code Review
|
||||
|
||||
Review the code changes on branch {branch} against {base_branch}.
|
||||
|
||||
1. Run: `git diff {base_branch}...HEAD`
|
||||
2. Review for:
|
||||
- Correctness (bugs, logic errors, edge cases)
|
||||
- Security (OWASP Top 10, secrets, injection)
|
||||
- Testing (coverage, quality)
|
||||
- Code quality (complexity, duplication)
|
||||
3. Reference: ~/.mosaic/guides/code-review.md
|
||||
|
||||
Report findings as JSON:
|
||||
```json
|
||||
{
|
||||
"verdict": "approve|request-changes",
|
||||
"blockers": 0,
|
||||
"critical_security": 0,
|
||||
"findings": [
|
||||
{"severity": "blocker|should-fix|suggestion", "title": "...", "file": "...", "description": "..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
---
|
||||
```
|
||||
|
||||
### Review Timing Guidelines
|
||||
|
||||
| Task Type | Review Required? |
|
||||
|-----------|-----------------|
|
||||
| Source code changes (*.ts, *.py, etc.) | **YES — always** |
|
||||
| Configuration changes (*.yml, *.toml) | YES — security review only |
|
||||
| Documentation changes (*.md) | No |
|
||||
| Task tracking updates (tasks.md) | No |
|
||||
| Test-only changes | YES — code review only |
|
||||
|
||||
### Logging Review Results
|
||||
|
||||
In the task notes column of tasks.md, append review results:
|
||||
|
||||
```
|
||||
Review: approve (0 blockers, 0 critical) | Codex 0.98.0
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```
|
||||
Review: needs-qa (1 blocker, 2 high) → QA task {task_id}-QA created
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Worker Prompt Template
|
||||
|
||||
Construct this from the task row and pass to worker via Task tool:
|
||||
|
||||
````markdown
|
||||
## Task Assignment: {id}
|
||||
|
||||
**Description:** {description}
|
||||
**Repository:** {project_path}/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 — zero lint errors, zero type errors, all tests green):
|
||||
```bash
|
||||
{quality_gates_command}
|
||||
```
|
||||
**MANDATORY:** This ALWAYS includes linting. If the project has a linter configured
|
||||
(ESLint, Biome, ruff, etc.), you MUST run it and fix ALL violations in files you touched.
|
||||
Do NOT leave lint warnings or errors for someone else to clean up.
|
||||
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)
|
||||
|
||||
## Git Scripts
|
||||
|
||||
For issue/PR/milestone operations, use scripts (NOT raw tea/gh):
|
||||
- `~/.mosaic/rails/git/issue-view.sh -i {N}`
|
||||
- `~/.mosaic/rails/git/pr-create.sh -t "Title" -b "Desc" -B develop`
|
||||
|
||||
Standard git commands (pull, commit, push, checkout) are fine.
|
||||
|
||||
## Result Format (MANDATORY)
|
||||
|
||||
End your response with this JSON block:
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "{id}",
|
||||
"status": "success|failed",
|
||||
"used": "5.2K",
|
||||
"commit_sha": "abc123",
|
||||
"notes": "Brief summary of what was done"
|
||||
}
|
||||
```
|
||||
|
||||
## Post-Coding Review
|
||||
|
||||
After you complete and push your changes, the orchestrator will independently
|
||||
review your code using Codex (or a fallback review agent). If the review finds
|
||||
blockers or critical security issues, a follow-up remediation task will be
|
||||
created. You do NOT need to run the review yourself — the orchestrator handles it.
|
||||
|
||||
## Rules
|
||||
|
||||
- DO NOT modify docs/tasks.md
|
||||
- DO NOT claim other tasks
|
||||
- Complete this single task, report results, done
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
## Context Threshold Protocol (Orchestrator Replacement)
|
||||
|
||||
**Threshold:** 55-60% context usage
|
||||
|
||||
**Why replacement, not compaction?**
|
||||
- Compaction causes **protocol drift** — agent "remembers" gist but loses specifics
|
||||
- Post-compaction agents may violate core rules (e.g., letting workers modify tasks.md)
|
||||
- Fresh orchestrator has **100% protocol fidelity**
|
||||
- All state lives in `docs/tasks.md` — the orchestrator is **stateless and replaceable**
|
||||
|
||||
**At threshold (55-60%):**
|
||||
|
||||
1. Complete current task
|
||||
2. Persist all state:
|
||||
- Update docs/tasks.md with all progress
|
||||
- Update docs/orchestrator-learnings.json with variances
|
||||
- Commit and push both files
|
||||
3. Output **ORCHESTRATOR HANDOFF** message with ready-to-use takeover kickstart
|
||||
4. **STOP COMPLETELY** — do not continue working
|
||||
|
||||
**Handoff message format:**
|
||||
|
||||
```
|
||||
---
|
||||
⚠️ ORCHESTRATOR HANDOFF REQUIRED
|
||||
|
||||
Context: {X}% — Replacement recommended to prevent drift
|
||||
|
||||
Progress: {completed}/{total} tasks ({percentage}%)
|
||||
Current phase: Phase {N} ({phase_name})
|
||||
|
||||
State persisted:
|
||||
- docs/tasks.md ✓
|
||||
- docs/orchestrator-learnings.json ✓
|
||||
|
||||
## Takeover Kickstart
|
||||
|
||||
Copy and paste this to spawn a fresh orchestrator:
|
||||
|
||||
---
|
||||
## Continuation Mission
|
||||
|
||||
Continue {mission_description} from existing state.
|
||||
|
||||
## Setup
|
||||
- Project: {project_path}
|
||||
- State: docs/tasks.md (already populated)
|
||||
- Protocol: docs/claude/orchestrator.md
|
||||
- Quality gates: {quality_gates_command}
|
||||
|
||||
## Resume Point
|
||||
- Next task: {task_id}
|
||||
- Phase: {current_phase}
|
||||
- Progress: {completed}/{total} tasks ({percentage}%)
|
||||
|
||||
## Instructions
|
||||
1. Read docs/claude/orchestrator.md for protocol
|
||||
2. Read docs/tasks.md to understand current state
|
||||
3. Continue execution from task {task_id}
|
||||
4. Follow Two-Phase Completion Protocol
|
||||
5. You are the SOLE writer of docs/tasks.md
|
||||
---
|
||||
|
||||
STOP: Terminate this session and spawn fresh orchestrator with the kickstart above.
|
||||
---
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Do NOT attempt to compact yourself — compaction causes drift
|
||||
- Do NOT continue past 60%
|
||||
- Do NOT claim you can "just continue" — protocol drift is real
|
||||
- STOP means STOP — the user (Coordinator) will spawn your replacement
|
||||
- Include ALL context needed for the replacement in the takeover kickstart
|
||||
|
||||
---
|
||||
|
||||
## Two-Phase Completion Protocol
|
||||
|
||||
Each major phase uses a two-phase approach to maximize completion while managing diminishing returns.
|
||||
|
||||
### Bulk Phase (Target: 90%)
|
||||
|
||||
- Focus on tractable errors
|
||||
- Parallelize where possible
|
||||
- When 90% reached, transition to Polish (do NOT declare success)
|
||||
|
||||
### Polish Phase (Target: 100%)
|
||||
|
||||
1. **Inventory:** List all remaining errors with file:line
|
||||
2. **Categorize:**
|
||||
| Category | Criteria | Action |
|
||||
|----------|----------|--------|
|
||||
| Quick-win | <5 min, straightforward | Fix immediately |
|
||||
| Medium | 5-30 min, clear path | Fix in order |
|
||||
| Hard | >30 min or uncertain | Attempt 15 min, then document |
|
||||
| Architectural | Requires design change | Document and defer |
|
||||
|
||||
3. **Work priority:** Quick-win → Medium → Hard
|
||||
4. **Document deferrals** in `docs/deferred-errors.md`:
|
||||
```markdown
|
||||
## {PREFIX}-XXX: [Error description]
|
||||
- File: path/to/file.ts:123
|
||||
- Error: [exact error message]
|
||||
- Category: Hard | Architectural | Framework Limitation
|
||||
- Reason: [why this is non-trivial]
|
||||
- Suggested approach: [how to fix in future]
|
||||
- Risk: Low | Medium | High
|
||||
```
|
||||
|
||||
5. **Phase complete when:**
|
||||
- All Quick-win/Medium fixed
|
||||
- All Hard attempted (fixed or documented)
|
||||
- Architectural items documented with justification
|
||||
|
||||
### Phase Boundary Rule
|
||||
|
||||
Do NOT proceed to the next major phase until the current phase reaches Polish completion:
|
||||
|
||||
```
|
||||
✅ Phase 2 Bulk: 91%
|
||||
✅ Phase 2 Polish: 118 errors triaged
|
||||
- 40 medium → fixed
|
||||
- 78 low → EACH documented with rationale
|
||||
✅ Phase 2 Complete: Created docs/deferred-errors.md
|
||||
→ NOW proceed to Phase 3
|
||||
|
||||
❌ WRONG: Phase 2 at 91%, "low priority acceptable", starting Phase 3
|
||||
```
|
||||
|
||||
### Reporting
|
||||
|
||||
When transitioning from Bulk to Polish:
|
||||
```
|
||||
Phase X Bulk Complete: {N}% ({fixed}/{total})
|
||||
Entering Polish Phase: {remaining} errors to triage
|
||||
```
|
||||
|
||||
When Polish Phase complete:
|
||||
```
|
||||
Phase X Complete: {final_pct}% ({fixed}/{total})
|
||||
- Quick-wins: {n} fixed
|
||||
- Medium: {n} fixed
|
||||
- Hard: {n} fixed, {n} documented
|
||||
- Framework limitations: {n} documented
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Learning & Retrospective
|
||||
|
||||
Orchestrators capture learnings to improve future estimation accuracy.
|
||||
|
||||
### 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, possible mismatch |
|
||||
|
||||
### Task Type Classification
|
||||
|
||||
Classify tasks by description keywords for pattern analysis:
|
||||
|
||||
| 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 |
|
||||
|
||||
### Capture Learning
|
||||
|
||||
When |variance| > 50%, append to `docs/orchestrator-learnings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "UC-CLEAN-003",
|
||||
"task_type": "BULK_CLEANUP",
|
||||
"estimate_k": 30,
|
||||
"actual_k": 112.8,
|
||||
"variance_pct": 276,
|
||||
"characteristics": {
|
||||
"file_count": 200,
|
||||
"keywords": ["object injection", "type guards"]
|
||||
},
|
||||
"analysis": "Multi-file type guards severely underestimated",
|
||||
"captured_at": "2026-02-05T19:45:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Retrospective Triggers
|
||||
|
||||
| Trigger | Action |
|
||||
|---------|--------|
|
||||
| Phase verification task | Analyze phase variance, summarize patterns |
|
||||
| 60% compaction | Persist learnings buffer, include in summary |
|
||||
| Milestone complete | Full retrospective, generate heuristic proposals |
|
||||
|
||||
### Enhanced Compaction Summary
|
||||
|
||||
Include learnings in compaction output:
|
||||
|
||||
```
|
||||
Session Summary (Compacting at 60%):
|
||||
|
||||
Completed: MS-SEC-001 (15K→0.3K, -98%), MS-SEC-002 (8K→12K, +50%)
|
||||
Quality: All gates passing
|
||||
|
||||
Learnings Captured:
|
||||
- MS-SEC-001: -98% variance — AUTH_ADD may need SKIP_IF_EXISTS category
|
||||
- MS-SEC-002: +50% variance — XSS sanitization more complex than expected
|
||||
|
||||
Remaining: MS-SEC-004 (ready), MS-SEC-005 through MS-SEC-010
|
||||
Next: MS-SEC-004
|
||||
```
|
||||
|
||||
### Cross-Project Learnings
|
||||
|
||||
Universal heuristics are maintained in `~/.mosaic/guides/orchestrator-learnings.md`.
|
||||
After completing a milestone, review variance patterns and propose updates to the universal guide.
|
||||
|
||||
---
|
||||
|
||||
## Report Cleanup
|
||||
|
||||
QA automation generates report files in `docs/reports/qa-automation/pending/`. These must be cleaned up to prevent accumulation.
|
||||
|
||||
**Directory structure:**
|
||||
```
|
||||
docs/reports/qa-automation/
|
||||
├── pending/ # Reports awaiting processing
|
||||
└── escalated/ # Reports for failed tasks (manual review needed)
|
||||
```
|
||||
|
||||
**Gitignore:** Add this to project `.gitignore`:
|
||||
```
|
||||
# Orchestrator reports (generated by QA automation, cleaned up after processing)
|
||||
docs/reports/qa-automation/
|
||||
```
|
||||
|
||||
**Cleanup timing:**
|
||||
| Event | Action |
|
||||
|-------|--------|
|
||||
| Task success | Delete matching reports from `pending/` |
|
||||
| Task failed | Move reports to `escalated/` for investigation |
|
||||
| Phase verification | Clean up all `pending/` reports for that phase |
|
||||
| Milestone complete | Archive or delete entire `escalated/` directory |
|
||||
|
||||
**Cleanup commands:**
|
||||
```bash
|
||||
# After successful task (finding ID pattern, e.g., SEC-API-1)
|
||||
find docs/reports/qa-automation/pending/ -name "*relevant-file-pattern*" -delete
|
||||
|
||||
# After phase verification - clean all pending
|
||||
rm -rf docs/reports/qa-automation/pending/*
|
||||
|
||||
# Move failed task reports to escalated
|
||||
mv docs/reports/qa-automation/pending/*failing-file* docs/reports/qa-automation/escalated/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Quality gates fail:**
|
||||
1. Worker should retry up to 2 times
|
||||
2. If still failing, worker reports `failed` with error details
|
||||
3. Orchestrator updates tasks.md: keep `in-progress`, add notes
|
||||
4. Orchestrator may re-spawn with error context, or mark `failed` and continue
|
||||
5. If failed task blocks others: Report deadlock, STOP
|
||||
|
||||
**Worker reports blocker:**
|
||||
1. Update tasks.md with blocker notes
|
||||
2. Skip to next unblocked task if possible
|
||||
3. If all remaining tasks blocked: Report blockers, STOP
|
||||
|
||||
**Git push conflict:**
|
||||
1. `git pull --rebase`
|
||||
2. If auto-resolves: push again
|
||||
3. If conflict on tasks.md: Report, STOP (human resolves)
|
||||
|
||||
---
|
||||
|
||||
## Stopping Criteria
|
||||
|
||||
**ONLY stop if:**
|
||||
1. All tasks in docs/tasks.md are `done`
|
||||
2. Critical blocker preventing progress (document and alert)
|
||||
3. Context usage >= 55% — output COMPACTION REQUIRED checkpoint and wait
|
||||
4. Absolute context limit reached AND cannot compact further
|
||||
|
||||
**DO NOT stop to ask "should I continue?"** — the answer is always YES.
|
||||
**DO stop at 55-60%** — output the compaction checkpoint and wait for user to run `/compact`.
|
||||
|
||||
---
|
||||
|
||||
## Sprint Completion Protocol
|
||||
|
||||
When all tasks in `docs/tasks.md` are `done` (or triaged as `deferred`), archive the sprint artifacts before stopping. This preserves them for post-mortems, variance calibration, and historical reference.
|
||||
|
||||
### Archive Steps
|
||||
|
||||
1. **Create archive directory** (if it doesn't exist):
|
||||
```bash
|
||||
mkdir -p docs/tasks/
|
||||
```
|
||||
|
||||
2. **Move tasks.md to archive:**
|
||||
```bash
|
||||
mv docs/tasks.md docs/tasks/{milestone-name}-tasks.md
|
||||
```
|
||||
Example: `docs/tasks/M6-AgentOrchestration-Fixes-tasks.md`
|
||||
|
||||
3. **Move learnings to archive:**
|
||||
```bash
|
||||
mv docs/orchestrator-learnings.json docs/tasks/{milestone-name}-learnings.json
|
||||
```
|
||||
|
||||
4. **Commit the archive:**
|
||||
```bash
|
||||
git add docs/tasks/
|
||||
git rm docs/tasks.md docs/orchestrator-learnings.json 2>/dev/null || true
|
||||
git commit -m "chore(orchestrator): Archive {milestone-name} sprint artifacts
|
||||
|
||||
{completed}/{total} tasks completed, {deferred} deferred.
|
||||
Archived to docs/tasks/ for post-mortem reference."
|
||||
git push
|
||||
```
|
||||
|
||||
5. **Run final retrospective** — review variance patterns and propose updates to estimation heuristics.
|
||||
|
||||
### Recovery
|
||||
|
||||
If an orchestrator starts and `docs/tasks.md` does not exist, check `docs/tasks/` for the most recent archive:
|
||||
|
||||
```bash
|
||||
ls -t docs/tasks/*-tasks.md 2>/dev/null | head -1
|
||||
```
|
||||
|
||||
If found, this may indicate another session archived the file. The orchestrator should:
|
||||
1. Report what it found in `docs/tasks/`
|
||||
2. Ask whether to resume from the archived file or bootstrap fresh
|
||||
3. If resuming: copy the archive back to `docs/tasks.md` and continue
|
||||
|
||||
### Retention Policy
|
||||
|
||||
Keep all archived sprints indefinitely. They are small text files and valuable for:
|
||||
- Post-mortem analysis
|
||||
- Estimation variance calibration across milestones
|
||||
- Understanding what was deferred and why
|
||||
- Onboarding new orchestrators to project history
|
||||
|
||||
---
|
||||
|
||||
## Kickstart Message Format
|
||||
|
||||
The kickstart should be **minimal** — the orchestrator figures out the rest:
|
||||
|
||||
```markdown
|
||||
## Mission
|
||||
Remediate findings from the codebase review.
|
||||
|
||||
## Setup
|
||||
- Project: /path/to/project
|
||||
- Review: docs/reports/{report-name}/
|
||||
- Quality gates: {command}
|
||||
- Milestone: {milestone-name} (for issue creation)
|
||||
- Task prefix: {PREFIX} (e.g., MS, UC)
|
||||
|
||||
## Protocol
|
||||
Read ~/.mosaic/guides/orchestrator.md for full instructions.
|
||||
|
||||
## Start
|
||||
Bootstrap from the review report, then execute until complete.
|
||||
```
|
||||
|
||||
**The orchestrator will:**
|
||||
1. Read this guide
|
||||
2. Parse the review reports
|
||||
3. Determine phases, estimates, dependencies
|
||||
4. Create issues and tasks.md
|
||||
5. Execute until done or blocked
|
||||
|
||||
---
|
||||
|
||||
## 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.**
|
||||
Reference in New Issue
Block a user