path: root/docs/proposals/feature-workflow-presets.md

# Feature Proposal: Workflow Presets / Pipeline Templates

> **Priority:** High
> **Complexity:** Medium
> **Estimated Effort:** 10-15 days
> **Status:** Proposal
> **Date:** 2026-02-09
> **Dependencies:** None (foundational feature)
> **Related:** [Overview Analysis](compound-engineering-analysis.md) · [Multi-Agent Review](feature-multi-agent-review.md) · [Knowledge Accumulation](feature-knowledge-accumulation.md)

---

## Problem Statement

Every makima contract currently requires **manual orchestration**:

- Users must decide which contract type to use (simple, specification, execute)
- Supervisors must manually spawn tasks, wait for results, advance phases
- There are **no pre-built pipelines** for common workflows (full feature development, quick bug fix, refactoring, investigation)
- The supervisor plan must encode the full orchestration logic every time
- **Repetitive patterns** (plan → execute → test → review) are re-invented for each contract
- New users face a steep learning curve to orchestrate contracts effectively

The compound engineering plugin's `/lfg` (Let's F***ing Go) and `/slfg` (Super LFG) commands solve this with **one-command full pipelines** that chain all phases automatically.

---

## How Compound Engineering Solves This

### LFG Pipeline (Serial)

```bash
/lfg "Implement user authentication"
```

Automatically chains:
```
Plan → Deepen Plan → Work → Review → Resolve Findings → Test → Compound → Done
```

### SLFG Pipeline (Parallel)

```bash
/slfg "Implement user authentication"
```

Same as LFG but parallelizes independent steps:
```
Plan ──▶ Deepen Plan ──▶ Work ──▶ ┌─ Review ─────┐ ──▶ Test ──▶ Compound
                                   │  (parallel)  │
                                   └──────────────┘
```

The key insight: **most engineering workflows follow predictable patterns** that can be templated and reused.

---

## Proposed Makima Implementation

### 1. Preset Definition Format

Presets are defined in YAML and describe a complete workflow:

```yaml
# .makima/presets/full-pipeline.yaml
name: full-pipeline
description: "Complete feature development pipeline with review and learning"
contract_type: specification
version: 1

# Variables that can be substituted at runtime
variables:
  task_description:
    required: true
    description: "What to build"
  repository:
    required: false
    description: "Target repository URL"
  base_branch:
    required: false
    default: "main"
    description: "Branch to work from"

# Phase configuration
phases:
  research:
    enabled: true
    deliverables:
      - id: research-notes
        name: "Research Notes"
        priority: required
    supervisor_plan: |
      Research the requirements for: {{ task_description }}
      - Analyze the existing codebase for relevant patterns
      - Identify dependencies and constraints
      - Document findings as research notes

  plan:
    enabled: true
    deliverables:
      - id: plan-document
        name: "Implementation Plan"
        priority: required
    supervisor_plan: |
      Create an implementation plan for: {{ task_description }}
      Based on the research findings.
    # Auto-deepen plan (requires Plan Deepening feature)
    deepen: true
    deepen_focus:
      - edge-cases
      - security
      - performance

  execute:
    enabled: true
    deliverables:
      - id: implementation
        name: "Implementation"
        priority: required
    supervisor_plan: |
      Execute the plan for: {{ task_description }}
      Follow the deepened plan step by step.
    # Spawn configuration
    max_concurrent_tasks: 3
    completion_action: "branch"

  review:
    enabled: true
    deliverables:
      - id: review-report
        name: "Review Report"
        priority: required
    # Auto-review configuration (requires Multi-Agent Review feature)
    auto_review: true
    review_agents:
      - security-sentinel
      - performance-oracle
      - architecture-strategist
      - test-coverage-analyzer
    merge_blocking_severity: P1

  compound:
    enabled: true
    # Auto-compound (requires Knowledge Accumulation feature)
    auto_compound: true
    categories:
      - architecture-decisions
      - security-practices
      - performance-optimizations

# Hooks
hooks:
  on_phase_complete:
    execute:
      - run: "makima supervisor spawn 'run-tests' --plan 'Run the full test suite'"
      - wait_for: "run-tests"
  on_contract_complete:
    - run: "makima supervisor compound"
```

### 2. Built-In Presets

#### `full-pipeline` — Complete Feature Development

```
Research → Plan → Deepen → Execute → Test → Review → Resolve → Compound
```

