From 463ece225baa1093b4752b716fe5a17955398d9c Mon Sep 17 00:00:00 2001 From: soryu Date: Mon, 9 Feb 2026 16:39:51 +0000 Subject: Add compound engineering feature proposals for makima Analyze the compound engineering plugin (https://github.com/EveryInc/compound-engineering-plugin) and propose 6 features inspired by its patterns for adoption into makima: - Multi-agent parallel review system (spawn-group/wait-group) - Knowledge accumulation / compound learning phase - Parallel plan deepening with research agents - Workflow presets / pipeline templates (LFG-style one-command pipelines) - Structured findings tracking with severity and lifecycle - Reusable task templates with meta-commands Co-Authored-By: Claude Opus 4.6 --- docs/proposals/feature-workflow-presets.md | 623 +++++++++++++++++++++++++++++ 1 file changed, 623 insertions(+) create mode 100644 docs/proposals/feature-workflow-presets.md (limited to 'docs/proposals/feature-workflow-presets.md') diff --git a/docs/proposals/feature-workflow-presets.md b/docs/proposals/feature-workflow-presets.md new file mode 100644 index 0000000..1468a8a --- /dev/null +++ b/docs/proposals/feature-workflow-presets.md @@ -0,0 +1,623 @@ +# 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 --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 `` 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. -- cgit v1.2.3