feat: add recipe composition with run_recipe tool and dev-sprint consumer

[Trecek]

Summary

This PR implements recipe composition for AutoSkillit, enabling recipes to invoke other recipes as sub-steps via a new run_recipe MCP tool. The execution layer adds run_subrecipe_session() and supporting prompt/command builders, wired into the server with a rules_recipe.py validation rule that catches references to unknown sub-recipes at load time. A new dev-sprint bundled recipe serves as the first consumer, orchestrating a full development sprint by composing triage, implementation, and PR creation phases through recipe composition.

Individual Group Plans

Group 1: Recipe Composition — Core Execution Layer

Establish the core execution layer for recipe composition: adds run_recipe to GATED_TOOLS, introduces build_subrecipe_cmd() and build_subrecipe_prompt() in execution/commands.py, and adds run_subrecipe_session() to execution/headless.py. Sub-recipe sessions set AUTOSKILLIT_KITCHEN_OPEN=1 to pre-open the kitchen gate without calling open_kitchen.

Group 2: Recipe Composition — Validation + Server Tool

Adds the run_recipe MCP tool handler and its validation infrastructure. Introduces ValidationContext.available_recipes, a new rules_recipe.py file with the unknown-sub-recipe ERROR rule, and updates _build_orchestrator_prompt() so parent orchestrators know how to handle tool: run_recipe steps.

Group 3: Dev-Sprint Recipe (Recipe Composition Consumer)

Creates the dev-sprint bundled recipe as the first consumer of recipe composition. Automates a full development sprint: triage open issues → run_recipe implementation-groups (sub-recipe) → create integration PR.

Architecture Impact

Process Flow Diagram