Best for: New features, major changes, complex implementations.

#### `quick-fix` — Rapid Bug Fix

```
Execute → Test → Done
```

Best for: Small bug fixes, typo corrections, config changes.

```yaml
# .makima/presets/quick-fix.yaml
name: quick-fix
description: "Fast bug fix with minimal ceremony"
contract_type: simple

phases:
  plan:
    enabled: true
    deliverables:
      - id: fix-plan
        name: "Fix Plan"
        priority: required
    supervisor_plan: |
      Quick analysis and fix plan for: {{ task_description }}
      Keep it brief — identify the bug and the fix.

  execute:
    enabled: true
    deliverables:
      - id: fix
        name: "Bug Fix"
        priority: required
    supervisor_plan: |
      Fix the bug: {{ task_description }}
      Run relevant tests after fixing.
    completion_action: "branch"
```

#### `refactor` — Code Refactoring

```
Research → Plan → Deepen → Execute → Test → Review → Done
```

Best for: Code restructuring, pattern changes, dependency updates.

```yaml
# .makima/presets/refactor.yaml
name: refactor
description: "Systematic refactoring with safety checks"
contract_type: specification

phases:
  research:
    enabled: true
    supervisor_plan: |
      Analyze the codebase to understand the current structure for: {{ task_description }}
      Document all files that will be affected.
      Identify dependencies and potential breaking changes.

  plan:
    enabled: true
    deepen: true
    deepen_focus:
      - edge-cases
      - patterns
    supervisor_plan: |
      Create a step-by-step refactoring plan for: {{ task_description }}
      Ensure each step maintains a working state (no big-bang changes).

  execute:
    enabled: true
    supervisor_plan: |
      Execute the refactoring plan for: {{ task_description }}
      After each significant change, run tests to verify nothing is broken.
    completion_action: "branch"

  review:
    enabled: true
    auto_review: true
    review_agents:
      - architecture-strategist
      - test-coverage-analyzer
    merge_blocking_severity: P1
```

#### `investigation` — Research & Analysis

```
Research → Document → Done
```

Best for: Bug investigation, feasibility analysis, technology evaluation.

```yaml
# .makima/presets/investigation.yaml
name: investigation
description: "Research-focused workflow for analysis and documentation"
contract_type: simple

phases:
  plan:
    enabled: true
    supervisor_plan: |
      Plan the investigation for: {{ task_description }}
      Define what questions need answering and what to examine.

  execute:
    enabled: true
    deliverables:
      - id: investigation-report
        name: "Investigation Report"
        priority: required
    supervisor_plan: |
      Investigate: {{ task_description }}
      Document findings thoroughly.
      Create actionable recommendations.
    completion_action: "none"
```

### 3. Preset Discovery & Usage

#### CLI Commands

```bash
# List available presets
makima preset list
# Output:
# NAME             DESCRIPTION                                  SOURCE
# full-pipeline    Complete feature development pipeline         built-in
# quick-fix        Fast bug fix with minimal ceremony            built-in
# refactor         Systematic refactoring with safety checks     built-in
# investigation    Research-focused analysis workflow             built-in
# custom-deploy    Deployment pipeline with staging              .makima/presets/

# Run a preset
makima preset run full-pipeline \
  --var task_description="Add user authentication with JWT" \
  --var repository="github.com/org/repo"

# Run with interactive variable input
makima preset run full-pipeline

# Preview what a preset will do (dry run)
makima preset preview full-pipeline \
  --var task_description="Add user authentication with JWT"

# Create a new preset from an existing contract
makima preset create --from-contract <contract-id> --name "my-workflow"

# Validate a preset file
makima preset validate .makima/presets/my-preset.yaml
```

#### Under the Hood

When `makima preset run full-pipeline` executes:

```
1. Parse preset YAML
2. Substitute variables
3. Create contract with specified type
4. Configure phases from preset
5. Create supervisor task with generated plan
6. Supervisor executes phases according to preset configuration
7. Auto-triggers (review, compound) fire at appropriate phase transitions
```

