# 9plan API Examples

Concrete request and response examples for every tool.

---

## Session Tools

### 9plan_session_create

Creates a new session for a task.

**Request:**
```json
{
  "tool": "9plan_session_create",
  "arguments": {
    "task_description": "Build Ghost-powered blog application with authentication, post fetching, pagination, and response caching"
  }
}
```

**Response (Success):**
```
[Session: amber-quiet-river]

Session created: amber-quiet-river
Directory: /Users/dev/.9plan/sessions/amber-quiet-river

The session is ready. Use 9plan_queue_add to add plans, then 9plan_queue_pull to begin work.
```

**Response (Error - rare, usually filesystem issues):**
```
Error: Failed to create session directory: Permission denied

Check that 9plan has write access to /Users/dev/.9plan/sessions/
```

---

### 9plan_session_resume

Loads an existing session.

**Request:**
```json
{
  "tool": "9plan_session_resume",
  "arguments": {
    "session_name": "amber-quiet-river"
  }
}
```

**Response (Success - with active plan):**
```
[Session: amber-quiet-river]

Session resumed: amber-quiet-river
Directory: /Users/dev/.9plan/sessions/amber-quiet-river

Task: Build Ghost-powered blog application with authentication, post fetching, pagination, and response caching

Active plan: k7f3m
  Path: /Users/dev/.9plan/sessions/amber-quiet-river/plans/k7f3m.txt
  Goal: Create authenticated Ghost API client module

Queue (2 plans):
  1. m2x9p - Implement response caching system
  2. p4r2k - Build post display layer with pagination

Completed: 0 plans

An active plan exists. Read the plan file to continue, or use 9plan_plan_complete/defer/discard to close it out.
```

**Response (Success - no active plan):**
```
[Session: amber-quiet-river]

Session resumed: amber-quiet-river
Directory: /Users/dev/.9plan/sessions/amber-quiet-river

Task: Build Ghost-powered blog application with authentication, post fetching, pagination, and response caching

Active plan: (none)

Queue (3 plans):
  1. k7f3m - Create authenticated Ghost API client module
  2. m2x9p - Implement response caching system
  3. p4r2k - Build post display layer with pagination

Completed: 0 plans

Use 9plan_queue_pull to get the next plan.
```

**Response (Success - empty queue):**
```
[Session: amber-quiet-river]

Session resumed: amber-quiet-river
Directory: /Users/dev/.9plan/sessions/amber-quiet-river

Task: Build Ghost-powered blog application with authentication, post fetching, pagination, and response caching

Active plan: (none)

Queue: (empty)

Completed: 6 plans

Task complete! Use 9plan_history_search to review completed work.
```

**Response (Error - session not found):**
```
Error: Session not found: amber-quiet-river

Check the session name and try again. Session names are case-sensitive.
Available sessions can be found in: /Users/dev/.9plan/sessions/
```

---

## Queue Tools

### 9plan_queue_add

Adds a new plan to the queue.

**Request (full plan):**
```json
{
  "tool": "9plan_queue_add",
  "arguments": {
    "context": "Building Ghost blog app. This is the foundational component that all other parts depend on. Must complete first.",
    "goal": "Create authenticated Ghost API client module",
    "inputs": "- Ghost API credentials: provided by user or environment",
    "outputs": "- ghost_client module: authenticated client instance with methods for getPosts(), getPost(id), with proper error handling",
    "approach": "1. Set up Ghost Content API authentication using API key\n2. Create client wrapper with typed methods\n3. Implement error handling for auth failures and API errors\n4. Export configured client instance",
    "success_criteria": "- Client successfully authenticates with Ghost API\n- getPosts() returns post array\n- getPost(id) returns single post\n- Auth errors throw descriptive exceptions",
    "position": "back"
  }
}
```

**Response (Success):**
```
[Session: amber-quiet-river]

Plan added: k7f3m
Path: /Users/dev/.9plan/sessions/amber-quiet-river/plans/k7f3m.txt
Queue position: 1

The plan file has been created. Use 9plan_queue_pull when ready to execute.
```