%%{init: {'flowchart': {'nodeSpacing': 40, 'rankSpacing': 50, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;

    START([Parent orchestrator<br/>tool: run_recipe step])
    END_OK([SkillResult success=true])
    END_FAIL([SkillResult success=false])

    subgraph RuntimePath ["Runtime Execution Path"]
        direction TB

        subgraph EntryGate ["Entry & Gate Check"]
            ToolHandler["● run_recipe MCP tool<br/>━━━━━━━━━━<br/>tools_recipe.py<br/>+ helpers.py bridges"]
            GateCheck{"Kitchen gate<br/>enabled?"}
        end

        subgraph Resolution ["Recipe Resolution"]
            FindRecipe["● find_recipe_by_name<br/>━━━━━━━━━━<br/>recipe.io<br/>project → bundled fallback"]
            RecipeFound{"Recipe<br/>found?"}
        end

        subgraph SessionBuild ["Sub-Session Build"]
            BuildPrompt["● build_subrecipe_prompt<br/>━━━━━━━━━━<br/>commands.py<br/>pre-supplied ingredients +<br/>routing rules + YAML fences"]
            BuildCmd["● build_subrecipe_cmd<br/>━━━━━━━━━━<br/>commands.py<br/>AUTOSKILLIT_KITCHEN_OPEN=1<br/>(NOT HEADLESS)"]
            Runner["● run_subrecipe_session<br/>━━━━━━━━━━<br/>headless.py<br/>subprocess runner + timing<br/>+ token recording"]
        end

        subgraph SubSession ["Sub-Orchestrator Session"]
            direction LR
            KitchenOpen["● MCP init<br/>━━━━━━━━━━<br/>KITCHEN_OPEN=1<br/>gate.enable() +<br/>mcp.enable(kitchen)"]
            ExecSteps["Execute recipe steps<br/>━━━━━━━━━━<br/>no AskUserQuestion<br/>ingredients pre-supplied"]
        end
    end

    subgraph ValidationPath ["Load-Time Validation Path (load_and_validate)"]
        direction TB
        ListRecipes["● list_recipes<br/>━━━━━━━━━━<br/>project + bundled<br/>→ known frozenset"]
        MakeCtx["● make_validation_context<br/>━━━━━━━━━━<br/>_analysis.py<br/>available_recipes=known"]
        RegistryEmpty{"available_recipes<br/>empty?"}
        TemplateRef{"name is<br/>template ref?"}
        NameKnown{"name in<br/>available_recipes?"}
        NewRule["★ unknown-sub-recipe rule<br/>━━━━━━━━━━<br/>rules_recipe.py<br/>ERROR severity"]
        ValidOK([No finding — passes])
        ValidERR([ERROR finding emitted])
    end

    %% RUNTIME FLOW %%
    START --> ToolHandler
    ToolHandler --> GateCheck
    GateCheck -->|"disabled"| END_FAIL
    GateCheck -->|"enabled"| FindRecipe
    FindRecipe --> RecipeFound
    RecipeFound -->|"not found"| END_FAIL
    RecipeFound -->|"found"| BuildPrompt
    BuildPrompt --> BuildCmd
    BuildCmd --> Runner
    Runner --> KitchenOpen
    KitchenOpen --> ExecSteps
    ExecSteps -->|"success"| END_OK
    ExecSteps -->|"failure"| END_FAIL

    %% VALIDATION FLOW %%
    ListRecipes --> MakeCtx
    MakeCtx --> NewRule
    NewRule --> RegistryEmpty
    RegistryEmpty -->|"yes — skip"| ValidOK
    RegistryEmpty -->|"no"| TemplateRef
    TemplateRef -->|"yes — skip"| ValidOK
    TemplateRef -->|"no"| NameKnown
    NameKnown -->|"known"| ValidOK
    NameKnown -->|"unknown"| ValidERR

    %% CLASS ASSIGNMENTS %%
    class START,END_OK,END_FAIL,ValidOK,ValidERR terminal;
    class GateCheck,RecipeFound,RegistryEmpty,TemplateRef,NameKnown detector;
    class ToolHandler,FindRecipe handler;
    class BuildPrompt,BuildCmd,Runner phase;
    class KitchenOpen,ExecSteps stateNode;
    class ListRecipes,MakeCtx handler;
    class NewRule newComponent;

Loading

Color Legend:

Color	Category	Description
Dark Blue	Terminal	Start, success, failure, and validation result states
Red	Detector	Decision/guard checks (gate, recipe found, validation conditions)
Orange	Handler	Processing nodes (tool handler, recipe resolution, list/context)
Purple	Phase	Session build steps (prompt, cmd, runner)
Teal	State	Sub-session MCP init and step execution
Green	New	★ unknown-sub-recipe rule — new in this PR

Module Dependency Diagram

%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 70, 'curve': 'basis'}}}%%
graph TB
    %% CLASS DEFINITIONS %%
    classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;

    subgraph L3 ["L3 — SERVER LAYER"]
        direction LR
        ToolsRecipe["● server/tools_recipe.py<br/>━━━━━━━━━━<br/>run_recipe MCP handler<br/>REQ-IMP-003: only core/<br/>pipeline/server imports"]
        Helpers["● server/helpers.py<br/>━━━━━━━━━━<br/>_find_recipe bridge<br/>_run_subrecipe bridge<br/>imports execution + recipe"]
    end

    subgraph L2 ["L2 — RECIPE LAYER"]
        direction LR
        RulesRecipe["★ recipe/rules_recipe.py<br/>━━━━━━━━━━<br/>unknown-sub-recipe rule<br/>@semantic_rule decorator"]
        Analysis["● recipe/_analysis.py<br/>━━━━━━━━━━<br/>ValidationContext<br/>+available_recipes field"]
        RecipeApi["● recipe/_api.py<br/>━━━━━━━━━━<br/>load_and_validate<br/>populates available_recipes"]
        RecipeInit["● recipe/__init__.py<br/>━━━━━━━━━━<br/>+find_recipe_by_name export<br/>+rules_recipe side-effect import"]
    end

    subgraph L1 ["L1 — EXECUTION LAYER"]
        direction LR
        Commands["● execution/commands.py<br/>━━━━━━━━━━<br/>+build_subrecipe_cmd<br/>+build_subrecipe_prompt"]
        Headless["● execution/headless.py<br/>━━━━━━━━━━<br/>+run_subrecipe_session<br/>uses env kwarg on runner"]
        ExecInit["● execution/__init__.py<br/>━━━━━━━━━━<br/>+build_subrecipe_cmd<br/>+build_subrecipe_prompt<br/>+run_subrecipe_session"]
    end

    subgraph L0 ["L0 — CORE LAYER"]
        direction LR
        CoreTypes["● core/types.py<br/>━━━━━━━━━━<br/>GATED_TOOLS += run_recipe<br/>SubprocessRunner (env kwarg)"]
        CorePublic["core/ (other)<br/>━━━━━━━━━━<br/>Severity, SkillResult,<br/>RetryReason, ClaudeFlags"]
    end

    %% L3 → L3 (intra-layer helpers bridge) %%
    ToolsRecipe -->|"calls _find_recipe<br/>_run_subrecipe"| Helpers

    %% L3 → L2 (helpers bridge → recipe) %%
    Helpers -->|"imports find_recipe_by_name"| RecipeInit

    %% L3 → L1 (helpers bridge → execution) %%
    Helpers -->|"imports run_subrecipe_session"| ExecInit

    %% L2 intra-layer %%
    RulesRecipe -->|"imports ValidationContext"| Analysis
    RecipeApi -->|"imports make_validation_context"| Analysis
    RecipeInit -->|"side-effect import"| RulesRecipe

    %% L2 → L0 %%
    RulesRecipe -->|"imports Severity"| CorePublic
    Analysis -->|"imports SKILL_TOOLS"| CorePublic
    RecipeApi -->|"imports pkg_root, load_yaml"| CorePublic

    %% L1 intra-layer %%
    Headless -->|"imports build_subrecipe_cmd<br/>build_subrecipe_prompt"| Commands
    ExecInit -->|"re-exports"| Headless
    ExecInit -->|"re-exports"| Commands

    %% L1 → L0 %%
    Commands -->|"imports ClaudeFlags, pkg_root"| CorePublic
    Headless -->|"imports SkillResult, RetryReason"| CorePublic
    CoreTypes -.->|"part of core"| CorePublic

    %% CLASS ASSIGNMENTS %%
    class ToolsRecipe cli;
    class Helpers stateNode;
    class RulesRecipe newComponent;
    class Analysis,RecipeApi,RecipeInit phase;
    class Commands,Headless,ExecInit handler;
    class CoreTypes,CorePublic output;