```
┌─────────────────────────────────────────────────────────┐
│                    Preset Engine                         │
│                                                         │
│  ┌──────────┐    ┌──────────┐    ┌──────────────────┐  │
│  │  Parse   │───▶│ Variable │───▶│ Create Contract  │  │
│  │  YAML    │    │  Subst.  │    │ + Supervisor     │  │
│  └──────────┘    └──────────┘    └────────┬─────────┘  │
│                                           │             │
│                  ┌────────────────────────┐│             │
│                  │  Phase Orchestration   ││             │
│                  │                        │▼             │
│                  │  research ──▶ plan ──▶ execute       │
│                  │                   │         │        │
│                  │             deepen-plan     │        │
│                  │             (if enabled)    │        │
│                  │                             ▼        │
│                  │                    review ──▶ compound│
│                  │                    (auto)    (auto)  │
│                  └────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```

### 4. Custom Preset Creation

Users create presets at three levels:

| Level | Location | Scope |
|-------|----------|-------|
| Built-in | Shipped with makima | All users |
| Repository | `.makima/presets/` | All users of the repo |
| User | `~/.makima/presets/` | Single user |

**Precedence**: User > Repository > Built-in (same name overrides)

#### Creating from Existing Contract

```bash
# Analyze a successful contract and generate a preset from it
makima preset create --from-contract abc-123 --name "my-api-workflow"

# This generates:
# ~/.makima/presets/my-api-workflow.yaml
# with phases, timings, and patterns extracted from the contract
```

---

## Integration with Existing Makima Features

### Contract System

Presets create contracts with the appropriate type:
```rust
// Preset specifies contract_type
let contract = create_contract(CreateContractRequest {
    name: format!("{} ({})", task_description, preset.name),
    contract_type: preset.contract_type.clone(), // "simple", "specification", "execute"
    phase: preset.first_enabled_phase(),
    autonomous_loop: true,
    phase_guard: preset.phase_guard,
    // ...
});
```

### Supervisor Plans

The preset generates a comprehensive supervisor plan by combining phase-specific instructions:

```rust
let supervisor_plan = preset.generate_supervisor_plan(&variables);
// This produces a plan like:
// "You are orchestrating a full-pipeline workflow.
//  Phase 1 (Research): ...
//  Phase 2 (Plan): ...
//  ..."
```

### Directive System Integration

For complex presets, phases can be modeled as directive steps with dependencies:

```rust
// Each phase becomes a directive step
let steps = preset.phases.iter().map(|phase| {
    DirectiveStep {
        name: phase.name.clone(),
        description: Some(phase.description.clone()),
        task_plan: Some(phase.supervisor_plan.clone()),
        depends_on: phase.dependencies(),
        // ...
    }
}).collect();
```

This allows parallel phases (e.g., independent review agents) to execute concurrently while respecting dependencies.

### Hooks System

Presets define hooks that trigger at phase transitions:

```yaml
hooks:
  on_phase_complete:
    execute:
      - run: "makima supervisor spawn 'tests' --plan 'Run test suite'"
      - wait_for: "tests"
  on_review_complete:
    - condition: "findings.p1_count == 0"
      run: "makima supervisor advance-phase compound -y"
    - condition: "findings.p1_count > 0"
      run: "makima supervisor ask 'P1 findings detected. Continue?' --choices 'Fix first,Continue anyway'"
```

### Autonomous Loop

Presets work with the existing autonomous loop:
- Each phase uses `<COMPLETION_GATE>` to signal completion
- Circuit breaker prevents stuck phases
- `autonomous_loop: true` on the contract enables automatic continuation

---

## Implementation Plan

### Phase 1: Core Preset Engine (4-5 days)

| Task | Effort | Description |
|------|--------|-------------|
| Preset YAML schema definition | 0.5 days | Define YAML format, validation rules |
| YAML parser with variable substitution | 1 day | Parse presets, substitute `{{ variables }}` |
| `preset list` command | 0.5 days | Discover and list available presets |
| `preset run` command | 1.5 days | Create contract + supervisor from preset |
| `preset preview` command | 0.5 days | Dry-run display |
| Built-in preset definitions | 1 day | Write 4 default presets |

### Phase 2: Custom Presets (3-5 days)

| Task | Effort | Description |
|------|--------|-------------|
| User/repo preset discovery | 1 day | Multi-level preset resolution |
| `preset create` command | 1.5 days | Generate preset from existing contract |
| `preset validate` command | 0.5 days | Validate preset YAML |
| Preset versioning | 1 day | Version field, migration support |

### Phase 3: Integration & Polish (3-5 days)

| Task | Effort | Description |
|------|--------|-------------|
| Hooks system | 1.5 days | Phase transition hooks |
| Auto-trigger integration | 1 day | Wire to review/compound auto-triggers |
| Directive system integration | 1 day | Complex presets as directive DAGs |
| Documentation | 0.5 days | User guide, preset authoring guide |

