diff options
Diffstat (limited to 'docs/proposals/feature-task-templates.md')
| -rw-r--r-- | docs/proposals/feature-task-templates.md | 602 |
1 files changed, 602 insertions, 0 deletions
diff --git a/docs/proposals/feature-task-templates.md b/docs/proposals/feature-task-templates.md new file mode 100644 index 0000000..98abde9 --- /dev/null +++ b/docs/proposals/feature-task-templates.md @@ -0,0 +1,602 @@ +# 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. |