Limps Plan Operations

Purpose

Provide reusable patterns for working with limps feature plans across commands. Handles plan identification, path resolution, loading plan artifacts, and shared distillation/lifecycle guidance for planning and agent execution.

LLM Execution Rules

• Use limps MCP tools for all reads/writes when available; do not edit plan files directly.
• Do not include secrets, tokens, or credentials in plan content.
• Only run process_doc / process_docs with code you authored or reviewed.

Scope

• identify-plan: Resolve a plan name or path to a canonical plan directory name and base path
• load-artifacts: Load all plan artifacts (plan file, interfaces.md, README.md, gotchas.md, agent files) using limps MCP tools
• resolve-path: Convert plan name/path input to canonical plans/NNNN-descriptive-name/ format
• distill-agent-files: Apply distillation rules and size guidance for *.agent.md generation
• lifecycle: Provide standard lifecycle and command usage context

MCP Tool Usage

All operations use limps MCP tools with server "limps":

Document & Plan Tools

• list_plans - List available plans
• list_agents - List agents for a plan
• process_doc - Read and analyze a single document
• process_docs - Read and analyze multiple documents (e.g., all agent files)
• create_plan - Create a new plan structure
• create_doc - Create a new document
• update_doc - Update an existing document
• search_docs - Full-text search across documents

Health & Integrity Tools

• check_staleness - Report stale plans/agents based on modification time
• check_drift - Verify agent file references match actual filesystem
• infer_status - Suggest status updates based on dependency completion

Proposals & Scoring Tools

• get_proposals - List update proposals from staleness, drift, and inference
• apply_proposal - Apply a single proposal with confirmation
• configure_scoring - Update scoring weights, presets, and biases

Task Management Tools

• get_plan_status - Plan progress summary with completion percentage
• get_next_task - Get highest-priority available task based on scoring
• update_task_status - Update agent status (GAP/WIP/PASS/BLOCKED)

Index Tools

• reindex_docs - Clear and rebuild the search index

Path format: Always relative to configured docsPath, e.g. plans/0041-limps-improvements/0041-limps-improvements-plan.md

Tool invocation: Use call_mcp_tool with server: "limps" and the tool name.

Quick Tool Selection

Identify Plan

When a command needs to identify which plan to work with:

Input Handling

1. User provides plan name or path:

• Examples: plan 41, plan 0041, 0041-limps-improvements, plans/0041-limps-improvements, 0041-limps-improvements/
• Accept any of these formats

1. No plan provided:

• Call list_plans (server: limps) to get available plans
• Choose default: most recently modified plan, highest-numbered plan, or ask user
• Present options if ambiguous

1. Plan not found:

• Report clearly: "Plan '{name}' not found"
• List available plans via list_plans
• Ask user to specify

Path Resolution

Resolve input to canonical format:

• Input: 0041-limps-improvements or plans/0041-limps-improvements or 0041-limps-improvements/
• Output: Plan directory name 0041-limps-improvements and base path plans/0041-limps-improvements/

Rules:

• Strip plans/ prefix if present
• Strip trailing / if present
• Validate format: NNNN-descriptive-name (4 digits, hyphen, descriptive name)
• If invalid format, report error and list available plans

Example Code Pattern

// 1. Get user input or default
const planInput = userProvided || await getDefaultPlan();

// 2. Resolve to canonical format
const planName = resolvePlanName(planInput); // "0041-limps-improvements"
const planPath = `plans/${planName}/`; // "plans/0041-limps-improvements/"

// 3. Validate plan exists
const plans = await call_mcp_tool({
  server: "limps",
  toolName: "list_plans",
  arguments: {}
});

const planExists = plans.some(p => p.name === planName);
if (!planExists) {
  // Report error, list available plans
}

Load Plan Artifacts

When a command needs to read plan files:

Required Files