**Request (minimal - no inputs/outputs):**
```json
{
  "tool": "9plan_queue_add",
  "arguments": {
    "context": "Building blog app. Need a basic UI component.",
    "goal": "Create PostCard component for displaying individual posts",
    "approach": "1. Create React component\n2. Accept post data as props\n3. Display title, excerpt, date\n4. Style with Tailwind",
    "success_criteria": "- Component renders post data\n- Styling looks good\n- No TypeScript errors",
    "position": "front"
  }
}
```

**Response (Success - front position):**
```
[Session: amber-quiet-river]

Plan added: r3t7w
Path: /Users/dev/.9plan/sessions/amber-quiet-river/plans/r3t7w.txt
Queue position: 1 (front)

The plan file has been created. Use 9plan_queue_pull when ready to execute.
```

**Response (Error - missing required field):**
```
Error: Plan validation failed

Missing required fields:
- approach: Must describe how to accomplish the goal

Please provide all required fields: context, goal, approach, success_criteria
```

**Response (Error - empty field):**
```
Error: Plan validation failed

Empty required fields:
- goal: Cannot be empty

Please provide meaningful content for all required fields.
```

---

### 9plan_queue_pull

Gets the next plan to work on.

**Request:**
```json
{
  "tool": "9plan_queue_pull",
  "arguments": {}
}
```

**Response (Success):**
```
[Session: amber-quiet-river]

Active plan: k7f3m
Path: /Users/dev/.9plan/sessions/amber-quiet-river/plans/k7f3m.txt

Read the plan file for full context. Review for any ambiguities before starting execution.

If the plan has inputs from other plans, use 9plan_history_search to find their outputs.
If the plan's Notes indicate it was previously decomposed, use 9plan_history_get to retrieve child outcomes.
```

**Response (Error - plan already active):**
```
[Session: amber-quiet-river]

Error: Cannot pull - a plan is already active

Active plan: k7f3m
Path: /Users/dev/.9plan/sessions/amber-quiet-river/plans/k7f3m.txt

Complete, defer, or discard the active plan before pulling another.
```

**Response (Queue empty):**
```
[Session: amber-quiet-river]

Queue is empty. Task complete!

Completed plans: 6

Use 9plan_history_search to review what was accomplished.
```

---

## Plan Lifecycle Tools

### 9plan_plan_complete

Marks the active plan as done.

**Request:**
```json
{
  "tool": "9plan_plan_complete",
  "arguments": {
    "outcome": "Created ghost_client module in src/lib/ghost-client.ts.\n\nExports:\n- GhostClient class with constructor(apiKey, apiUrl)\n- getPosts(options?: {limit, page}) → Post[]\n- getPost(id: string) → Post\n\nError handling:\n- GhostAuthError for 401/403 responses\n- GhostNotFoundError for 404 responses\n- GhostAPIError for other failures\n\nTested against live Ghost instance, all methods working."
  }
}
```

**Response (Success):**
```
[Session: amber-quiet-river]

Plan k7f3m completed and indexed.

The plan's content and outcome are now searchable via 9plan_history_search.

Queue status: 2 plans remaining
Next: Use 9plan_queue_pull to continue work.
```

**Response (Error - no active plan):**
```
[Session: amber-quiet-river]

Error: No active plan to complete

Use 9plan_queue_pull to get a plan first.
```

---

### 9plan_plan_defer

Returns the active plan to the queue.

**Request (blocked, retry soon):**
```json
{
  "tool": "9plan_plan_defer",
  "arguments": {
    "reason": "Blocked: Need Ghost API credentials from user before proceeding",
    "position": "front"
  }
}
```

**Response (Success - front):**
```
[Session: amber-quiet-river]

Plan k7f3m deferred to front of queue.
Reason recorded in Notes.

Queue status: 3 plans
Position: 1 (will be pulled next)

Resolve the blocking issue, then use 9plan_queue_pull to retry.
```

**Request (decomposition, aggregate later):**
```json
{
  "tool": "9plan_plan_defer",
  "arguments": {
    "reason": "Decomposed into subplans: x5k9m (PostList UI), r3t7w (pagination state), j8n2q (integration). Will aggregate child outcomes when re-pulled.",
    "position": "back"
  }
}
```

**Response (Success - back):**
```
[Session: amber-quiet-river]

Plan p4r2k deferred to back of queue.
Reason recorded in Notes.

Queue status: 4 plans
Position: 4 (will execute after current queue)

Use 9plan_queue_pull to continue with queued work.
```