---

## Configuration Examples

### Running a Preset

```bash
# Simplest usage — one command to run a full pipeline
makima preset run full-pipeline --var task_description="Add OAuth2 login"

# This creates:
# - Contract: "Add OAuth2 login (full-pipeline)"
# - Supervisor task with complete phase orchestration
# - Auto-review enabled
# - Auto-compound enabled
# - All phases configured with deliverables
```

### Creating a Custom Preset

```yaml
# .makima/presets/api-feature.yaml
name: api-feature
description: "API feature development with schema validation"
contract_type: specification
version: 1

variables:
  feature_name:
    required: true
    description: "Name of the API feature"
  api_version:
    required: false
    default: "v1"
    description: "API version"

phases:
  research:
    enabled: true
    supervisor_plan: |
      Research existing API patterns in the codebase for {{ api_version }}.
      Document the current API schema structure.
      Identify relevant endpoints and data models for {{ feature_name }}.

  plan:
    enabled: true
    deepen: true
    deepen_focus:
      - api-patterns
      - security
      - edge-cases
    supervisor_plan: |
      Plan the {{ feature_name }} API feature for {{ api_version }}.
      Include: endpoint design, request/response schemas, validation rules,
      error handling, and test cases.

  execute:
    enabled: true
    max_concurrent_tasks: 2
    supervisor_plan: |
      Implement the {{ feature_name }} API feature.
      Follow the plan. Create endpoints, handlers, validators, and tests.
      Run tests after implementation.
    completion_action: "branch"

  review:
    enabled: true
    auto_review: true
    review_agents:
      - security-sentinel
      - api-contract-validator
      - test-coverage-analyzer
    merge_blocking_severity: P1

  compound:
    enabled: true
    auto_compound: true
    categories:
      - api-patterns
      - security-practices
```

### Listing Presets

```
$ makima preset list

BUILT-IN PRESETS
  full-pipeline     Complete feature development pipeline with review and learning
  quick-fix         Fast bug fix with minimal ceremony
  refactor          Systematic refactoring with safety checks
  investigation     Research-focused analysis workflow

REPOSITORY PRESETS (.makima/presets/)
  api-feature       API feature development with schema validation
  migration         Database migration with rollback plan

USER PRESETS (~/.makima/presets/)
  my-workflow       Custom workflow for frontend development
```

---

## Open Questions

1. **Preset inheritance**: Should presets be able to extend other presets? (e.g., `extends: full-pipeline` with overrides)
2. **Conditional phases**: Should phases be conditionally enabled based on runtime conditions? (e.g., skip review for changes under 50 lines)
3. **Preset parameters validation**: How strict should variable validation be? Allow arbitrary variables or enforce a schema?
4. **Preset sharing**: Should presets be sharable via a registry or marketplace?
5. **Preset analytics**: Should we track which presets are most used and their success rates?
6. **Rollback**: If a preset-driven workflow fails mid-phase, how should recovery work?
7. **Interactive mode**: Should presets support interactive steps where the user provides input mid-pipeline?

---

## Alternatives Considered

| Alternative | Pros | Cons | Decision |
|-------------|------|------|----------|
| Hardcoded pipelines | Simple, predictable | Not customizable; one-size-fits-all | Rejected — need flexibility |
| Pure CLI scripting | Maximum flexibility | Not portable; error-prone; no validation | Rejected — too fragile |
| GUI workflow builder | Visual, intuitive | High development cost; not scriptable | Deferred — consider for UI |
| Contract type expansion | Minimal new concepts | Doesn't solve orchestration; just adds phase combos | Partial — presets use contract types |
| Makefile-style approach | Familiar to developers | Wrong abstraction level; no variable substitution | Rejected — YAML is better fit |

---

## Priority & Complexity Assessment

- **Priority: HIGH** — Workflow presets are the **gateway feature** that makes all other features accessible. Without presets, users must manually orchestrate review, deepening, and compounding. With presets, these features are activated with a single command.
- **Complexity: MEDIUM** — YAML parsing and variable substitution are straightforward. Hooks system and directive integration add complexity. Main challenge is designing a preset schema that's flexible enough for diverse workflows without being overwhelming.
- **Risk: LOW** — Presets are purely additive. They don't change existing behavior. Users can always fall back to manual orchestration.