Loading

Color Legend:

Color	Category	Description
Dark Blue	Server Tools	L3 tool handler (REQ-IMP-003 restricted)
Teal	Bridge Module	server/helpers.py — architecture-compliance bridge
Green	New	★ rules_recipe.py — new file added by this PR
Purple	Recipe Layer	L2 recipe modules — analysis, API, init
Orange	Execution Layer	L1 execution modules — commands, headless, init
Dark Teal	Core Layer	L0 foundation — types, public surface

Closes #303

Implementation Plan

Plan files:

• /home/talon/projects/autoskillit-runs/impl-303-20260310-073832-454193/temp/make-plan/recipe_composition_plan_2026-03-10_part_a.md
• /home/talon/projects/autoskillit-runs/impl-303-20260310-073832-454193/temp/make-plan/recipe_composition_plan_2026-03-10_part_b.md
• /home/talon/projects/autoskillit-runs/impl-303-20260310-073832-454193/temp/make-plan/recipe_composition_plan_2026-03-10_part_c.md

Token Usage Summary

Token Summary

implement

• input_tokens: 20305
• output_tokens: 537078
• cache_creation_input_tokens: 1621507
• cache_read_input_tokens: 103595580
• invocation_count: 17

audit_impl

• input_tokens: 9681
• output_tokens: 144617
• cache_creation_input_tokens: 563252
• cache_read_input_tokens: 4118056
• invocation_count: 14

open_pr

• input_tokens: 2269
• output_tokens: 172827
• cache_creation_input_tokens: 544287
• cache_read_input_tokens: 9113477
• invocation_count: 9

retry_worktree

• input_tokens: 45
• output_tokens: 22321
• cache_creation_input_tokens: 111687
• cache_read_input_tokens: 3405410
• invocation_count: 1

make_plan

• input_tokens: 44
• output_tokens: 69854
• cache_creation_input_tokens: 121021
• cache_read_input_tokens: 2735054
• invocation_count: 1

review_pr

• input_tokens: 8787
• output_tokens: 383468
• cache_creation_input_tokens: 801892
• cache_read_input_tokens: 10830228
• invocation_count: 12

dry_walkthrough

• input_tokens: 57
• output_tokens: 30444
• cache_creation_input_tokens: 114452
• cache_read_input_tokens: 1679519
• invocation_count: 3

resolve_review

• input_tokens: 669
• output_tokens: 349584
• cache_creation_input_tokens: 838303
• cache_read_input_tokens: 38375492
• invocation_count: 12

fix

• input_tokens: 356
• output_tokens: 132867
• cache_creation_input_tokens: 480031
• cache_read_input_tokens: 21980041
• invocation_count: 7

investigate

• input_tokens: 2053
• output_tokens: 12607
• cache_creation_input_tokens: 52059
• cache_read_input_tokens: 382017
• invocation_count: 1

rectify

• input_tokens: 4616
• output_tokens: 21997
• cache_creation_input_tokens: 75946
• cache_read_input_tokens: 854207
• invocation_count: 1

open_pr_step

• input_tokens: 52
• output_tokens: 27985
• cache_creation_input_tokens: 102646
• cache_read_input_tokens: 1871801
• invocation_count: 2