**Response (Error - no active plan):**
```
[Session: amber-quiet-river]

Error: No active plan to defer

Use 9plan_queue_pull to get a plan first.
```

---

### 9plan_plan_discard

Abandons the active plan.

**Request:**
```json
{
  "tool": "9plan_plan_discard",
  "arguments": {
    "reason": "Plan superseded by external changes - the Ghost API was replaced with a different CMS. This plan is no longer relevant."
  }
}
```

**Response (Success):**
```
[Session: amber-quiet-river]

Plan k7f3m discarded.
Reason: Plan superseded by external changes - the Ghost API was replaced with a different CMS. This plan is no longer relevant.

The plan has been removed and will not appear in history.

Queue status: 2 plans remaining
Next: Use 9plan_queue_pull to continue work.
```

**Response (Error - no active plan):**
```
[Session: amber-quiet-river]

Error: No active plan to discard

Use 9plan_queue_pull to get a plan first.
```

---

## History Tools

### 9plan_history_search

Searches completed plans for outputs.

**Request:**
```json
{
  "tool": "9plan_history_search",
  "arguments": {
    "query": "ghost client API authentication"
  }
}
```

**Response (Success - matches found):**
```
[Session: amber-quiet-river]

Found 1 matching plan:

1. Plan k7f3m
   Goal: Create authenticated Ghost API client module
   Outcome: Created ghost_client module in src/lib/ghost-client.ts.
            Exports GhostClient class with getPosts(), getPost() methods...

Use 9plan_history_get with the plan ID for full details.
```

**Response (Success - multiple matches):**
```
[Session: amber-quiet-river]

Found 3 matching plans:

1. Plan k7f3m
   Goal: Create authenticated Ghost API client module
   Outcome: Created ghost_client module in src/lib/ghost-client.ts...

2. Plan m2x9p
   Goal: Implement response caching system
   Outcome: Created caching layer wrapping ghost_client...

3. Plan j8n2q
   Goal: Integrate data fetching with UI components
   Outcome: Connected cached ghost_client to PostList component...

Use 9plan_history_get with the plan ID for full details.
```

**Response (No matches):**
```
[Session: amber-quiet-river]

No matching plans found for: "payment processing stripe"

Try different search terms, or check if the relevant work has been completed yet.
```

---

### 9plan_history_get

Retrieves a specific completed plan.

**Request:**
```json
{
  "tool": "9plan_history_get",
  "arguments": {
    "plan_id": "k7f3m"
  }
}
```

**Response (Success):**
```
[Session: amber-quiet-river]

Plan k7f3m (completed)

# Context
Building Ghost blog app. This is the foundational component that all other parts depend on. Must complete first.

# Goal
Create authenticated Ghost API client module

# Inputs
- Ghost API credentials: provided by user or environment

# Outputs
- ghost_client module: authenticated client instance with methods for getPosts(), getPost(id), with proper error handling

# Approach
1. Set up Ghost Content API authentication using API key
2. Create client wrapper with typed methods
3. Implement error handling for auth failures and API errors
4. Export configured client instance

# Success Criteria
- Client successfully authenticates with Ghost API
- getPosts() returns post array
- getPost(id) returns single post
- Auth errors throw descriptive exceptions

# Notes
[2024-01-15 14:30] Progress checkpoint:
- Created ghost-client.ts with GhostClient class
- Implemented constructor with API key validation
- getPosts() method complete, tested against live API
- Remaining: getPost(id), error handling improvements

# Outcome
Created ghost_client module in src/lib/ghost-client.ts.

Exports:
- GhostClient class with constructor(apiKey, apiUrl)
- getPosts(options?: {limit, page}) → Post[]
- getPost(id: string) → Post

Error handling:
- GhostAuthError for 401/403 responses
- GhostNotFoundError for 404 responses
- GhostAPIError for other failures

Tested against live Ghost instance, all methods working.
```

**Response (Error - not found):**
```
[Session: amber-quiet-river]

Error: Plan not found: xyz99

The plan may not have been completed yet (check queue), or may have been discarded.
Use 9plan_session_resume to see current queue, or 9plan_history_search to find related plans.
```

---

## Admin Tools

### 9plan_admin_validate

Checks session state against all invariants.

