feat: Add self-contained orchestration templates and guide
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
Makes Mosaic Stack self-contained for orchestration - no external dependencies. New files: - docs/claude/orchestrator.md - Platform-specific orchestrator protocol - docs/templates/ - Bootstrap templates for tasks.md, learnings, reports Templates: - orchestrator/tasks.md.template - Task tracking scaffold - orchestrator/orchestrator-learnings.json.template - Variance tracking - orchestrator/orchestrator-learnings.schema.md - JSON schema docs - 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 Updated CLAUDE.md: - References local docs/claude/orchestrator.md instead of ~/.claude/ - Added Platform Templates section pointing to docs/templates/ This enables deployment without requiring user-level ~/.claude/ configuration. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
360
docs/claude/orchestrator.md
Normal file
360
docs/claude/orchestrator.md
Normal file
@@ -0,0 +1,360 @@
|
||||
# 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.**
|
||||
76
docs/templates/README.md
vendored
Normal file
76
docs/templates/README.md
vendored
Normal file
@@ -0,0 +1,76 @@
|
||||
# Mosaic Stack Orchestration Templates
|
||||
|
||||
Templates for consistent orchestration setup within Mosaic Stack.
|
||||
|
||||
## Usage
|
||||
|
||||
### Variable Substitution
|
||||
|
||||
Templates use `${VARIABLE}` syntax. Substitute using `envsubst`:
|
||||
|
||||
```bash
|
||||
# Set variables
|
||||
export PROJECT="mosaic-stack"
|
||||
export MILESTONE="M6-Security"
|
||||
export CURRENT_DATETIME=$(date -Iseconds)
|
||||
|
||||
# Generate file from template (paths relative to repo root)
|
||||
envsubst < docs/templates/orchestrator/tasks.md.template > docs/tasks.md
|
||||
```
|
||||
|
||||
### Validation
|
||||
|
||||
Check for unsubstituted variables:
|
||||
|
||||
```bash
|
||||
grep -rE '\$\{[A-Z_]+\}' docs/tasks.md && echo "WARN: Unsubstituted variables" || echo "OK"
|
||||
```
|
||||
|
||||
## Standard Variables
|
||||
|
||||
| Variable | Description | Example |
|
||||
| --------------------- | -------------------- | ----------------------- |
|
||||
| `${PROJECT}` | Project identifier | `mosaic-stack` |
|
||||
| `${MILESTONE}` | Milestone identifier | `M6-AgentOrchestration` |
|
||||
| `${CURRENT_DATETIME}` | ISO datetime | `2026-02-05T20:00:00Z` |
|
||||
| `${PHASE_NUMBER}` | Phase number | `1` |
|
||||
| `${PHASE_ISSUE}` | Gitea issue number | `#337` |
|
||||
| `${PHASE_BRANCH}` | Feature branch | `fix/security` |
|
||||
| `${TASK_PREFIX}` | Task ID prefix | `MS-SEC` |
|
||||
|
||||
## Template Index
|
||||
|
||||
| Template | Purpose |
|
||||
| --------------------------------------------------- | ------------------------------- |
|
||||
| `orchestrator/tasks.md.template` | Task tracking table with schema |
|
||||
| `orchestrator/orchestrator-learnings.json.template` | Variance tracking |
|
||||
| `orchestrator/orchestrator-learnings.schema.md` | JSON schema documentation |
|
||||
| `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 |
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# From mosaic-stack root
|
||||
export PROJECT="mosaic-stack"
|
||||
export MILESTONE="M7-NewFeature"
|
||||
export CURRENT_DATETIME=$(date -Iseconds)
|
||||
export TASK_PREFIX="MS-001"
|
||||
export PHASE_ISSUE="#400"
|
||||
export PHASE_BRANCH="fix/feature"
|
||||
|
||||
# Create tracking files
|
||||
envsubst < docs/templates/orchestrator/tasks.md.template > docs/tasks.md
|
||||
envsubst < docs/templates/orchestrator/orchestrator-learnings.json.template > docs/orchestrator-learnings.json
|
||||
|
||||
# Create review report structure
|
||||
./docs/templates/reports/review-report-scaffold.sh codebase-review mosaic-stack
|
||||
```
|
||||
|
||||
## Platform Integration
|
||||
|
||||
These templates are part of Mosaic Stack's orchestration system. The orchestrator guide at `docs/claude/orchestrator.md` references these templates.
|
||||
|
||||
**Self-contained:** All orchestration tooling ships with the platform. No external dependencies on `~/.claude/` or other repositories.
|
||||
51
docs/templates/orchestrator/compaction-summary.md.template
vendored
Normal file
51
docs/templates/orchestrator/compaction-summary.md.template
vendored
Normal file
@@ -0,0 +1,51 @@
|
||||
## Compaction Summary
|
||||
|
||||
**Project:** ${PROJECT}
|
||||
**Milestone:** ${MILESTONE}
|
||||
**Time:** ${CURRENT_DATETIME}
|
||||
**Context at compaction:** ${CONTEXT_PERCENT}%
|
||||
|
||||
---
|
||||
|
||||
### Completed Tasks
|
||||
|
||||
| Task | Description | Tokens | Variance |
|
||||
|------|-------------|--------|----------|
|
||||
| ${TASK_1_ID} | ${TASK_1_DESC} | ${TASK_1_USED} | ${TASK_1_VARIANCE} |
|
||||
|
||||
**Phase progress:** ${COMPLETED_COUNT}/${TOTAL_COUNT} tasks
|
||||
|
||||
---
|
||||
|
||||
### Quality Status
|
||||
|
||||
- **Tests:** ${TEST_STATUS}
|
||||
- **Lint:** ${LINT_STATUS}
|
||||
- **Typecheck:** ${TYPECHECK_STATUS}
|
||||
- **Regressions:** ${REGRESSION_COUNT}
|
||||
|
||||
---
|
||||
|
||||
### Learnings Captured
|
||||
|
||||
<!-- Include if variance > 50% on any task -->
|
||||
- ${LEARNING_1}
|
||||
|
||||
---
|
||||
|
||||
### Remaining Tasks
|
||||
|
||||
| Task | Description | Status | Estimate |
|
||||
|------|-------------|--------|----------|
|
||||
| ${NEXT_TASK_ID} | ${NEXT_TASK_DESC} | ready | ${NEXT_TASK_EST} |
|
||||
|
||||
---
|
||||
|
||||
### Resuming With
|
||||
|
||||
**Next task:** ${NEXT_TASK_ID}
|
||||
**Reason:** First unblocked task in queue
|
||||
|
||||
---
|
||||
|
||||
*Context reduced from ${CONTEXT_BEFORE}% to ~25-30%*
|
||||
10
docs/templates/orchestrator/orchestrator-learnings.json.template
vendored
Normal file
10
docs/templates/orchestrator/orchestrator-learnings.json.template
vendored
Normal file
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"project": "${PROJECT}",
|
||||
"milestone": "${MILESTONE}",
|
||||
"created_at": "${CURRENT_DATETIME}",
|
||||
"learnings": [],
|
||||
"phase_summaries": [],
|
||||
"proposed_adjustments": [],
|
||||
"investigation_queue": []
|
||||
}
|
||||
113
docs/templates/orchestrator/orchestrator-learnings.schema.md
vendored
Normal file
113
docs/templates/orchestrator/orchestrator-learnings.schema.md
vendored
Normal file
@@ -0,0 +1,113 @@
|
||||
# Orchestrator Learnings JSON Schema
|
||||
|
||||
Reference documentation for `orchestrator-learnings.json` structure.
|
||||
|
||||
## Root Object
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"project": "string - Project identifier",
|
||||
"milestone": "string - Milestone identifier",
|
||||
"created_at": "ISO8601 - When file was created",
|
||||
"learnings": [],
|
||||
"phase_summaries": [],
|
||||
"proposed_adjustments": [],
|
||||
"investigation_queue": []
|
||||
}
|
||||
```
|
||||
|
||||
## Learning Entry
|
||||
|
||||
Captured when |variance| > 50%.
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "string - Matches task ID from tasks.md (e.g., MS-SEC-001)",
|
||||
"task_type": "enum - See Task Types below",
|
||||
"estimate_k": "number - Estimated tokens in thousands",
|
||||
"actual_k": "number - Actual tokens used in thousands",
|
||||
"variance_pct": "number - ((actual - estimate) / estimate) * 100",
|
||||
"characteristics": {
|
||||
"file_count": "number - Files modified",
|
||||
"keywords": ["array - Descriptive tags for pattern matching"]
|
||||
},
|
||||
"analysis": "string - Human/AI explanation of variance",
|
||||
"flags": ["array - CRITICAL | NEEDS_INVESTIGATION | ANOMALY"],
|
||||
"captured_at": "ISO8601 - When learning was recorded"
|
||||
}
|
||||
```
|
||||
|
||||
### Task Types
|
||||
|
||||
| Type | Description | Base Estimate |
|
||||
| ------------------------ | ------------------------------------------ | ---------------- |
|
||||
| `STYLE_FIX` | Formatting, prettier, lint fixes | 3-5K |
|
||||
| `BULK_CLEANUP` | Multi-file cleanup (unused vars, warnings) | file_count × 550 |
|
||||
| `GUARD_ADD` | Add guards, decorators, validation | 5-8K |
|
||||
| `AUTH_ADD` | Authentication implementation | 15-25K |
|
||||
| `ERROR_HANDLING` | Error handling improvements | 8-12K |
|
||||
| `CONFIG_DEFAULT_CHANGE` | Config default changes | 5-10K |
|
||||
| `CONFIG_EXTERNALIZATION` | Move hardcoded values to env vars | 8-12K |
|
||||
| `INPUT_VALIDATION` | Input sanitization, allowlists | 5-8K |
|
||||
| `BUG_FIX_SIMPLE` | Simple bug fixes (single file) | 3-8K |
|
||||
| `REFACTOR` | Code refactoring | 10-15K |
|
||||
| `COMPLEX_REFACTOR` | Multi-file architectural changes | 25-40K |
|
||||
| `TEST_ADD` | Adding test coverage | 15-25K |
|
||||
|
||||
## Phase Summary
|
||||
|
||||
Generated after phase verification task.
|
||||
|
||||
```json
|
||||
{
|
||||
"phase": "number - Phase number",
|
||||
"tasks_completed": "number",
|
||||
"tasks_total": "number",
|
||||
"estimate_total_k": "number - Sum of estimates",
|
||||
"actual_total_k": "number - Sum of actual usage",
|
||||
"variance_avg_pct": "number - Average variance",
|
||||
"pattern": "enum - SYSTEMATIC_UNDERESTIMATE | ACCURATE | OVERESTIMATE",
|
||||
"notes": "string - Summary observations"
|
||||
}
|
||||
```
|
||||
|
||||
## Proposed Adjustment
|
||||
|
||||
Heuristic improvement proposals.
|
||||
|
||||
```json
|
||||
{
|
||||
"category": "string - Task type category",
|
||||
"current_heuristic": "string - Current estimation formula",
|
||||
"proposed_heuristic": "string - Improved formula",
|
||||
"confidence": "enum - HIGH | MEDIUM | LOW",
|
||||
"evidence": ["array - Task IDs supporting this"],
|
||||
"variance_if_applied": "string - Expected improvement",
|
||||
"notes": "string - Additional context"
|
||||
}
|
||||
```
|
||||
|
||||
## Investigation Queue
|
||||
|
||||
Tasks requiring manual review.
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "string",
|
||||
"question": "string - What needs investigation",
|
||||
"priority": "enum - HIGH | MEDIUM | LOW",
|
||||
"status": "enum - OPEN | IN_PROGRESS | CLOSED",
|
||||
"resolution": "string - Outcome when closed",
|
||||
"verified_at": "ISO8601 - When investigation completed"
|
||||
}
|
||||
```
|
||||
|
||||
## Variance Thresholds
|
||||
|
||||
| Variance | Action |
|
||||
| -------- | ------------------------------------- |
|
||||
| 0-30% | Log only (acceptable) |
|
||||
| 30-50% | Flag for review |
|
||||
| 50-100% | Capture learning |
|
||||
| >100% | CRITICAL — review task classification |
|
||||
43
docs/templates/orchestrator/phase-issue-body.md.template
vendored
Normal file
43
docs/templates/orchestrator/phase-issue-body.md.template
vendored
Normal file
@@ -0,0 +1,43 @@
|
||||
## Phase ${PHASE_NUMBER}: ${PHASE_NAME}
|
||||
|
||||
**Milestone:** ${MILESTONE}
|
||||
**Branch:** `${PHASE_BRANCH}`
|
||||
**Estimate:** ${PHASE_ESTIMATE_K}K tokens
|
||||
|
||||
---
|
||||
|
||||
### Scope
|
||||
|
||||
${PHASE_SCOPE}
|
||||
|
||||
### Tasks
|
||||
|
||||
<!-- Generated from findings -->
|
||||
- [ ] Task 1
|
||||
- [ ] Task 2
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- [ ] All quality gates pass (lint, typecheck, tests)
|
||||
- [ ] No regressions from baseline
|
||||
- [ ] Code review approved
|
||||
- [ ] tasks.md updated with actual token usage
|
||||
|
||||
### Dependencies
|
||||
|
||||
**Blocked by:** ${BLOCKED_BY}
|
||||
**Blocks:** ${BLOCKS}
|
||||
|
||||
### Quality Gates
|
||||
|
||||
```bash
|
||||
# Run before marking tasks complete
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Tracking:** docs/tasks.md
|
||||
**Learnings:** docs/orchestrator-learnings.json
|
||||
62
docs/templates/orchestrator/tasks.md.template
vendored
Normal file
62
docs/templates/orchestrator/tasks.md.template
vendored
Normal file
@@ -0,0 +1,62 @@
|
||||
# Tasks
|
||||
|
||||
<!--
|
||||
Project: ${PROJECT}
|
||||
Milestone: ${MILESTONE}
|
||||
Created: ${CURRENT_DATETIME}
|
||||
|
||||
IMPORTANT: This file is owned by the orchestrator. Workers NEVER modify it.
|
||||
-->
|
||||
|
||||
<!--
|
||||
## Column Reference
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| id | string | Unique task ID (format: PREFIX-NNN, e.g., MS-SEC-001) |
|
||||
| status | enum | not-started, in-progress, done, blocked |
|
||||
| description | string | Brief task description with finding ID reference |
|
||||
| issue | string | Gitea issue reference (e.g., #337) |
|
||||
| repo | string | Target app/package (e.g., api, web, orchestrator) |
|
||||
| branch | string | Feature branch for this phase |
|
||||
| depends_on | string | Task IDs this depends on (comma-separated) |
|
||||
| blocks | string | Task IDs blocked by this (comma-separated) |
|
||||
| agent | string | Worker agent identifier (e.g., worker-1) |
|
||||
| started_at | ISO8601 | When work began |
|
||||
| completed_at | ISO8601 | When work finished |
|
||||
| estimate | string | Token estimate (e.g., 15K) |
|
||||
| used | string | Actual tokens used (e.g., 12.5K) |
|
||||
|
||||
## Status Workflow
|
||||
|
||||
not-started → in-progress → done
|
||||
↓
|
||||
blocked → in-progress (when unblocked)
|
||||
|
||||
## Task ID Convention
|
||||
|
||||
{PROJECT_PREFIX}-{PHASE}-{NUMBER}
|
||||
|
||||
Phase prefixes:
|
||||
- SEC: Security (Critical/High)
|
||||
- HIGH: High priority non-security
|
||||
- CQ: Code quality (Medium)
|
||||
- TEST: Test coverage (Low)
|
||||
- PERF: Performance
|
||||
- V01: Verification task
|
||||
|
||||
Examples: MS-SEC-001, MS-HIGH-015, MS-CQ-V01
|
||||
-->
|
||||
|
||||
| id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used |
|
||||
|----|--------|-------------|-------|------|--------|------------|--------|-------|------------|--------------|----------|------|
|
||||
| ${TASK_PREFIX}-001 | not-started | First task description | ${PHASE_ISSUE} | ${FIRST_REPO} | ${PHASE_BRANCH} | | ${TASK_PREFIX}-002 | | | | | |
|
||||
|
||||
<!--
|
||||
Add tasks above this line.
|
||||
|
||||
Dependency rules:
|
||||
1. All Phase N tasks depend on Phase N-1 verification task
|
||||
2. Same-file tasks should be sequential (earlier blocks later)
|
||||
3. Each phase ends with a verification task (e.g., MS-SEC-V01)
|
||||
-->
|
||||
262
docs/templates/reports/review-report-scaffold.sh
vendored
Executable file
262
docs/templates/reports/review-report-scaffold.sh
vendored
Executable file
@@ -0,0 +1,262 @@
|
||||
#!/bin/bash
|
||||
# review-report-scaffold.sh - Create review report directory structure
|
||||
# Usage: ./review-report-scaffold.sh <report-name> [project-name]
|
||||
|
||||
set -e
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
REPORT_NAME="${1:-codebase-review}"
|
||||
PROJECT_NAME="${2:-$(basename $(pwd))}"
|
||||
REPORT_DATE=$(date +%Y-%m-%d)
|
||||
REPORT_DIR="docs/reports/${REPORT_NAME}-${REPORT_DATE}"
|
||||
|
||||
if [[ -d "$REPORT_DIR" ]]; then
|
||||
echo "Warning: $REPORT_DIR already exists"
|
||||
read -p "Overwrite? [y/N] " -n 1 -r
|
||||
echo
|
||||
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
mkdir -p "${REPORT_DIR}"
|
||||
|
||||
# Create executive summary
|
||||
cat > "${REPORT_DIR}/00-executive-summary.md" << EOF
|
||||
# ${PROJECT_NAME} - ${REPORT_NAME}: Executive Summary
|
||||
|
||||
**Date:** ${REPORT_DATE}
|
||||
**Scope:** Full codebase review
|
||||
**Method:** Parallel review agents covering security, code quality, and QA/test coverage
|
||||
|
||||
---
|
||||
|
||||
## At a Glance
|
||||
|
||||
| Dimension | Findings | Critical | High | Medium | Low |
|
||||
|-----------|----------|----------|------|--------|-----|
|
||||
| Security - API | | | | | |
|
||||
| Security - Web | | | | | |
|
||||
| Security - Orchestrator | | | | | |
|
||||
| Code Quality - API | | | | | |
|
||||
| Code Quality - Web | | | | | |
|
||||
| Code Quality - Orchestrator | | | | | |
|
||||
| **Totals** | | | | | |
|
||||
|
||||
---
|
||||
|
||||
## Top 10 Most Urgent Findings
|
||||
|
||||
<!-- Populated by review agents -->
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
4.
|
||||
5.
|
||||
6.
|
||||
7.
|
||||
8.
|
||||
9.
|
||||
10.
|
||||
|
||||
---
|
||||
|
||||
## Summary by Workspace
|
||||
|
||||
### apps/api
|
||||
- **Security:**
|
||||
- **Code Quality:**
|
||||
- **Test Grade:**
|
||||
|
||||
### apps/web
|
||||
- **Security:**
|
||||
- **Code Quality:**
|
||||
- **Test Grade:**
|
||||
|
||||
### apps/orchestrator
|
||||
- **Security:**
|
||||
- **Code Quality:**
|
||||
- **Test Grade:**
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Create phase issues for critical/high findings
|
||||
2. Bootstrap tasks.md from findings
|
||||
3. Track remediation progress
|
||||
|
||||
EOF
|
||||
|
||||
# Create security review
|
||||
cat > "${REPORT_DIR}/01-security-review.md" << EOF
|
||||
# ${PROJECT_NAME} - Security Review
|
||||
|
||||
**Date:** ${REPORT_DATE}
|
||||
**Scope:** Security vulnerabilities, authentication, authorization, input validation
|
||||
|
||||
---
|
||||
|
||||
## Methodology
|
||||
|
||||
- Static code analysis
|
||||
- Dependency vulnerability scan
|
||||
- Authentication/authorization review
|
||||
- Input validation audit
|
||||
- Secret detection
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
### Critical Severity
|
||||
|
||||
<!--
|
||||
Format:
|
||||
#### SEC-{AREA}-{N}: {Title}
|
||||
|
||||
| Aspect | Detail |
|
||||
|--------|--------|
|
||||
| **Location** | \`path/to/file.ts:123\` |
|
||||
| **Risk** | Description of security risk |
|
||||
| **Impact** | What could happen if exploited |
|
||||
| **Remediation** | Steps to fix |
|
||||
| **Effort** | Estimate (e.g., 8K tokens) |
|
||||
-->
|
||||
|
||||
### High Severity
|
||||
|
||||
### Medium Severity
|
||||
|
||||
### Low Severity
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Severity | Count |
|
||||
|----------|-------|
|
||||
| Critical | |
|
||||
| High | |
|
||||
| Medium | |
|
||||
| Low | |
|
||||
|
||||
EOF
|
||||
|
||||
# Create code quality review
|
||||
cat > "${REPORT_DIR}/02-code-quality-review.md" << EOF
|
||||
# ${PROJECT_NAME} - Code Quality Review
|
||||
|
||||
**Date:** ${REPORT_DATE}
|
||||
**Scope:** Code patterns, error handling, performance, maintainability
|
||||
|
||||
---
|
||||
|
||||
## Methodology
|
||||
|
||||
- Pattern consistency analysis
|
||||
- Error handling audit
|
||||
- Performance anti-pattern detection
|
||||
- Type safety review
|
||||
- Memory leak detection
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
### Critical Severity
|
||||
|
||||
<!--
|
||||
Format:
|
||||
#### CQ-{AREA}-{N}: {Title}
|
||||
|
||||
| Aspect | Detail |
|
||||
|--------|--------|
|
||||
| **Location** | \`path/to/file.ts:123\` |
|
||||
| **Issue** | Description of the problem |
|
||||
| **Impact** | Effect on system behavior |
|
||||
| **Remediation** | Steps to fix |
|
||||
| **Effort** | Estimate (e.g., 10K tokens) |
|
||||
-->
|
||||
|
||||
### High Severity
|
||||
|
||||
### Medium Severity
|
||||
|
||||
### Low Severity
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Severity | Count |
|
||||
|----------|-------|
|
||||
| Critical | |
|
||||
| High | |
|
||||
| Medium | |
|
||||
| Low | |
|
||||
|
||||
EOF
|
||||
|
||||
# Create QA/test coverage review
|
||||
cat > "${REPORT_DIR}/03-qa-test-coverage.md" << EOF
|
||||
# ${PROJECT_NAME} - QA & Test Coverage Review
|
||||
|
||||
**Date:** ${REPORT_DATE}
|
||||
**Scope:** Test coverage gaps, testing patterns, quality assurance
|
||||
|
||||
---
|
||||
|
||||
## Coverage Summary
|
||||
|
||||
| Workspace | Statements | Branches | Functions | Lines | Grade |
|
||||
|-----------|------------|----------|-----------|-------|-------|
|
||||
| apps/api | | | | | |
|
||||
| apps/web | | | | | |
|
||||
| apps/orchestrator | | | | | |
|
||||
|
||||
---
|
||||
|
||||
## Critical Coverage Gaps
|
||||
|
||||
<!--
|
||||
Format:
|
||||
#### TEST-{AREA}-{N}: {Title}
|
||||
|
||||
| Aspect | Detail |
|
||||
|--------|--------|
|
||||
| **Location** | \`path/to/file.ts\` |
|
||||
| **Gap** | What is not tested |
|
||||
| **Risk** | Why this matters |
|
||||
| **Recommended Tests** | Specific tests to add |
|
||||
| **Effort** | Estimate (e.g., 15K tokens) |
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
## Testing Pattern Issues
|
||||
|
||||
### Missing Test Types
|
||||
|
||||
### Flaky Tests
|
||||
|
||||
### Test Organization
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
EOF
|
||||
|
||||
echo "Created: ${REPORT_DIR}/"
|
||||
echo " - 00-executive-summary.md"
|
||||
echo " - 01-security-review.md"
|
||||
echo " - 02-code-quality-review.md"
|
||||
echo " - 03-qa-test-coverage.md"
|
||||
echo ""
|
||||
echo "Next: Run review agents to populate findings"
|
||||
92
docs/templates/scratchpad.md.template
vendored
Normal file
92
docs/templates/scratchpad.md.template
vendored
Normal file
@@ -0,0 +1,92 @@
|
||||
# Issue #${ISSUE_NUMBER}: ${ISSUE_TITLE}
|
||||
|
||||
**Project:** ${PROJECT}
|
||||
**Milestone:** ${MILESTONE}
|
||||
**Task ID:** ${TASK_ID}
|
||||
**Started:** ${CURRENT_DATETIME}
|
||||
**Agent:** ${AGENT_ID}
|
||||
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
${TASK_DESCRIPTION}
|
||||
|
||||
**Finding reference:** See `docs/reports/` for detailed finding (search for ${FINDING_ID})
|
||||
|
||||
---
|
||||
|
||||
## Approach
|
||||
|
||||
### Analysis
|
||||
|
||||
<!-- Initial analysis of what needs to be done -->
|
||||
|
||||
### Implementation Plan
|
||||
|
||||
1. [ ] Step 1
|
||||
2. [ ] Step 2
|
||||
3. [ ] Step 3
|
||||
|
||||
### Files to Modify
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `path/to/file.ts` | Description |
|
||||
|
||||
---
|
||||
|
||||
## Progress
|
||||
|
||||
### ${CURRENT_DATE}
|
||||
|
||||
- [ ] Implementation started
|
||||
- [ ] Tests written
|
||||
- [ ] Quality gates passing
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
# Run relevant tests
|
||||
pnpm test --filter=@app/component
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
```
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- [ ] Feature works as expected
|
||||
- [ ] No regressions introduced
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
### Decisions Made
|
||||
|
||||
<!-- Document key decisions and rationale -->
|
||||
|
||||
### Blockers Encountered
|
||||
|
||||
<!-- Document any blockers and how resolved -->
|
||||
|
||||
### Learnings
|
||||
|
||||
<!-- Document learnings for orchestrator-learnings.json -->
|
||||
|
||||
---
|
||||
|
||||
## Completion Checklist
|
||||
|
||||
- [ ] Implementation complete
|
||||
- [ ] All tests passing
|
||||
- [ ] Quality gates pass (lint, typecheck)
|
||||
- [ ] Committed with proper message
|
||||
- [ ] tasks.md updated (by orchestrator)
|
||||
|
||||
**Completed:**
|
||||
**Actual tokens:** K
|
||||
Reference in New Issue
Block a user