path: root/docs/proposals/feature-task-templates.md

# Feature Proposal: Reusable Task Templates & Meta-Commands

> **Priority:** Medium
> **Complexity:** Medium
> **Estimated Effort:** 8-12 days
> **Status:** Proposal
> **Date:** 2026-02-09
> **Dependencies:** None (standalone, but complements [Workflow Presets](feature-workflow-presets.md))
> **Related:** [Overview Analysis](compound-engineering-analysis.md) · [Workflow Presets](feature-workflow-presets.md) · [Multi-Agent Review](feature-multi-agent-review.md)

---

## Problem Statement

Makima tasks are created with **ad-hoc plans** every time:

- **No plan reuse** — even when spawning the same type of task (e.g., "add API endpoint"), the plan is written from scratch
- **No standardization** — different supervisors produce different quality plans for the same task type
- **No best practices encoding** — hard-won knowledge about how to structure certain tasks isn't captured
- **No variable substitution** — plans can't be parameterized for reuse
- **No validation** — there's no way to verify a plan includes required steps before execution
- **No meta-creation** — the system cannot create its own task templates or improve its own capabilities

The compound engineering plugin addresses this with meta-commands (`/create-agent-skill`, `/heal-skill`) that allow the system to create and repair its own specialized capabilities.

---

## How Compound Engineering Solves This

### `/create-agent-skill`

Creates new specialized agents and skills on demand:

```bash
/create-agent-skill "database migration reviewer"
```

This generates:
1. An agent definition file with specialized prompts
2. A skill file that exposes the agent as a command
3. Registration in the agent/skill registry

### `/heal-skill`

When a skill breaks (e.g., after a dependency change), this meta-command:
1. Analyzes the error
2. Identifies the root cause
3. Patches the skill definition
4. Tests the fix

The key insight: **the system should be able to improve and extend itself**.

---

## Proposed Makima Implementation

### 1. Task Recipe Format

Task recipes are parameterized plan templates with validation and metadata:

```yaml
# .makima/recipes/api-endpoint.yaml
name: api-endpoint
description: "Create a new REST API endpoint"
version: 1
author: "team"
tags: [api, backend, rest]

# Input variables
variables:
  endpoint_name:
    required: true
    description: "Name of the endpoint (e.g., 'users', 'orders')"
    validation: "^[a-z][a-z0-9-]*$"

  http_method:
    required: true
    description: "HTTP method"
    enum: [GET, POST, PUT, PATCH, DELETE]
    default: GET

  resource_name:
    required: true
    description: "Name of the resource/model"

  requires_auth:
    required: false
    default: true
    description: "Whether the endpoint requires authentication"

  database_table:
    required: false
    description: "Database table name (if applicable)"

# Plan template with variable substitution
plan: |
  ## Task: Create {{ http_method }} /api/{{ endpoint_name }} Endpoint

  ### Step 1: Define Route
  Add the `{{ http_method }} /api/{{ endpoint_name }}` route to the router.
  {% if requires_auth %}
  Apply authentication middleware to this route.
  {% endif %}

  ### Step 2: Create Handler
  Create the handler function for {{ endpoint_name }}.
  {% if database_table %}
  The handler should query the `{{ database_table }}` table.
  {% endif %}

  ### Step 3: Request/Response Models
  Define request and response types for the {{ resource_name }} resource.
  Include validation for all input fields.

  ### Step 4: Error Handling
  Implement proper error responses:
  - 400 for validation errors
  - 401 for authentication failures
  {% if requires_auth %}
  - 403 for authorization failures
  {% endif %}
  - 404 for not found
  - 500 for server errors

  ### Step 5: Tests
  Write tests covering:
  - Happy path
  - Input validation
  {% if requires_auth %}
  - Authentication required
  - Authorization check
  {% endif %}
  - Error cases
  - Edge cases

  ### Step 6: Documentation
  Update API documentation with:
  - Endpoint URL and method
  - Request/response schemas
  - Example requests and responses
  - Error codes

# Validation rules — checks that must pass before execution
validation:
  - check: "file_exists"
    path: "src/api/mod.rs"
    message: "API module must exist"
  - check: "grep"
    pattern: "Router"
    path: "src/api/mod.rs"
    message: "Router must be defined in API module"

# Expected outputs
outputs:
  files:
    - "src/api/{{ endpoint_name }}.rs"
    - "src/api/{{ endpoint_name }}_test.rs"
  tests:
    - "cargo test {{ endpoint_name }}"

# Metadata for recipe discovery
metadata:
  estimated_time: "30-60 minutes"
  difficulty: "easy"
  example_usage: |
    makima recipe run api-endpoint \
      --var endpoint_name=users \
      --var http_method=GET \
      --var resource_name=User \
      --var database_table=users
```

