🇺🇸English

Erk Planning Skill

When to Load

Load this skill when user mentions:

• "update plan", "update the plan"
• "modify the plan", "change the plan"
• "edit the plan"

When these triggers fire and a plan was saved in this session:

1. Check for plan-saved-issue.marker in session scratch:

   erk exec marker read --session-id <session-id> plan-saved-issue
   

2. If found (exit code 0), invoke /local:plan-update <issue-number> with the marker content

3. If not found (exit code 1), ask user for issue number

Overview

Erk-plans are GitHub PRs that track implementation plans. They have a two-part structure:

• PR body : Machine-readable metadata (timestamps, comment IDs, dispatch info)
• First comment : Human-readable plan content in a plan-body metadata block

This separation keeps metadata parseable while plan content remains readable.

Plan Structure

PR #123: "Add feature X [erk-plan]"
├── Body (metadata only):
│   <!-- erk:metadata-block:plan-header -->
│   created_at: 2025-01-05T12:00:00Z
│   created_by: username
│   plan_comment_id: 456789
│   <!-- /erk:metadata-block:plan-header -->
│
│   ## Commands
│   - `erk implement 123`
│   - `erk pr dispatch 123`
│
└── Comment #456789 (first comment, plan content):
    <!-- erk:metadata-block:plan-body -->
    <details open><summary>Plan</summary>

    # Add feature X

    ## Implementation Steps
    1. Step one
    2. Step two

    </details>
    <!-- /erk:metadata-block:plan-body -->

Quick Reference

Creating a Plan

After writing a plan in plan mode:

# Via slash command (recommended)
/erk:plan-save

# Via CLI
erk exec plan-save --format display --session-id="<session-id>"

Updating an Existing Plan

When you need to modify a plan that's already saved to GitHub:

# Via slash command
/local:plan-update 123

# Via CLI
erk exec plan-update --plan-number 123 --session-id="<session-id>"

When to update vs create new:

The Update Workflow

1. Fetch existing plan (if not in local files):

   gh pr view 123 --comments --json comments
   

Extract content from plan-body block in first comment.

1. Enter plan mode and make modifications

2. Update the issue :

   /local:plan-update 123
   

3. Optionally add a comment explaining what changed:

   gh pr comment 123 --body "Updated plan: added step 3 for edge case handling"
   

Plan Mode Integration

When exiting plan mode with an existing linked issue (e.g., from .erk/impl-context/<branch>/ref.json), consider:

1. Update existing : If iterating on the same plan
2. Save as new : If this is a fresh plan unrelated to the linked issue
3. Implement directly : If changes are ready to code

The plan-update command finds plan content from:

1. --plan-path flag (explicit file path)
2. Session scratch storage (via --session-id)
3. ~/.claude/plans/ directory (latest plan file)

Related Commands

Resources

references/

• workflow.md - Complete update workflow with examples

Weekly Installs

53

Repository

dagster-io/erk

GitHub Stars

74

First Seen

Jan 29, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykWarn

Installed on

github-copilot53

codex53

opencode52

claude-code52

kimi-cli52

gemini-cli52