# 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.
