coaia-planning

Transform Claude plans into structural tension charts following Robert Fritz methodology

What is coaia-planning?

coaia-planning bridges Claude's plan markdown files and structural tension charts. Plans ARE structural tension charts - not task lists. Each action step telescopes into its own chart with desired outcome, current reality, and strategic secondary choices.

Key Concepts

Plans as Structural Tension

Traditional approach (WRONG):

Plan = list of tasks to complete

Structural tension approach (CORRECT):

Plan = {
  desired_outcome: "what we're creating",
  current_reality: "where we are now",
  action_steps: [each is a telescoped STC]
}

Bidirectional Sync

         ┌─────────────┐
         │  Plan.md    │
         │  (human)    │
         └──────┬──────┘
                │
    plan_to_stc │ sync_plan_to_chart
                ↓
         ┌─────────────┐
         │  Chart.jsonl│ ←─── Agents modify
         │  (agents)   │
         └──────┬──────┘
                │
sync_chart_to_plan
                ↓
         ┌─────────────┐
         │ Updated.md  │
         └─────────────┘

Installation

npm install
npm run build

MCP Configuration

{
  "mcpServers": {
    "coaia-planning": {
      "command": "node",
      "args": ["/a/src/coaia-planning/dist/index.js"],
      "env": {
        "COAIA_PLANS_DIR": "/home/mia/.claude/plans",
        "COAIA_OUTPUT_DIR": "/a/src/coaia-planning/output"
      }
    }
  }
}

Tools

1. parse_plan_structural

Parse Claude plan as structural tension chart with confidence scores.

2. plan_to_stc

Convert plan to structural tension chart JSONL (coaia-narrative compatible).

3. sync_plan_to_chart

Sync plan changes TO chart.

4. sync_chart_to_plan

Sync chart changes TO plan (critical for multi-agent collaboration).

5. create_plan_trace

Generate Langfuse trace data.

Usage

Pattern 1: Plan → Chart → Visualize

# Parse and convert
plan_to_stc --planPath /path/to/plan.md --outputPath plan.jsonl

# Open in visualizer
coaia-visualizer --memory-path plan.jsonl --port 3131

Pattern 2: Multi-Agent Collaboration

# Create initial chart from plan
plan_to_stc --planPath plan.md --outputPath shared.jsonl

# Multiple agents work on shared.jsonl via coaia-visualizer API

# Sync changes back to plan
sync_chart_to_plan --chartsPath shared.jsonl --planPath plan-updated.md

Integration

With coaia-visualizer

Direct JSONL compatibility - no export needed.

plan_to_stc --planPath myplan.md --outputPath myplan.jsonl
coaia-visualizer --memory-path myplan.jsonl --port 3131

With coaia-narrative

Same JSONL format means direct interoperability.

npx [email protected] --memory-path myplan.jsonl

Philosophy

Structural tension = unresolved tension between current reality and desired outcome that naturally seeks resolution.

NOT: gap to fill, problem to solve IS: generative force, creative advancement structure

Action steps ARE telescoped STCs - each with its own desired outcome, current reality, and sub-actions.

Architecture

coaia-narrative  →  STC storage (.jsonl)
coaia-visualizer →  STC WebUI + MCP client
coaia-planning   →  Plan ↔ STC transformation

Development

See ROADMAP.md for phases.

Current Status:

• ✅ Phase 1.1: Structural plan parser
• 🔄 Phase 1.2: Telescoping refinement
• 📋 Phase 2: Bidirectional sync
• 📋 Phase 3: API integration
• 📋 Phase 4: Langfuse traces

License

MIT

Credits

• Methodology: Robert Fritz - Structural Tension
• Foundation: coaia-narrative, coaia-visualizer