**Request:**
```json
{
  "tool": "9plan_admin_validate",
  "arguments": {}
}
```

**Response (Success - all invariants pass):**
```
[Session: amber-quiet-river]

Validation passed: All invariants hold.

Invariants:
  ✓ single_active_plan: At most one plan is active
  ✓ queue_order_preserved: Queue positions are sequential
  ✓ files_match_database: Plan files exist for all queued/active plans
  ✓ no_orphaned_files: No plan files without database entries

Issues: (none)
```

**Response (Issues detected):**
```
[Session: amber-quiet-river]

Validation failed: 2 issues detected.

Invariants:
  ✓ single_active_plan: At most one plan is active
  ✓ queue_order_preserved: Queue positions are sequential
  ✗ files_match_database: Plan files exist for all queued/active plans
  ✗ no_orphaned_files: No plan files without database entries

Issues:
  - Missing plan file: plans/k7f3m.txt (plan k7f3m is queued)
  - Orphaned file: plans/old123.txt (no database entry)
```

---

### 9plan_admin_sessions

Lists all sessions on the system.

**Request:**
```json
{
  "tool": "9plan_admin_sessions",
  "arguments": {}
}
```

**Response (Success):**
```
Sessions found: 3

1. amber-quiet-river
   Created: 2024-01-15 10:30
   Task: Build Ghost-powered blog application
   Queue: 2 plans
   Completed: 4 plans
   Active: Yes (k7f3m)

2. copper-velvet-morning
   Created: 2024-01-14 14:00
   Task: Implement user authentication
   Queue: 0 plans
   Completed: 6 plans
   Active: No

3. silver-ocean-dawn
   Created: 2024-01-13 09:15
   Task: Refactor database layer
   Queue: 3 plans
   Completed: 1 plan
   Active: No
```

**Response (No sessions):**
```
No sessions found.

Use 9plan_session_create to create a new session.
```

---

### 9plan_admin_state

Returns detailed state dump for current session.

**Request:**
```json
{
  "tool": "9plan_admin_state",
  "arguments": {}
}
```

**Response (Success):**
```
[Session: amber-quiet-river]

Session State Dump
==================

Session: amber-quiet-river
Task: Build Ghost-powered blog application with authentication, post fetching, pagination, and response caching

Queue (2 plans):
  Position 1: m2x9p - "Implement response caching system"
  Position 2: p4r2k - "Build post display layer with pagination"

Active Plan:
  ID: k7f3m
  Goal: Create authenticated Ghost API client module
  File: /Users/dev/.9plan/sessions/amber-quiet-river/plans/k7f3m.txt

Completed Plans: 4

Plan Files in Directory:
  - k7f3m.txt (active)
  - m2x9p.txt (queued)
  - p4r2k.txt (queued)

File/Database Match: ✓ Yes
```

**Response (Empty session):**
```
[Session: amber-quiet-river]

Session State Dump
==================

Session: amber-quiet-river
Task: Build Ghost-powered blog application

Queue: (empty)

Active Plan: (none)

Completed Plans: 6

Plan Files in Directory: (none)

File/Database Match: ✓ Yes

Task complete! All plans have been executed.
```

---

## Common Patterns

### Resolving Dependencies

When a plan has inputs, resolve them before execution:

```
1. Read plan file, find inputs:
   "- cached_client: from Cache System work"

2. Search history:
   9plan_history_search("cached_client cache system")

3. Get details if needed:
   9plan_history_get("m2x9p")

4. Use the information from outcome to proceed
```

### Aggregating After Decomposition

When a parent plan is re-pulled:

```
1. Read plan Notes, find child IDs:
   "Decomposed into subplans: x5k9m, r3t7w, j8n2q"

2. Get each child's outcome:
   9plan_history_get("x5k9m")
   9plan_history_get("r3t7w")
   9plan_history_get("j8n2q")

3. Verify children succeeded, aggregate results

4. Complete parent:
   9plan_plan_complete(outcome: "Aggregated from children...")
```

### Adding Subplans in Correct Order

To achieve execution order [A, B, C], add in reverse:

```
9plan_queue_add(C, position: "front")  → Queue: [C, ...]
9plan_queue_add(B, position: "front")  → Queue: [B, C, ...]
9plan_queue_add(A, position: "front")  → Queue: [A, B, C, ...]
```