Files

ci/woodpecker/push/woodpecker Pipeline failed

Details

feat: Add self-contained orchestration templates and guide

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>

2026-02-05 16:37:58 -06:00

3.9 KiB

Raw Blame History

Orchestrator Learnings JSON Schema

Reference documentation for orchestrator-learnings.json structure.

Root Object

{
  "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%.

{
  "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.

{
  "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.

{
  "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.

{
  "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

3.9 KiB Raw Blame History Unescape Escape