### 2. Recipe Registry

Recipes are discovered from three sources (same hierarchy as workflow presets):

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

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

### 3. Supervisor Commands

#### List Available Recipes

```bash
makima recipe list

# Output:
# NAME              DESCRIPTION                          SOURCE     TAGS
# api-endpoint      Create a new REST API endpoint        built-in   api, backend
# db-migration      Create a database migration           built-in   database
# react-component   Create a React component              built-in   frontend, react
# unit-test         Create unit tests for a module        built-in   testing
# bug-fix           Structured bug fix workflow            built-in   debugging
# custom-validator  Create input validation module         repo       validation
```

#### Run a Recipe

```bash
# Run with explicit variables
makima recipe run api-endpoint \
  --var endpoint_name=users \
  --var http_method=GET \
  --var resource_name=User \
  --var database_table=users

# Run with interactive variable input
makima recipe run api-endpoint

# Preview the generated plan (dry run)
makima recipe preview api-endpoint \
  --var endpoint_name=users \
  --var http_method=GET
```

#### Create a Recipe

```bash
# Create recipe from scratch
makima recipe create --name "my-recipe" --edit

# Generate recipe from a completed task (meta-creation)
makima recipe create --from-task <task-id> --name "my-recipe"

# Generate recipe from a plan file
makima recipe create --from-plan plan.md --name "my-recipe"
```

#### Validate a Recipe

```bash
# Validate recipe file
makima recipe validate .makima/recipes/my-recipe.yaml

# Validate recipe variables
makima recipe validate api-endpoint \
  --var endpoint_name=users \
  --var http_method=GET
```

### 4. Meta-Commands: Self-Improving Templates

The most powerful aspect of the compound engineering plugin is its ability to **create its own capabilities**. Makima can implement similar meta-commands:

#### `makima recipe generate`

The system analyzes completed tasks and suggests recipe templates:

```bash
# Analyze recent tasks and suggest recipes
makima recipe generate --analyze-last 20

# Output:
# Detected patterns:
# 1. "API endpoint creation" — 7 tasks followed similar pattern
#    Suggested recipe: api-endpoint (confidence: 0.89)
#    Variables: endpoint_name, http_method, resource_name
#
# 2. "Database migration" — 4 tasks followed similar pattern
#    Suggested recipe: db-migration (confidence: 0.76)
#    Variables: table_name, migration_type
#
# Generate these recipes? [y/N]
```

#### `makima recipe heal`

When a recipe fails repeatedly, the system can analyze and fix it:

```bash
# Analyze recipe failures and suggest fixes
makima recipe heal api-endpoint

# Output:
# Analyzed 3 recent failures of 'api-endpoint':
# Root cause: Step 1 references 'src/api/mod.rs' but project uses 'src/routes/mod.rs'
# Suggested fix: Change validation path and plan references
# Apply fix? [y/N]
```

#### `makima recipe evolve`

Improve recipes based on review findings:

```bash
# Check if review findings suggest recipe improvements
makima recipe evolve api-endpoint --from-findings

# Output:
# Review findings from tasks using 'api-endpoint' recipe:
# - SEC-001: "Missing rate limiting" (3 occurrences)
# - PERF-001: "Missing pagination" (2 occurrences)
#
# Suggested additions to recipe:
# 1. Add "Rate Limiting" step after Step 1
# 2. Add pagination to Step 2 for GET endpoints
# Apply improvements? [y/N]
```

### 5. Built-In Recipes

#### `api-endpoint`

Creates a REST API endpoint with handler, models, validation, tests, and docs.

#### `db-migration`

Creates a database migration with up/down scripts, validation, and rollback plan.

```yaml
name: db-migration
variables:
  table_name: { required: true }
  migration_type: { required: true, enum: [create-table, alter-table, add-index, seed-data] }
plan: |
  ## Create Database Migration: {{ migration_type }} on {{ table_name }}
  ### Step 1: Create migration file
  ### Step 2: Write up migration
  ### Step 3: Write down migration (rollback)
  ### Step 4: Test migration on clean database
  ### Step 5: Test rollback
  ### Step 6: Document migration in changelog
```

