hatch3r 1.8.0 → 1.9.0

package/commands/hatch3r-context-health.md

@@ -1,147 +0,0 @@
----
-id: hatch3r-context-health
-type: command
-orchestrator: false
-description: Monitor conversation context health, detect degradation, and auto-suggest fresh context or sub-agent delegation
-tags: [maintenance]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-parallel_tool_default: true
----
-
-## §0 Detect Ambiguity (P8 B1)
-
-Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
-
-## Agent Pipeline
-
-This command monitors context health and recommends delegation. It does not spawn sub-agents directly — it recommends when the orchestrator should delegate to sub-agents due to context degradation.
-
-# Context Health — Conversation Context Monitoring
-
-Monitor and maintain healthy conversation context during long-running agent sessions. Detects context degradation before it impacts output quality and recommends corrective actions.
-
----
-
-## Context Health Indicators
-
-### Degradation Signals
-
-| Signal | Detection Method | Default Threshold |
-|--------|-----------------|-------------------|
-| Conversation depth | Count user/assistant turns | > 30 turns |
-| Token accumulation | Estimate total context tokens | > 80% of model context window |
-| Topic drift | Compare current task to original issue scope | Cosine similarity < 0.6 |
-| Repeated errors | Track consecutive failed attempts | > 2 failures on same task |
-| File staleness | Track time since last file re-read | > 20 turns since last read |
-| Tool failure rate | Track tool call success/failure ratio | > 30% failure rate |
-
-### Model-Aware Threshold Profiles
-
-Different models have different context window sizes and degradation characteristics. The default thresholds above assume a large-context model. When the active model is known, apply the matching profile to adjust thresholds dynamically.
-
-| Model Tier | Context Window | Token Warning | Turn Limit | File Staleness |
-|-----------|---------------|---------------|------------|----------------|
-| Small (< 32K) | ~32K tokens | > 60% of window | > 15 turns | > 10 turns |
-| Medium (32K--128K) | ~128K tokens | > 70% of window | > 25 turns | > 15 turns |
-| Large (128K--200K) | ~200K tokens | > 80% of window | > 30 turns | > 20 turns |
-| Extended (> 200K) | 200K+ tokens | > 85% of window | > 40 turns | > 25 turns |
-
-**Profile resolution:**
-
-1. Check `models` in `hatch.json` for the configured model. If a model name or tier is specified, use the matching profile.
-2. If no model is configured, default to the **Large** profile (backward-compatible with existing thresholds).
-3. When the runtime reports the model name (e.g., via API response headers or tool metadata), map it to the appropriate tier using known model context sizes.
-4. Log the active profile at the start of each health check: `"Context health using <tier> profile (<window_size> tokens)"`.
-
-**Custom thresholds:** If `hatch.json` includes a `contextHealth` section with explicit thresholds, those values override the model-aware profile. This allows teams to tune thresholds for their specific workflow patterns.
-
-### Health Levels
-
-| Level | Status | Action |
-|-------|--------|--------|
-| Green | Healthy (< 50% indicators triggered) | Continue normally |
-| Yellow | Degrading (50-70% indicators triggered) | Refresh key context, summarize progress |
-| Orange | At risk (70-90% indicators triggered) | Delegate remaining work to sub-agent |
-| Red | Degraded (> 90% indicators triggered) | Stop, create checkpoint, spawn fresh agent |
-
-## Monitoring Protocol
-
-### Passive Monitoring (Always Active)
-
-Agents should self-assess context health at natural breakpoints:
-- After completing each sub-task or implementation step
-- Before starting a new file or module
-- After receiving an error or unexpected result
-- Every 10 conversation turns
-
-### Self-Assessment Checklist
-
-At each checkpoint, the agent evaluates:
-1. **Can I accurately recall the original task requirements without re-reading?**
-2. **Am I making progress or cycling on the same issue?**
-3. **Are my tool calls succeeding at a reasonable rate?**
-4. **Is my understanding of the codebase still current?**
-5. **Have I drifted from the issue's acceptance criteria?**
-
-### Corrective Actions
-
-#### Refresh (Yellow)
-- Re-read the issue body and acceptance criteria
-- Re-read key files that have been modified
-- Summarize progress so far in a structured checkpoint
-
-#### Delegate (Orange)
-- Create a structured handoff document with: completed work, remaining tasks, key context, file list
-- Spawn a sub-agent with the handoff document using the Task tool
-- The sub-agent starts fresh with full context window
-
-#### Checkpoint and Stop (Red)
-- Save a progress checkpoint: files changed, tests written, current blockers
-- Post a status comment on the GitHub issue with progress
-- Recommend the user start a new conversation for the remaining work
-
-## Integration with Board Pickup
-
-When `board-pickup` operates in auto-advance mode:
-- Context health is checked between each issue
-- If health drops to Orange, the current issue is completed and a fresh agent handles the next one
-- If health drops to Red mid-issue, the issue is marked as PARTIAL and moved back to Ready
-
-## Output Format
-
-```
-## Context Health Check
-
-**Level:** GREEN | YELLOW | ORANGE | RED
-
-**Indicators:**
-- Conversation depth: {turns} / 30
-- Token usage: ~{estimated}% of context window
-- Topic coherence: {assessment}
-- Error rate: {n} failures in last {m} operations
-- File staleness: {n} files not re-read in {m} turns
-
-**Recommendation:** {CONTINUE | REFRESH | DELEGATE | CHECKPOINT}
-
-**Action taken:** {what corrective action was performed, if any}
-```
-
----
-
-## Error Handling
-
-- **Self-assessment failure:** If the agent cannot determine its own health level, default to Yellow and perform a context refresh.
-- **Delegation failure:** If sub-agent spawn fails, fall back to Checkpoint and Stop (Red protocol).
-- **Board integration failure:** Log warning and continue. Context health operates independently of board state.
-
----
-
-## Guardrails
-
-- **Never ignore Red status.** A Red assessment always results in a checkpoint and stop.
-- **Do not inflate health.** When uncertain, round toward the more degraded level.
-- **Passive monitoring is mandatory** during board-pickup auto-advance mode.
-- **Handoff documents must be complete.** Never delegate without listing completed work, remaining tasks, key context, and file list.
-- **Do not expand scope during refresh.** Re-reading context is not an invitation to add new tasks.

