stack/docs/claude/task-tracking.md

Autonomous Task Orchestration

Load this guide when orchestrating autonomous task completion via docs/tasks.md.

Ownership

The orchestrator is the sole writer of docs/tasks.md. Worker agents execute tasks and report results — they never read or modify the tracking file.

Schema Reference

Column	Format	Purpose
id	MS-{CAT}-{NNN}	Unique task ID
status	not-started | in-progress | done	Current state
description	Free text	What to do (inline, concise)
issue	#NNN or empty	Gitea issue for requirements context
repo	Workspace name	api, web, orchestrator, coordinator
branch	Branch name	Git branch for this work
depends_on	Comma-separated IDs	Must complete before this task starts
blocks	Comma-separated IDs	Tasks waiting on this one
agent	Agent identifier	Who is executing
started_at	ISO 8601	When work began
completed_at	ISO 8601	When work finished
estimate	5K, 40K	Predicted token usage
used	4.2K, 38.5K	Actual token usage (fill on completion)

Category prefixes: SEC (security), HIGH (high priority), CQ (code quality), TEST (test coverage)

Orchestrator Core 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, STOP
   - Some blocked? → Report deadlock, STOP
5. Update tasks.md: status=in-progress, agent, started_at
6. Spawn worker agent (Task tool) with task details from the row
7. Wait for worker completion
8. Parse worker result (JSON)
9. Update tasks.md: status=done/failed, completed_at, used
10. Commit + push: git add docs/tasks.md && git commit && git push
11. Check context usage
12. If >= 60%: Compact (see below), then go to step 1
13. If < 60%: Go to step 1

Worker Prompt Template

The orchestrator constructs this prompt from the task row and passes it to a worker agent via the Task tool:

## Task Assignment: {id}

**Description:** {description}
**Repository:** /home/localadmin/src/mosaic-stack/apps/{repo}
**Branch:** {branch}

**Reference Report:** See `docs/reports/codebase-review-2026-02-05/` for detailed findings.

## Workflow

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

## Git Scripts (for issue/PR/milestone operations, NOT raw tea/gh)

~/.claude/scripts/git/issue-view.sh -i {N}
~/.claude/scripts/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"
}
```

## 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% (prompts, tools, CLAUDE.md). Real capacity is ~74%. Triggering at 60% means ~81% actual usage — safe margin before the 91-95% emergency wall.

After completing each task:

1. Check context usage
2. If < 60%: Continue to next task
3. If >= 60%: Compact before next task

Compaction steps:

1. Update docs/tasks.md with all current progress
2. Commit + push tasks.md
3. Summarize: completed tasks, quality status, remaining queue
4. Clear detailed worker outputs and execution history
5. Resume with next unblocked task

Compaction does NOT require user permission.

Template:

Session Summary (Compacting at 60%):

Completed: MS-SEC-001 (12K), MS-SEC-002 (8K), MS-SEC-003 (10K)
Quality: All tests passing, zero regressions
Remaining: MS-SEC-004 (ready), MS-SEC-005 through MS-SEC-010, Phase 2-4 tasks
Next: MS-SEC-004

Expected: Context drops from 60% → ~25-30%.

Error Handling

Quality gates fail:

1. Update tasks.md: status remains in-progress, add failure notes
2. Re-spawn worker with error context, or mark failed and move on
3. If failed task blocks others: Report deadlock, STOP

Worker reports blocker:

1. Update tasks.md: note the blocker
2. Skip to next unblocked task if possible
3. If all remaining tasks blocked: Report, 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. Absolute context limit reached AND cannot compact further

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

Phase Structure

Phase 1 - Critical Security (MS-SEC-001 through MS-SEC-010):

• Authentication, XSS, error handling, OIDC validation
• Must complete before Phase 2

Phase 2 - High Security (MS-HIGH-001 through MS-HIGH-006):

• CSRF, mock data removal, rate limiting, container hardening
• Must complete before Phase 3

Phase 3 - Code Quality (MS-CQ-001 through MS-CQ-007):

• Memory leaks, stale closures, boolean bugs, atomic operations
• Must complete before Phase 4

Phase 4 - Test Coverage (MS-TEST-001 through MS-TEST-005):

• Critical service tests, widget tests, coverage investigation
• Final verification gate