#### `react-component`

Creates a React component with props, state, styling, and tests.

#### `unit-test`

Generates unit tests for an existing module by analyzing its public API.

#### `bug-fix`

Structured bug fix workflow: reproduce → root cause → fix → test → document.

```yaml
name: bug-fix
variables:
  bug_description: { required: true }
  reproduction_steps: { required: false }
  affected_area: { required: false }
plan: |
  ## Bug Fix: {{ bug_description }}

  ### Step 1: Reproduce
  {% if reproduction_steps %}
  Follow these reproduction steps: {{ reproduction_steps }}
  {% else %}
  Identify and document reproduction steps.
  {% endif %}

  ### Step 2: Root Cause Analysis
  Trace the code path to identify the root cause.
  {% if affected_area %}
  Start in: {{ affected_area }}
  {% endif %}

  ### Step 3: Implement Fix
  Fix the root cause, not just the symptom.

  ### Step 4: Write Regression Test
  Create a test that would have caught this bug.

  ### Step 5: Verify Fix
  Run the reproduction steps and confirm the bug is fixed.
  Run the full test suite to check for regressions.

  ### Step 6: Document
  Document what caused the bug and how it was fixed.
```

---

## Integration with Existing Makima Features

### Supervisor Task Spawning

Recipes generate plans that are passed to `spawn-task`:

```rust
// Recipe execution
let plan = recipe.render_plan(&variables)?;
let task = spawn_task(SpawnTaskRequest {
    task_name: format!("{} ({})", recipe.name, variables.get("primary_var")),
    plan,
    // ... other params from context
})?;
```

### Contract Files

Recipe definitions can be stored as contract files for versioning:

```rust
File {
    contract_id: None, // Global, not contract-specific
    name: "Recipe: api-endpoint",
    body: vec![
        BodyElement::Code { language: Some("yaml"), content: recipe_yaml },
    ],
}
```

### Workflow Presets

Recipes and presets are complementary:
- **Presets** define the high-level workflow (which phases, what triggers)
- **Recipes** define the low-level task plans (what each task does)

A preset can reference recipes:

```yaml
# In a preset
phases:
  execute:
    recipe: api-endpoint    # Use the api-endpoint recipe for this phase's tasks
    recipe_vars:
      endpoint_name: "{{ task_description }}"
```

### Knowledge Accumulation

Recipes can be **evolved** based on learnings:
- When compound learning captures a pattern, check if it maps to an existing recipe
- If so, suggest recipe improvements
- If not, suggest creating a new recipe

### Directive System

For directive-based workflows, recipes can be used as task plan sources:

```rust
DirectiveStep {
    name: "create-users-endpoint",
    task_plan: recipe.render_plan(&variables)?,  // Generated from recipe
    // ...
}
```

---

## Implementation Plan

### Phase 1: Core Recipe System (3-4 days)

| Task | Effort | Description |
|------|--------|-------------|
| Recipe YAML schema | 0.5 days | Define format, validation rules |
| YAML parser with Jinja-like templating | 1 day | Variable substitution, conditionals |
| `recipe list` command | 0.5 days | Discover and list recipes |
| `recipe run` command | 1 day | Parse, validate, render, spawn task |
| `recipe preview` command | 0.5 days | Dry-run display |

### Phase 2: Recipe Management (2-3 days)

| Task | Effort | Description |
|------|--------|-------------|
| Multi-level discovery | 0.5 days | Built-in, repo, user resolution |
| `recipe create` command | 1 day | Create from scratch or from task |
| `recipe validate` command | 0.5 days | YAML validation, variable check |
| Built-in recipe definitions | 1 day | Write 5 default recipes |

### Phase 3: Meta-Commands (3-5 days)

| Task | Effort | Description |
|------|--------|-------------|
| `recipe generate` | 1.5 days | Pattern detection from task history |
| `recipe heal` | 1 day | Failure analysis and auto-fix |
| `recipe evolve` | 1 day | Improve recipes from findings/learnings |
| Recipe versioning | 0.5 days | Version tracking, deprecation |
| Documentation | 0.5 days | User guide, recipe authoring guide |

---

## Configuration Examples

### Running a Recipe