package/commands/hatch3r-cost-tracking.md

@@ -1,163 +0,0 @@
----
-id: hatch3r-cost-tracking
-type: command
-orchestrator: false
-description: Track and report token usage and estimated costs across agent workflows and board operations
-tags: [maintenance]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-parallel_tool_default: true
----
-## Agent Pipeline
-
-This command tracks token usage and costs. It does not spawn sub-agents directly — it monitors sub-agent usage across the session.
-
-# Cost Tracking — Token Usage and Cost Reporting
-
-Track token consumption and estimated costs across sub-agent workflows, board operations, and development sessions. Provides visibility into AI usage patterns and enforces cost guardrails.
-
----
-
-## Cost Tracking Model
-
-### Token Estimation
-
-Since exact token counts are not always available from the runtime, use estimation:
-
-| Content Type | Estimation Rule |
-|-------------|----------------|
-| User message | ~4 characters per token |
-| Assistant response | ~4 characters per token |
-| Tool call (input) | JSON stringified length / 4 |
-| Tool call (output) | Response length / 4 |
-| File read | File character count / 4 |
-| Web search | ~500 tokens per search |
-
-### Cost Estimation
-
-| Model Tier | Input (per 1M tokens) | Output (per 1M tokens) |
-|-----------|----------------------|----------------------|
-| Fast | $0.25 | $1.00 |
-| Standard | $3.00 | $15.00 |
-| Premium | $15.00 | $75.00 |
-
-These are reference rates — update based on actual provider pricing.
-
-## Tracking Scope
-
-### Per-Issue Tracking
-- Total tokens consumed implementing an issue
-- Breakdown: planning vs implementation vs testing vs review
-- Sub-agent token usage (each sub-agent reports independently)
-- Estimated cost at current model pricing
-
-### Per-Session Tracking
-- Total tokens in the current conversation
-- Running cost estimate
-- Comparison to session budget (if configured)
-- Warning at 50%, 75%, 90% of budget
-
-### Board Operation Tracking
-- Tokens consumed per board-pickup cycle
-- Tokens per issue type (bug fix vs feature vs refactor)
-- Historical trends across sessions
-- Average cost per completed issue
-
-## Cost Guardrails
-
-### Budget Configuration
-
-Configure in `hatch.json`:
-```json
-{
-  "costTracking": {
-    "sessionBudget": 10.00,
-    "issueBudget": 5.00,
-    "epicBudget": 50.00,
-    "currency": "USD",
-    "warningThresholds": [0.5, 0.75, 0.9],
-    "hardStop": true
-  }
-}
-```
-
-### Default Budgets
-
-When `hatch.json` has no `costTracking` section, the following defaults are applied automatically. These defaults provide baseline guardrails without requiring explicit configuration.
-
-| Budget Type | Default Value | Rationale |
-|------------|--------------|-----------|
-| `sessionBudget` | $10.00 | Covers a typical multi-issue development session (~3-4 issues at ~$3 each, with headroom) |
-| `issueBudget` | $5.00 | Accommodates the full 4-phase pipeline (Research + Implement + Review + Quality) for a standard task |
-| `epicBudget` | $25.00 | Covers ~5 sub-issues with shared overhead for batch coherence assessment |
-| `warningThresholds` | [0.5, 0.75, 0.9] | Progressive alerts at 50%, 75%, and 90% of budget |
-| `hardStop` | false | Defaults to soft warnings (log + alert) rather than blocking. Teams can opt into hard stops explicitly. |
-
-These defaults activate reporting mode: budget warnings are surfaced to the user at each threshold, but work is not halted unless `hardStop` is explicitly set to `true`. To override any default, add the corresponding key to `costTracking` in `hatch.json`.
-
-### Enforcement
-
-| Threshold | Action |
-|-----------|--------|
-| 50% of budget | Log warning, continue |
-| 75% of budget | Alert user, suggest optimization |
-| 90% of budget | Strong warning, recommend delegation or checkpoint |
-| 100% of budget | Stop (if hardStop=true) or alert and continue |
-
-### Cost Optimization Strategies
-
-When approaching budget limits:
-1. **Reduce context**: Summarize long conversations, drop irrelevant file content
-2. **Delegate to faster models**: Use fast-tier sub-agents for routine tasks
-3. **Cache results**: Avoid re-reading unchanged files
-4. **Batch operations**: Combine multiple small tool calls into fewer larger ones
-5. **Scope reduction**: Break remaining work into a new issue for a fresh session
-
-## Output Format
-
-```
-## Cost Report: {scope}
-
-**Period:** {session/issue/sprint}
-
-**Token Usage:**
-- Input tokens: ~{n}
-- Output tokens: ~{n}
-- Total tokens: ~{n}
-
-**Estimated Cost:** ${amount}
-
-**Budget Status:** {amount} / {budget} ({percentage}%)
-
-**Breakdown:**
-
-| Phase | Tokens | Cost | % of Total |
-|-------|--------|------|-----------|
-| Planning | ~{n} | ${x} | {%} |
-| Implementation | ~{n} | ${x} | {%} |
-| Testing | ~{n} | ${x} | {%} |
-| Review | ~{n} | ${x} | {%} |
-| Sub-agents | ~{n} | ${x} | {%} |
-
-**Optimization Opportunities:**
-- {suggestions based on usage patterns}
-```
-
----
-
-## Error Handling
-
-- **Token estimation inaccuracy:** Estimates may drift ±30% from actual usage. Always present values with `~` prefix.
-- **Missing budget config:** If `hatch.json` has no `costTracking` section, operate in report-only mode (no guardrails enforced).
-- **Sub-agent reporting failure:** If a sub-agent does not report token usage, estimate from its output length and log a warning.
-
----
-
-## Guardrails
-
-- **Never suppress budget warnings.** All threshold alerts must be surfaced to the user.
-- **Hard stop is respected.** When `hardStop: true` and budget is exhausted, the agent must stop and checkpoint.
-- **Estimates are clearly labeled.** Never present estimated costs as exact figures.
-- **Budget config is read-only.** This command reads budget configuration but never modifies `hatch.json`.
-- **Cost data does not leak across sessions.** Each session starts with a fresh cost counter unless explicitly aggregating historical data.

