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:
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 |
|
||||
Reference in New Issue
Block a user