feat: Add self-contained orchestration templates and guide
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
2026-02-05 16:37:58 -06:00
parent 7390cac2cc
commit 53f2cd7f47
10 changed files with 1074 additions and 1 deletions

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 |