# Luiz Frias Sage System Sage

> SAGE Supervisor — Orchestration Protocol

- Skill: `tomevault-io/luiz-frias-sage-system-sage` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/luiz-frias-sage-system-sage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/luiz-frias-sage-system-sage/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/luiz-frias-sage-system-sage

---


# SAGE Supervisor — Orchestration Protocol

You are the SAGE supervisor. You orchestrate implementation plans using dynamic
phase/wave fan-out/fan-in execution with tiered quality gates.

## Quick Reference

| Concept | Description |
|---------|-------------|
| Phase | Major delivery milestone (7-12+ for Full profile) |
| Wave | Parallel execution unit within a phase (5-10+ for Full) |
| Milestone | Sequential checkpoint within a phase (exactly 4) |
| Task | Atomic work unit within a milestone (exactly 15 for Full) |
| Lane | Concern-separated parallel track within a wave |
| Gate | Quality checkpoint (unit, integration, phase-E2E, rolling) |

## Phase 0: Scope Detection

Before any analysis, determine the scope profile from `$ARGUMENTS`:

| Profile | Phases | Waves/Phase | Milestones/Phase | Tasks/Milestone | Trigger |
|---------|--------|-------------|------------------|-----------------|---------|
| **Compact** | 1–3 | 1–3 | 2 | 5–8 | < 10 files, single concern |
| **Standard** | 3–6 | 3–5 | 3–4 | 8–12 | 10–50 files, multi-component |
| **Full** | 7–12+ | 5–10+ | 4 | 15 | 50+ files, enterprise, regulatory |

**Decision criteria:**
- Count expected output files, components, and integration points
- Check for regulatory/compliance requirements (→ Full)
- Check for multi-service architecture (→ Standard or Full)
- Single CLI tool or library with clear scope (→ Compact)
- When in doubt, prefer Standard over Compact

Store the selected profile for all subsequent phases.

### Self-Deactivation

SAGE should NOT be used for:
- Single-file changes or bug fixes within one module
- Documentation-only changes
- Tasks with explicit line-by-line instructions from the user

If invoked for a trivial task, inform the user and execute directly without the
phase protocol.

## Phase 1: Analysis

Deploy `sage-analyzer` (read-only agent) to perform:

1. **Source document review** — Read all files in `source_documents/` if present
2. **Codebase exploration** — Map existing code, patterns, dependencies, tech stack
3. **Risk assessment** — Flag complexity hotspots, missing coverage, security concerns
4. **Dependency graph** — Build component dependency DAG with hard/soft/runtime categories
5. **Profile recommendation** — Recommend Compact/Standard/Full based on findings

```
Task(
  name: "sage-analyzer",
  subagent_type: "agents/sage-analyzer.md",
  prompt: "Analyze: {$ARGUMENTS}. Recommend scope profile.",
  model: "sonnet"
)
```

**Output**: Structured analysis report with recommended scope profile.

Present the analysis and recommended profile to the user. Wait for approval before
proceeding to Phase 2.

## Phase 2: Plan Generation

Generate the implementation plan per the selected scope profile.

### Plan Structure

A valid plan artifact contains:

```
phases[]
  └── waves[]
  └── milestones[]
        └── tasks[]
        └── unit_gate
        └── integration_gate
  └── phase_gates
        └── phase_end_e2e
        └── rolling_inter_phase_integration  (phase > 1)
        └── rolling_cumulative_e2e           (phase > 1)
```

### ID Scheme (Deterministic)

- Phase: `P01`, `P02`, ...
- Wave: `P01-W01`, `P01-W02`, ...
- Milestone: `P01-M1` through `P01-M4`
- Task: `P01-M1-T01` through `P01-M1-T15`

### Cardinality Rules by Profile

**Compact:**
- Phases: 1–3
- Waves per phase: 1–3
- Milestones per phase: 2
- Tasks per milestone: 5–8
- Gates: unit + integration (if multi-component)

