mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

feat: Add self-contained orchestration templates and guide
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
Details

Browse Source 
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
2026-02-05 16:37:58 -06:00
parent 7390cac2cc
commit 53f2cd7f47
10 changed files with 1074 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
CLAUDE.md
View File

@@ -5,11 +5,15 @@ integration.**
| When working on... | Load this guide | | When working on... | Load this guide |
| ---------------------------------------- | ------------------------------------------------------------------- | | ---------------------------------------- | ------------------------------------------------------------------- |
| Orchestrating autonomous task completion | `~/.claude/agent-guides/orchestrator.md` | | Orchestrating autonomous task completion | `docs/claude/orchestrator.md` |
| Security remediation (review findings) | `docs/reports/codebase-review-2026-02-05/01-security-review.md` | | Security remediation (review findings) | `docs/reports/codebase-review-2026-02-05/01-security-review.md` |
| Code quality fixes | `docs/reports/codebase-review-2026-02-05/02-code-quality-review.md` | | Code quality fixes | `docs/reports/codebase-review-2026-02-05/02-code-quality-review.md` |
| Test coverage gaps | `docs/reports/codebase-review-2026-02-05/03-qa-test-coverage.md` | | Test coverage gaps | `docs/reports/codebase-review-2026-02-05/03-qa-test-coverage.md` |
## Platform Templates
Bootstrap templates are at `docs/templates/`. See `docs/templates/README.md` for usage.
## Project Overview ## Project Overview
Mosaic Stack is a standalone platform that provides: Mosaic Stack is a standalone platform that provides:

360
docs/claude/orchestrator.md Normal file
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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
View 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