1. Plan file: plans/{plan-name}/{plan-name}-plan.md - Full feature specifications
2. interfaces.md: plans/{plan-name}/interfaces.md - Contract source of truth
3. README.md: plans/{plan-name}/README.md - Index, graph, status matrix
4. gotchas.md: plans/{plan-name}/gotchas.md - Discovered issues (optional, may not exist)
5. Agent files: plans/{plan-name}/agents/*.agent.md - All agent execution files

Loading Strategy

Use only `process_doc` and `process_docs` (server: limps) for reading. Do not assume other read APIs.

Single files (plan file, interfaces.md, README.md, gotchas.md):

• Use process_doc for each file
• Path: plans/{plan-name}/{filename}.md
• Code: "doc.content" to read full content, or specific extraction code

Agent files (multiple):

• Use process_docs with pattern plans/{plan-name}/agents/*.agent.md
• This loads all agent files in one call
• Code: "docs.map(d => ({ path: d.path, content: d.content }))" or specific extraction

Error Handling

• Missing file: Note in output and continue (e.g., no gotchas.md is acceptable)
• Missing required file (plan file, interfaces.md, README.md): Report error and stop
• MCP tools unavailable: Fall back to reading from workspace files directly (note limitations)

Example Code Pattern for Loading Artifacts

const planName = "0041-limps-improvements";
const planPath = `plans/${planName}/`;

// Load single files
const planFile = await call_mcp_tool({
  server: "limps",
  toolName: "process_doc",
  arguments: {
    path: `${planPath}${planName}-plan.md`,
    code: "doc.content"
  }
});

const interfaces = await call_mcp_tool({
  server: "limps",
  toolName: "process_doc",
  arguments: {
    path: `${planPath}interfaces.md`,
    code: "doc.content"
  }
});

const readme = await call_mcp_tool({
  server: "limps",
  toolName: "process_doc",
  arguments: {
    path: `${planPath}README.md`,
    code: "doc.content"
  }
});

// Load gotchas (optional)
let gotchas = null;
try {
  gotchas = await call_mcp_tool({
    server: "limps",
    toolName: "process_doc",
    arguments: {
      path: `${planPath}gotchas.md`,
      code: "doc.content"
    }
  });
} catch (e) {
  // gotchas.md doesn't exist, continue
}

// Load all agent files
const agents = await call_mcp_tool({
  server: "limps",
  toolName: "process_docs",
  arguments: {
    pattern: `${planPath}agents/*.agent.md`,
    code: "docs.map(d => ({ path: d.path, content: d.content }))"
  }
});

Resolve Path

Convert various plan input formats to canonical path:

Input Formats Accepted

• 0041-limps-improvements (plan name only)
• plans/0041-limps-improvements (with plans/ prefix)
• plans/0041-limps-improvements/ (with trailing slash)
• 0041-limps-improvements/ (plan name with trailing slash)

Output Format

• Plan name: 0041-limps-improvements (canonical directory name)
• Base path: plans/0041-limps-improvements/ (for constructing file paths)
• Plan file path: plans/0041-limps-improvements/0041-limps-improvements-plan.md

Validation

• Must match pattern: NNNN-descriptive-name where NNNN is 1-4 digits (zero-padded)
• If invalid, report error and list available plans

Integration with Commands

Commands that use this skill:

• /audit-plan - Identify plan, load artifacts for audit
• /update-feature-plan - Identify plan, load artifacts for updates
• /run-agent - Identify plan, load agent files
• Other plan-related commands

Command Integration Pattern

### 1. Identify the Plan

- If user provides plan name or path, use it
- If no plan provided: call `list_plans` (server: `limps`), choose default or ask
- Resolve to plan directory name `NNNN-descriptive-name` and base path `plans/NNNN-descriptive-name/`

**Note**: Use `/limps-plan-operations identify-plan` skill for consistent plan identification.

### 2. Load Plan Artifacts

Using only `process_doc` and `process_docs` (server: `limps`), read:
- `plans/{plan-name}/{plan-name}-plan.md`
- `plans/{plan-name}/interfaces.md`
- `plans/{plan-name}/README.md`
- `plans/{plan-name}/gotchas.md` (if present)
- All agent files: `process_docs` with pattern `plans/{plan-name}/agents/*.agent.md`

**Note**: Use `/limps-plan-operations load-artifacts` skill for consistent artifact loading.

Common Patterns

Getting Default Plan

const plans = await call_mcp_tool({
  server: "limps",
  toolName: "list_plans",
  arguments: {}
});

// Choose highest-numbered plan
const defaultPlan = plans
  .sort((a, b) => parseInt(b.number) - parseInt(a.number))[0];

Extracting Features from Plan

const features = await call_mcp_tool({
  server: "limps",
  toolName: "process_doc",
  arguments: {
    path: `${planPath}${planName}-plan.md`,
    code: "extractFeatures(doc.content)"
  }
});

Checking Plan Consistency

// Load all artifacts
const [planFile, interfaces, readme, agents] = await Promise.all([
  loadPlanFile(planPath, planName),
  loadInterfaces(planPath),
  loadReadme(planPath),
  loadAgents(planPath)
]);

// Compare interfaces with agent exports/receives
// Check dependency graph matches assignments
// Verify feature status consistency

Error Handling Patterns

Plan Not Found

Plan '0042-nonexistent' not found.

Available plans:
- 0041-limps-improvements
- 0040-other-feature
- 0039-another-plan

Please specify a valid plan name.

MCP Tools Unavailable

If limps MCP tools are unavailable:

• Ask user for plan path
• Read files directly from workspace using Read tool
• Note in output that some operations may be limited (e.g., duplicate scan, full consistency checks)

Missing Required Files

Error: Required file missing: plans/0041-limps-improvements/0041-limps-improvements-plan.md

Please ensure the plan directory exists and contains the plan file.

Notes

• Always use process_doc and process_docs for reading plan content; do not assume other read APIs
• Path format: always relative to configured docsPath
• Plan names are case-sensitive and must match directory names exactly
• Agent files use pattern NNN_agent_descriptive-name.agent.md (zero-padded 3-digit prefix)
• Zero-padded plan numbers (0001, 0002, ...) ensure proper lexicographical ordering

Distill Agent Files

Agent files are distilled execution context, not documentation.

Include

• Feature IDs + one-line TL;DRs
• Interface contracts (exports + receives)
• Files to create/modify
• Test IDs
• Concise TDD cycles (one line per cycle)
• Relevant gotchas (brief)
• Done checklist

Exclude

• Verbose Gherkin (TL;DR sufficient)
• Methodology explanations (agent knows TDD)
• Git workflow details
• Other agents' details
• Historical context

Target Size

• ~200-400 lines for 2-4 features (guideline, not a hard limit)
• If the interface itself is the deliverable, include full definitions inline and allow ~400-600 lines

Searching Is Failure

If agent files are well-constructed, open-ended searching is rare. Frequent or broad searching means the distillation is too thin.

Self-Contained Scope (Scoped Search Allowed)

Each .agent.md should be self-contained for execution. When details must live elsewhere, include explicit cross-file references (exact file + section/heading) so the agent can do scoped lookup, not open-ended search. If an agent requires broad cross-file context, inline the relevant excerpts (distilled) or split the work so each agent remains self-contained.

When Interface Is the Deliverable

For agents whose primary output is foundational types or interfaces:

• Include full type definitions inline (they are the deliverable)
• Include concrete test assertions, not descriptions
• “Distill” means remove methodology and commentary, keep exact code

Lifecycle

Create Plan

1. Gather context → verbose {plan-name}-plan.md
2. Map interfaces → interfaces.md
3. Draw dependencies → README.md
4. Distill agent files → agents/*.agent.md

Assign Work

Copy agents/000_agent_*.agent.md → paste to agent → done

During Execution

• Agent works from their .agent.md
• Updates status when complete
• Appends to gotchas.md if issues found
• Searches only for unexpected edge cases

Status Values

Commands

Health & Integrity Workflow

After completing agent work or during audits, use health tools in this order:

1. check_drift - Verify file references are still valid
2. infer_status - Check if statuses should change
3. check_staleness - Find stale agents
4. get_proposals - Review all suggested updates
5. apply_proposal - Apply approved suggestions