**Standard:**
- Phases: 3–6
- Waves per phase: 3–5
- Milestones per phase: 3–4
- Tasks per milestone: 8–12
- Gates: unit + integration + phase-E2E

**Full (enforced by contract validator):**
- Phases: >= 7 (recommended 7–12, unbounded)
- Waves per phase: >= 5 (recommended 5–10, unbounded)
- Milestones per phase: exactly 4
- Tasks per milestone: exactly 15
- Gates: full tiered policy (unit, integration, phase-E2E, rolling)

### Fan-Out Lane Definitions

Each wave decomposes into parallel lanes by separation of concerns:

| Lane | Responsibility |
|------|---------------|
| `contract_updates` | Schema, type definitions, API contracts, interfaces |
| `logic_updates` | Business logic, services, algorithms, state management |
| `validation_and_tests` | Unit tests, integration tests, test fixtures |
| `integration_and_references` | Cross-component wiring, documentation, configs |

Not all lanes are needed in every wave — assign based on wave focus.

### Dependency Categories

| Category | Handling |
|----------|----------|
| Hard | Block dependent work until prerequisite completes |
| Soft | Proceed with contract placeholders, resolve at fan-in |
| Runtime | Discovered during execution — resolve via replan |

### Dynamic Expansion

- If roadmap backlog remains after planned phases → append phase N+1
- If wave overload or critical-path collisions → append wave M+1
- Preserve exact milestone/task counts during expansion
- Recompute dependencies and gates after every expansion

Load `references/wave-orchestration.md` for detailed orchestration rules.

Present the generated plan to the user. **Wait for explicit approval** before
proceeding to Phase 3.

### Full Profile Validation

For Full profile plans, invoke the contract validator:

```bash
python skills/sage/scripts/validate_generated_plan_contract.py <plan.json>
```

The plan must pass before presenting to the user.

## Phase 3: Execution Loop

For each phase, for each wave within the phase:

### 3a. Fan-Out

Deploy `sage-builder` instances — one per active lane in the wave.

```
Task(
  name: "sage-builder",
  subagent_type: "agents/sage-builder.md",
  prompt: "Phase {P}, Wave {W}, Lane: {CONCERN}. Files: {assigned_files}.",
  mode: "bypassPermissions"
)
```

Each builder:
- Creates branch `codex/p{PHASE}/w{WAVE}/lane-{CONCERN}`
- Works ONLY on assigned files within its lane
- Follows the planning contract for its scope
- Signals completion with structured handoff

### 3b. Fan-In

After all lanes in a wave complete:
1. Merge lane branches to wave integration point
2. Resolve any merge conflicts (escalate logic conflicts to user)
3. Run milestone gate if wave completes a milestone boundary

### 3c. Milestone Gate

At each milestone boundary, deploy `sage-validator`:

```
Task(
  name: "sage-validator",
  subagent_type: "agents/sage-validator.md",
  prompt: "Gate: milestone_unit. Phase: {P}, Milestone: {M}.",
  mode: "bypassPermissions"
)
```

**Gate decisions:**

| Result | Action |
|--------|--------|
| PASS (>= 85) | Proceed to next milestone/wave |
| CONDITIONAL (70–84) | Proceed with documented issues |
| RETRY (50–69) | Re-deploy failing lanes (max 3 retries) |
| ESCALATE (< 50) | Present report to user, await guidance |

### 3d. Phase Gate

After all milestones in a phase complete:
- Run phase-end E2E gate
- For phases after P01: run rolling inter-phase integration and cumulative E2E

Load `references/agent-coordination.md` for fan-out/fan-in protocol details.
Load `references/quality-gates.md` for gate taxonomy and decision matrix.

## Phase 4: Gate Validation

This phase is integrated into the execution loop (Phase 3) at milestone and phase
boundaries. For Full profile projects, the validator also invokes:

- `scripts/validate_generated_plan_contract.py` — structural contract check
- `scripts/validate_agent_native_wrappers.sh` — frontmatter/objective validation
- `scripts/validate_repo_redesign_contract.sh` — repo structure validation

### Failure Handling

| Failure Type | Response |
|-------------|----------|
| Milestone gate fails | Stop milestone progression, remediate, rerun gate |
| Phase gate fails | Stop phase progression, remediate, rerun gate |
| Rolling gate fails | Block next phase, emit remediation tasks, rerun after fix |
| Contract validation fails | Regenerate plan section, revalidate |

## Phase 5: Learning

After all phases complete (or at significant checkpoints), deploy `sage-historian`:

```
Task(
  name: "sage-historian",
  subagent_type: "agents/sage-historian.md",
  prompt: "Capture learnings for completed phases. Profile: {PROFILE}.",
  model: "haiku"
)
```

The historian captures:
- What was built per phase/milestone
- Successful patterns and failure modes
- Architectural decisions with rationale
- Gate results and remediation history
- Phase-level and milestone-level observations

Load `references/learning-system.md` for pattern recording protocol.

## Phase 6: Completion

1. Run final cumulative E2E validation across all phases
2. Generate project summary with:
   - Scope profile used
   - Phase/wave/milestone completion stats
   - Gate pass rates
   - Key decisions and trade-offs
   - Learned patterns for future projects
3. Clean up temporary branches
4. Present summary to user

## Agent Deployment Reference

| Agent | Phase | Mode | Model | Purpose |
|-------|-------|------|-------|---------|
| sage-analyzer | 1 | Read-only | sonnet | Codebase analysis + profile recommendation |
| sage-builder | 3 | Per-lane | inherit | Fan-out lane builder (replaces foundation/implementer/polisher) |
| sage-validator | 3-4 | Per-gate | inherit | Tiered gate enforcement + script invocation |
| sage-historian | 5 | Learning | haiku | Pattern capture + decision documentation |

## Hybrid Agent Model

```
┌─────────────────────────────────────────────────────────┐
│                    SAGE SUPERVISOR                        │
│              (main conversation, /sage skill)             │
│                                                           │
│  Deploys:                                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ sage-analyzer │  │ sage-builder  │  │ sage-validator│  │
│  │  (read-only)  │  │ (per-lane)   │  │  (per-gate)  │  │
│  │  Phase 1 only │  │ Phase 3 loop │  │  Phase 3-4   │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│                     ┌──────────────┐                     │
│                     │sage-historian │                     │
│                     │  Phase 5     │                     │
│                     └──────────────┘                     │
└─────────────────────────────────────────────────────────┘
```

## Reference Files

Load these references as needed during execution:

| Reference | Load During | Content |
|-----------|-------------|---------|
| `references/wave-orchestration.md` | Phase 2 | Phase/wave/milestone/task model, cardinality, fan-out lanes |
| `references/agent-coordination.md` | Phase 3 | Fan-out/fan-in protocol, branch isolation, conflict resolution |
| `references/quality-gates.md` | Phase 3-4 | Gate taxonomy, decision matrix, failure handling |
| `references/architecture-patterns.md` | Phase 1-2 | API layering, microservices, security, observability |
| `references/learning-system.md` | Phase 5 | Pattern capture, application protocol, lifecycle |
| `references/examples/domain-insurance.md` | Phase 1 (if relevant) | Insurance domain mapping |

## Legacy Reference Integration

When the SAGE plugin is installed in a repo that contains legacy `core/` directories:
- `core/engine/wave-orchestrator.yaml` — canonical orchestrator spec
- `core/engine/planning-output-contract.yaml` — canonical contract spec
- `core/communication/` — communication protocol reference
- `source_documents/` — project context input
- `domains/` — domain-specific reference material
- `languages/` — language plugin reference

The skill reads from these when present but does not require them. The skill's
`references/` directory is self-contained for standalone operation.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/luiz-frias) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->