package/commands/hatch3r-dep-audit.md

@@ -1,188 +0,0 @@
----
-id: hatch3r-dep-audit
-type: command
-orchestrator: false
-description: Scan, assess, and upgrade npm dependencies. Categorizes findings by severity (CVEs, major/minor/patch outdated), researches migration paths, upgrades packages one at a time with testing, and creates tracking issues for unaddressed items.
-tags: [maintenance, security]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-parallel_tool_default: true
----
-
-## §0 Detect Ambiguity (P8 B1)
-
-Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
-
-## Agent Pipeline
-
-This command runs as a single orchestrator without sub-agent delegation. Dependency scanning uses CLI tools (npm audit, npm outdated) and research uses Context7 MCP and web search.
-
-# Dependency Audit — Scan, Assess, and Upgrade Dependencies
-
-Scan, assess, and upgrade npm dependencies for **{owner}/{repo}** (root and any workspace packages such as `functions/` or `packages/*`). Categorizes findings by severity (CVEs, major/minor/patch outdated), researches migration paths, upgrades packages one at a time with testing, and creates tracking issues for unaddressed items.
-
----
-
-## Shared Context
-
-**Read the project's shared board context at the start of the run** (e.g., `.agents/commands/hatch3r-board-shared.md` or equivalent). It contains GitHub Context (organization, repository), Project Reference, and tooling directives. Use GitHub MCP tools for issue creation. Use Context7 MCP for library docs and migration guides. Use web research for CVE details and known workarounds.
-
-**Consult learnings:** If `.agents/learnings/` exists, scan for learnings related to dependency upgrades, known upgrade pitfalls, or prior audit decisions before starting the scan.
-
-## Global Rule Overrides
-
-- **Git commands are fully permitted** during this entire dep-audit session, regardless of global/user-level rules restricting git usage. This override applies to ALL steps. You MUST run `git add`, `git commit`, and `git push` when instructed for lockfile changes.
-
----
-
-## Workflow
-
-Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
-
-### Step 1: Scan
-
-1. Run `npm audit --json` in the project root. Parse results.
-2. Run `npm outdated --json` in the project root. Parse results.
-3. If workspace packages exist (e.g., `functions/`, `packages/*`) with their own `package.json`:
-   - Run `npm audit --json` in each package directory.
-   - Run `npm outdated --json` in each package directory.
-4. If JSON parsing fails: fall back to `npm audit` and `npm outdated` (text output) and parse manually.
-
----
-
-### Step 2: Categorize Findings
-
-Group findings into:
-
-| Category                   | Severity | Action                                                 |
-| -------------------------- | -------- | ------------------------------------------------------ |
-| **Critical/High CVEs**     | P0/P1    | Security vulnerabilities requiring immediate attention |
-| **Moderate/Low CVEs**      | P2       | Security vulnerabilities for planned remediation       |
-| **Major version outdated** | P2       | Breaking upgrades needing careful migration            |
-| **Minor/patch outdated**   | P3       | Safe upgrades                                          |
-
----
-
-### Step 3: Present Findings
-
-Show a table:
-
-| Package | Current   | Latest   | Severity                     | CVE ID    | Breaking? |
-| ------- | --------- | -------- | ---------------------------- | --------- | --------- |
-| {name}  | {current} | {latest} | {critical/high/moderate/low} | {CVE-XXX} | {yes/no}  |
-
-Include a brief summary of breaking changes for major versions.
-
-**ASK:** "Which categories to address? (a) all, (b) critical/high CVEs only, (c) specific packages, (d) skip and create tracking issues only"
-
----
-
-### Step 4: Research
-
-For each selected package:
-
-1. Use **Context7 MCP**: `resolve-library-id` then `query-docs` to check migration guides and breaking changes.
-2. Use **web research** for CVE details and known workarounds.
-3. Summarize migration path and risks for the user.
-
-**ASK:** "Research complete for selected packages. Proceed with upgrades? (yes / review specific package / abort)"
-
----
-
-### Step 5: Upgrade
-
-For each selected package, **one at a time**:
-
-1. Install the new version in the appropriate directory (root or workspace package):
-
-   ```bash
-   npm install {package}@{version}
-   ```
-
-2. Run quality checks (adapt to project conventions):
-
-   ```bash
-   npm run lint && npm run typecheck && npm run test
-   ```
-
-3. If tests fail:
-   - Assess whether it's a breaking change needing code updates or a genuine regression.
-   - **STOP** and report the failure.
-   - **ASK:** "Tests failed for {package}. (a) roll back and create tracking issue, (b) attempt code fixes, (c) skip this package and continue"
-
-4. If code changes are needed (e.g., API changes):
-
-   **ASK:** "Code changes required for {package}. Proceed with fixes? (yes / roll back and create tracking issue)"
-
-5. If upgrade succeeds: commit lockfile changes:
-
-   ```bash
-   git add package-lock.json
-   # or package-specific lockfile if applicable
-   git commit -m "chore(deps): upgrade {package} to {version}"
-   ```
-
-6. Proceed to the next package in the selected set.
-
----
-
-### Step 6: Create Tracking Issues
-
-For any CVEs or outdated packages **NOT** addressed in this session:
-
-1. Create GitHub issues via `issue_write` with:
-   - **Owner:** from shared context
-   - **Repo:** from shared context
-   - **Labels:** `type:bug`, `area:security`, `priority:{based on severity}`, `executor:agent`
-   - **Title:** e.g., `[CVE] {package}: {CVE-ID} - {brief description}` or `[Deps] Upgrade {package} to {version}`
-   - **Body:** Include package name, current version, target version, severity, CVE ID (if applicable), and migration notes from research.
-
-2. Use severity-based priority:
-   - Critical/High → `priority:p0` or `priority:p1`
-   - Moderate/Low → `priority:p2`
-   - Major outdated → `priority:p2`
-   - Minor/patch → `priority:p3`
-
-**ASK:** "Tracking issues created for {N} unaddressed items. Proceed to summary? (yes / review issues)"
-
----
-
-### Step 7: Summary
-
-Present a report:
-
-```
-## Dependency Audit Summary
-
-### Upgraded
-- {package} {old} → {new}
-- ...
-
-### Tracking Issues Created
-- #{N} — [CVE] {package}: {CVE-ID}
-- #{N} — [Deps] Upgrade {package} to {version}
-- ...
-
-### Remaining Technical Debt
-- {package} — {reason not addressed}
-- ...
-```
-
----
-
-## Error Handling
-
-- **npm audit parse failure:** Fall back to `npm audit` text output. Parse manually.
-- **npm install failure:** Roll back. `git checkout package.json package-lock.json` (and workspace equivalents if applicable). Report error.
-- **Test failure:** Stop. Do not proceed with that package. Report and ask user (roll back / fix / skip).
-
----
-
-## Guardrails
-
-- **Never ignore critical CVEs without creating a tracking issue.** Every critical/high CVE must either be fixed or have a tracking issue.
-- **Always test after each upgrade.** Do not batch upgrades without testing.
-- **Never upgrade all packages at once.** One package at a time.
-- **Always commit lockfile changes** after successful upgrades.
-- **ASK at every checkpoint.** Do not proceed without user confirmation.

