Workflow Rust Plan

Workflow: Rust Plan

A 5-step planning workflow for Rust development tasks. Queries the rust-librarian knowledge base to enrich plans with idiomatic patterns, then optionally feeds into the SDLC plan-execute-verify loop.

When to Use

• Before implementing any non-trivial Rust feature
• When writing Rust code involving ownership, lifetimes, async, or unsafe
• When planning a new Rust crate or module
• When you want compile-fix loop guardrails on generated Rust code

Config

# --- Required ---
task: <string>                  # What needs to be built

# --- Optional ---
crate_context: <string>         # Path to existing crate (reads Cargo.toml, src/)
target_crate: <string>          # Which crate to modify (for workspace projects)
compile_fix: <bool>             # Enable compile-fix loop (default: false)
max_fix_attempts: <int>         # Max compile-fix iterations (default: 3)
patterns_limit: <int>           # Max pattern results to inject (default: 5)
error_limit: <int>              # Max error examples to inject (default: 3)
skip_search: <bool>             # Skip knowledge base search (default: false)
plan_only: <bool>               # Stop after plan (default: false)

Steps

Step 1: Context Gathering

Understand what exists and what is needed.

1. Read task description
2. If crate_context provided:
   - Read Cargo.toml (deps, features, edition)
   - Read src/lib.rs or src/main.rs (public API surface)
   - Identify existing patterns (error handling, async, serde)
3. Extract key Rust concepts:
   - Ownership/borrowing implications
   - Concurrency model (sync, async, threads)
   - Error handling strategy (Result, anyhow, thiserror)
   - Trait requirements
   - Unsafe needs

Step 2: Knowledge Base Query

Search rust-librarian for relevant patterns and pitfalls.

1. Query project-rust-patterns:
   - Search patterns matching task domain
   - "HTTP server" -> "async HTTP handler pattern"
   - "CLI" -> "clap derive pattern"

2. Query project-rust-books-guides:
   - Search relevant Rust Book chapters
   - References -> "borrowing and lifetimes"
   - Enums -> "pattern matching enum"

3. Query project-rust-error-examples:
   - Search common errors in task domain
   - Async -> "error[E0277] Future is not Send"
   - Borrowing -> "error[E0502] cannot borrow as mutable"

4. Collect top results (patterns_limit + error_limit)
5. Format as planning context block

Search execution (calls rust-librarian API or CLI):

# If search API running:
curl -s -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{"query":"<concepts>","projects":["rust-knowledge"],"framework":"rust","limit":5}'

# If using skill directly:
/rust-librarian search "<concepts>"

Step 3: Plan Generation

Generate a Rust-aware implementation plan.

Synthesize into plan with sections:

## Approach
- Strategy and which patterns apply

## Crate Structure
- Files to create/modify
- Module organization, public API

## Dependencies
- Required crates + versions + feature flags

## Implementation Notes
- Ownership/lifetime considerations
- Error handling approach
- Concurrency model
- Known pitfalls to avoid (from error search)

## Validation
- cargo check, cargo clippy -- -D warnings
- cargo test strategy

If plan_only=true -> STOP here, return plan.

Step 4: Execute

Implement the plan. Optionally use compile-fix loop.

1. Write code following plan
2. Run validation:
   - cargo check
   - cargo clippy -- -D warnings
   - cargo test

3. If compile_fix=true and check fails:
   a. Parse errors via: cargo check --message-format=json
   b. Extract error[E####] codes
   c. Query rust-librarian for each error code
   d. Apply fixes informed by knowledge base
   e. Retry up to max_fix_attempts

Structured error parsing (better than RustCoder's stderr scraping):

cargo check --message-format=json 2>&1 | \
  python3 -c "
import sys, json
for line in sys.stdin:
    try:
        msg = json.loads(line)
        if msg.get('reason') == 'compiler-message':
            code = msg['message'].get('code')
            if code: print(f'ERROR: {code[\"code\"]}')
            print(msg['message'].get('rendered',''))
    except: pass
"

Step 5: Verify & Report

Validate and report results.

1. Full validation:
   - cargo check
   - cargo clippy -- -D warnings
   - cargo test
   - cargo doc --no-deps (if public API)

2. Report:
   - Files created/modified
   - Patterns applied (with source attribution)
   - Pitfalls avoided (error code references)
   - Test results

3. SDLC integration:
   - Update BD issue with evidence
   - Link to spec if exists

SDLC Mapping

Maps to plan-execute-verify flow stages:

Examples

# Plan a feature with knowledge enrichment
/workflow rust-plan task="Implement concurrent rate limiter with token bucket"

# Plan with existing crate context
/workflow rust-plan task="Add WebSocket support" crate_context="crates/lev-gateway"

# Plan + execute with compile-fix
/workflow rust-plan task="Create CLI parser" compile_fix=true max_fix_attempts=5

# Plan only
/workflow rust-plan task="Design error handling for lev-reactive" plan_only=true

Related

• rust-librarian -- Knowledge base skill (search + ingestion)
• plugins/core-sdlc/ -- SDLC plan-execute-verify flow
• core/flowmind/ -- FlowMind execution engine
• os/agent/performance-engine/ -- Go docs system (architecture reference)