diff --git a/CLAUDE.md b/CLAUDE.md index 0f8a083..c668860 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,11 +5,15 @@ integration.** | 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` | | 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` | +## Platform Templates + +Bootstrap templates are at `docs/templates/`. See `docs/templates/README.md` for usage. + ## Project Overview Mosaic Stack is a standalone platform that provides: diff --git a/docs/claude/orchestrator.md b/docs/claude/orchestrator.md new file mode 100644 index 0000000..a9b2777 --- /dev/null +++ b/docs/claude/orchestrator.md @@ -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.** diff --git a/docs/templates/README.md b/docs/templates/README.md new file mode 100644 index 0000000..4fc18cb --- /dev/null +++ b/docs/templates/README.md @@ -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. diff --git a/docs/templates/orchestrator/compaction-summary.md.template b/docs/templates/orchestrator/compaction-summary.md.template new file mode 100644 index 0000000..a168561 --- /dev/null +++ b/docs/templates/orchestrator/compaction-summary.md.template @@ -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 + + +- ${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%* diff --git a/docs/templates/orchestrator/orchestrator-learnings.json.template b/docs/templates/orchestrator/orchestrator-learnings.json.template new file mode 100644 index 0000000..6e58bbe --- /dev/null +++ b/docs/templates/orchestrator/orchestrator-learnings.json.template @@ -0,0 +1,10 @@ +{ + "schema_version": "1.0", + "project": "${PROJECT}", + "milestone": "${MILESTONE}", + "created_at": "${CURRENT_DATETIME}", + "learnings": [], + "phase_summaries": [], + "proposed_adjustments": [], + "investigation_queue": [] +} diff --git a/docs/templates/orchestrator/orchestrator-learnings.schema.md b/docs/templates/orchestrator/orchestrator-learnings.schema.md new file mode 100644 index 0000000..a1decb1 --- /dev/null +++ b/docs/templates/orchestrator/orchestrator-learnings.schema.md @@ -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 | diff --git a/docs/templates/orchestrator/phase-issue-body.md.template b/docs/templates/orchestrator/phase-issue-body.md.template new file mode 100644 index 0000000..370b49f --- /dev/null +++ b/docs/templates/orchestrator/phase-issue-body.md.template @@ -0,0 +1,43 @@ +## Phase ${PHASE_NUMBER}: ${PHASE_NAME} + +**Milestone:** ${MILESTONE} +**Branch:** `${PHASE_BRANCH}` +**Estimate:** ${PHASE_ESTIMATE_K}K tokens + +--- + +### Scope + +${PHASE_SCOPE} + +### Tasks + + +- [ ] 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 diff --git a/docs/templates/orchestrator/tasks.md.template b/docs/templates/orchestrator/tasks.md.template new file mode 100644 index 0000000..99db04f --- /dev/null +++ b/docs/templates/orchestrator/tasks.md.template @@ -0,0 +1,62 @@ +# Tasks + + + + + +| 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 | | | | | | + + diff --git a/docs/templates/reports/review-report-scaffold.sh b/docs/templates/reports/review-report-scaffold.sh new file mode 100755 index 0000000..fce1fc2 --- /dev/null +++ b/docs/templates/reports/review-report-scaffold.sh @@ -0,0 +1,262 @@ +#!/bin/bash +# review-report-scaffold.sh - Create review report directory structure +# Usage: ./review-report-scaffold.sh [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 + + + +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 + + + +### 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 + + + +### 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 + + + +--- + +## 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" diff --git a/docs/templates/scratchpad.md.template b/docs/templates/scratchpad.md.template new file mode 100644 index 0000000..2adf6f7 --- /dev/null +++ b/docs/templates/scratchpad.md.template @@ -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 + + + +### 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 + + + +### Blockers Encountered + + + +### Learnings + + + +--- + +## 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