package/commands/hatch3r-recipe.md

@@ -1,194 +0,0 @@
----
-id: hatch3r-recipe
-type: command
-orchestrator: false
-description: Execute shareable workflow recipes that compose agents, skills, and commands into guided sequences for common development scenarios
-tags: [core]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-parallel_tool_default: true
----
-
-## §0 Detect Ambiguity (P8 B1)
-
-Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
-
-## Agent Pipeline
-
-This command orchestrates other commands and skills as recipe steps. It does not spawn sub-agents directly — the composed commands handle their own agent delegation.
-
-# Recipe System — Composable Workflow Orchestration
-
-Execute predefined or custom workflow recipes that chain hatch3r's agents, skills, and commands into repeatable guided sequences for common development scenarios.
-
----
-
-## Recipe Format
-
-Recipes are YAML files stored in `.hatch3r/recipes/` (project-level) or `~/.hatch3r/recipes/` (user-level).
-
-### Recipe Schema
-
-```yaml
-name: greenfield-setup
-version: 1.0.0
-description: Full greenfield project setup from spec to first PR
-author: hatch3r
-tags: [setup, greenfield, planning]
-
-prerequisites:
-  - GitHub repository initialized
-  - hatch3r initialized (hatch3r init)
-
-variables:
-  project_name:
-    description: Project name
-    required: true
-  tech_stack:
-    description: Primary tech stack
-    required: true
-    options: [react, vue, next, express, fastify]
-
-steps:
-  - id: generate-spec
-    name: Generate Project Specification
-    command: hatch3r-project-spec
-    inputs:
-      project_name: "{{ project_name }}"
-    checkpoint: true
-
-  - id: init-board
-    name: Initialize Project Board
-    command: hatch3r-board-init
-    depends_on: [generate-spec]
-    checkpoint: true
-
-  - id: fill-board
-    name: Fill Board from Specification
-    command: hatch3r-board-fill
-    depends_on: [init-board]
-
-  - id: security-baseline
-    name: Security Baseline Audit
-    command: hatch3r-security-audit
-    depends_on: [fill-board]
-    parallel_with: [a11y-baseline]
-
-  - id: a11y-baseline
-    name: Accessibility Baseline
-    skill: hatch3r-a11y-audit
-    depends_on: [fill-board]
-    parallel_with: [security-baseline]
-
-  - id: first-pickup
-    name: Pick Up First Issue
-    command: hatch3r-board-pickup
-    depends_on: [security-baseline, a11y-baseline]
-    checkpoint: true
-
-completion:
-  message: "Project {{ project_name }} is set up with board, security audit, and first issue in progress."
-  next_steps:
-    - Continue with `board-pickup` to implement remaining issues
-    - Run `hatch3r-dep-audit` for dependency security baseline
-```
-
-## Built-in Recipes
-
-### 1. Greenfield Setup
-Full project initialization: spec -> board -> audit -> first issue.
-
-### 2. Legacy Onboarding
-Codebase analysis -> codebase map -> board setup -> healthcheck -> first improvements.
-
-### 3. Security Hardening
-Security audit -> dependency audit -> findings triage -> hardening implementation.
-
-### 4. Performance Sprint
-Performance audit -> budget review -> optimization planning -> implementation -> verification.
-
-### 5. Release Preparation
-Healthcheck -> test validation -> security scan -> changelog -> release.
-
-### 6. Quality Gate
-Lint fix -> test coverage review -> a11y audit -> perf audit -> security scan.
-
-## Recipe Execution
-
-### Workflow
-
-1. **Parse recipe**: Load and validate YAML schema, resolve variable references.
-2. **Check prerequisites**: Verify all prerequisites are met before starting.
-3. **Collect variables**: Prompt user for required variables (or accept via CLI args).
-4. **Build execution graph**: Resolve `depends_on` and `parallel_with` into a dependency DAG.
-5. **Execute steps**: Run steps in dependency order, parallelizing where possible.
-6. **Handle checkpoints**: At `checkpoint: true` steps, pause and present progress to user.
-7. **Report completion**: Show completion message and next steps.
-
-### Execution Modes
-
-| Mode | Behavior |
-|------|----------|
-| Interactive (default) | Pause at checkpoints, show progress |
-| Auto (`--auto`) | Skip checkpoints, run all steps autonomously |
-| Dry-run (`--dry-run`) | Show execution plan without running |
-| Resume (`--resume`) | Continue from last checkpoint |
-
-### Error Handling
-
-- **Step failure**: Stop execution, show error, offer retry or skip.
-- **Dependency failure**: Skip dependent steps, mark as blocked.
-- **Partial completion**: Save progress, allow resume from last successful step.
-
-## Custom Recipes
-
-### Creating a Recipe
-
-1. Create a YAML file in `.hatch3r/recipes/your-recipe.yaml`
-2. Follow the recipe schema above
-3. Test with `--dry-run` mode
-4. Share by including in the project repository
-
-### Recipe Composition
-
-Recipes can reference other recipes as steps:
-```yaml
-steps:
-  - id: security
-    recipe: security-hardening
-    inputs:
-      scope: full
-```
-
-## Output Format
-
-```
-## Recipe Execution: {recipe_name}
-
-**Status:** COMPLETE | PARTIAL | FAILED
-
-**Steps:**
-
-| # | Step | Status | Duration | Notes |
-|---|------|--------|----------|-------|
-| 1 | Generate Spec | DONE | 5m | Spec created at docs/spec.md |
-| 2 | Init Board | DONE | 2m | Board created with 8 columns |
-| 3 | Fill Board | DONE | 8m | 24 issues created |
-| 4 | Security Audit | DONE | 3m | Audit epic #45 created |
-| 5 | First Pickup | IN PROGRESS | - | Working on #46 |
-
-**Variables Used:**
-- project_name: {value}
-- tech_stack: {value}
-
-**Next Steps:**
-- {recommendations}
-```
-
-## Guardrails
-
-- Recipes must not bypass safety checkpoints for destructive operations
-- Recipe files are validated against the schema before execution
-- Circular dependencies in the execution graph are detected and rejected
-- Variable injection is sanitized to prevent command injection