```bash
# Simple usage
makima recipe run api-endpoint \
  --var endpoint_name=orders \
  --var http_method=POST \
  --var resource_name=Order \
  --var requires_auth=true \
  --var database_table=orders

# This spawns a task with the rendered plan:
# "## Task: Create POST /api/orders Endpoint
#  ### Step 1: Define Route
#  Add the POST /api/orders route to the router.
#  Apply authentication middleware to this route.
#  ..."
```

### Creating a Recipe from a Completed Task

```bash
# After completing a successful task
makima recipe create --from-task abc-123 --name "graphql-resolver"

# Analyzes the task's plan and execution to generate:
# .makima/recipes/graphql-resolver.yaml
# with variables extracted from repeated patterns
```

### Recipe with Validation

```yaml
# .makima/recipes/react-component.yaml
name: react-component
variables:
  component_name:
    required: true
    validation: "^[A-Z][a-zA-Z]*$"  # PascalCase
  use_typescript:
    required: false
    default: true
  include_tests:
    required: false
    default: true
  styling:
    required: false
    enum: [css-modules, styled-components, tailwind]
    default: css-modules

validation:
  - check: "file_exists"
    path: "src/components"
    message: "Components directory must exist"
  - check: "not_exists"
    path: "src/components/{{ component_name }}"
    message: "Component {{ component_name }} already exists"

plan: |
  ## Create React Component: {{ component_name }}

  ### Step 1: Component File
  Create `src/components/{{ component_name }}/{{ component_name }}.{{ 'tsx' if use_typescript else 'jsx' }}`
  with the component skeleton.

  ### Step 2: Styling
  {% if styling == 'css-modules' %}
  Create `{{ component_name }}.module.css` with base styles.
  {% elif styling == 'styled-components' %}
  Create styled components in the component file.
  {% elif styling == 'tailwind' %}
  Use Tailwind CSS classes directly in the component.
  {% endif %}

  {% if include_tests %}
  ### Step 3: Tests
  Create `{{ component_name }}.test.{{ 'tsx' if use_typescript else 'jsx' }}`
  with tests for rendering, props, and user interactions.
  {% endif %}

  ### Step {{ '4' if include_tests else '3' }}: Export
  Add {{ component_name }} to the components index file.

outputs:
  files:
    - "src/components/{{ component_name }}/{{ component_name }}.{{ 'tsx' if use_typescript else 'jsx' }}"
    - "src/components/{{ component_name }}/index.{{ 'ts' if use_typescript else 'js' }}"
```

---

## Open Questions

1. **Templating language**: Should we use a full Jinja2-like syntax or a simpler `{{ variable }}` substitution? Jinja adds power but complexity.
2. **Recipe dependencies**: Can recipes depend on other recipes? (e.g., "api-endpoint requires db-migration to have run first")
3. **Recipe testing**: How do you test that a recipe produces valid plans? Should recipes have test cases?
4. **Recipe marketplace**: Should there be a community registry for sharing recipes?
5. **Pattern detection**: How sophisticated should `recipe generate` be? Simple plan comparison, or full semantic analysis?
6. **Recipe scope**: Should recipes generate just plans, or also pre-create file scaffolding (like code generators)?
7. **Backwards compatibility**: When a recipe is updated, what happens to tasks that were created with the old version?

---

## Alternatives Considered

| Alternative | Pros | Cons | Decision |
|-------------|------|------|----------|
| Plan library (copy-paste) | Simple | No variables, no validation | Rejected — not reusable enough |
| Code generators (scaffolding) | Creates actual files | Over-prescriptive; doesn't handle logic | Complement — recipes can reference generators |
| LLM-only planning | Maximum flexibility | Inconsistent; no standardization | Current state — recipes improve on this |
| Cookiecutter-style templates | Familiar | Wrong level (project-level vs task-level) | Rejected — different abstraction |
| Hardcoded task types | Fast | Not extensible; limited variety | Rejected — need flexibility |

---

## Priority & Complexity Assessment

- **Priority: MEDIUM** — Task templates improve consistency and speed but aren't required for makima to function. They become increasingly valuable as the system is used more (patterns emerge).
- **Complexity: MEDIUM** — YAML parsing and variable substitution are straightforward. Meta-commands (generate, heal, evolve) require sophisticated analysis of task history and are the main complexity drivers.
- **Risk: LOW-MEDIUM** — Core recipe system is low risk. Meta-commands (auto-generation, healing) involve AI-driven analysis that may produce variable quality. Mitigated by requiring human approval before applying changes.