analyze_prs

• input_tokens: 13
• output_tokens: 18525
• cache_creation_input_tokens: 55984
• cache_read_input_tokens: 358201
• invocation_count: 1

merge_pr

• input_tokens: 54
• output_tokens: 11011
• cache_creation_input_tokens: 124523
• cache_read_input_tokens: 1156759
• invocation_count: 4

create_review_pr

• input_tokens: 35
• output_tokens: 17881
• cache_creation_input_tokens: 52674
• cache_read_input_tokens: 1060679
• invocation_count: 1

plan

• input_tokens: 6248
• output_tokens: 238067
• cache_creation_input_tokens: 765044
• cache_read_input_tokens: 9628970
• invocation_count: 9

verify

• input_tokens: 2305
• output_tokens: 144281
• cache_creation_input_tokens: 598389
• cache_read_input_tokens: 7105068
• invocation_count: 11

🤖 Generated with Claude Code via AutoSkillit

[Trecek]

AutoSkillit PR Review — Verdict: changes_requested

9 blocking issues found (4 critical, 5 warning). See inline comments.

[Trecek]

[critical] bugs: Duplicate @mcp.tool registration: run_recipe is registered as a stub here AND as a real implementation in tools_recipe.py. FastMCP will conflict at registration time — one shadows the other or the server fails to start. Remove this stub function entirely from tools_execution.py.

[Trecek]

[critical] bugs: If runner() raises an exception, _result remains None. The finally block logs correctly, but post-finally code unconditionally calls dataclasses.replace(_result, ...) which raises TypeError(None), losing the original exception. Move post-processing into the try block or guard with if _result is not None and re-raise.

[Trecek]

[critical] arch: Conflicting @mcp.tool registration — a stub with the same tool name run_recipe exists in tools_execution.py. Remove the stub in tools_execution.py; this real implementation here is correct.

[Trecek]

[critical] cohesion: build_subrecipe_prompt belongs in cli/_prompts.py alongside _build_orchestrator_prompt, not in commands.py. commands.py is a pure command-builder (no filesystem I/O). This function reads the filesystem via pkg_root() and builds a multi-line prompt string — it is prompt-building logic. Move it to cli/_prompts.py.

[Trecek]

[warning] slop: Stale hardcoded stub error run_recipe is not yet implemented (Part B). The real implementation already exists in tools_recipe.py. Remove this entire run_recipe function from tools_execution.py.

[Trecek]

[warning] tests: test_ds3_no_semantic_errors is trivially satisfied — calling run_semantic_rules(recipe) without available_recipes causes unknown-sub-recipe to return [] by safe-fallback design. This test cannot detect a misspelled sub-recipe name in dev-sprint. Pass available_recipes with all bundled recipe names to actually exercise the rule.

[Trecek]

[warning] defense: JSONDecodeError is silently swallowed with no logging. A caller passing malformed ingredients_json silently runs the sub-recipe with no ingredients. Add logger.warning() with the error and original input before falling back to {}.

[Trecek]

[warning] defense: recipe_info.path.read_text() called without error handling. An unreadable recipe file (deleted, permissions error) raises an unhandled OSError that propagates through the MCP tool handler instead of a structured SkillResult error. Wrap in try/except OSError and return SkillResult(is_error=True).

[Trecek]

[warning] defense: cwd (str) is passed to runner with no existence check. An invalid or non-existent cwd produces an opaque subprocess error. Validate Path(cwd).is_dir() early and return a descriptive SkillResult error before launching the subprocess.

[Trecek]

AutoSkillit review found 9 blocking issues (4 critical, 5 warning). See inline comments for details.

Critical issues:

1. Duplicate @mcp.tool registration: run_recipe stub in tools_execution.py conflicts with real implementation in tools_recipe.py — FastMCP will conflict at startup.
2. _result None dereference after runner() exception in run_subrecipe_session — TypeError will mask the original exception.
3. build_subrecipe_prompt placed in commands.py (pure command builder) but it reads filesystem and builds prompts — belongs in cli/_prompts.py.

Warning issues:

• Stale stub error message in tools_execution.py (remove the function)
• test_ds3_no_semantic_errors trivially passes — safe-fallback silences the rule under test
• Silent JSONDecodeError swallowing in build_subrecipe_prompt
• Unhandled OSError from recipe_info.path.read_text() in run_recipe tool
• No cwd validation before subprocess launch in run_subrecipe_session

Resolve these before merging.

[Trecek]

Collapsed into integration PR #323 (#323)