Migrate plan/update-plan commands into a planning skill and planning agent

[maciejmalecki]

Summary

Refactor the existing planner agent and plan storage to cleanly separate the mechanical file I/O (into a plan skill) from the planner persona (agent), following the same governance model as the meta-log skill.

Motivation

The current planner agent (planner.md) mixes persona behaviour with mechanical file operations inline. Splitting them will:

• Make plan file I/O reusable and testable independently of the agent
• Provide a structured, indexed plan archive in plans/ (mirroring meta/)
• Sync plan content to GitHub issues when plans are issue-scoped
• Keep the planner agent focused on reasoning, questions, and architecture guidance

Current State

• .claude/agents/planner.md — fully-featured planner agent (CREATE + UPDATE modes, refinement loop); exists, to be refactored
• .claude/metaprompts/ — prompt-engineering metaprompts; keep as-is, out of scope
• Plans stored in .ai/{issue-number}-{feature-short-name}/ — migrate to plans/

Proposed Design

1. Plan Template

Extract the plan document structure into:

.claude/templates/plan.template.md

The template defines the canonical sections matching the current planner agent's plan structure (feature description, root cause analysis, relevant code parts, questions, implementation plan, testing strategy, risks, documentation, rollout). Changes to .claude/templates/ do not trigger meta-log.

2. Planning Skill

New skill at .claude/skills/plan/SKILL.md responsible for all mechanical work on plan files:

• Create a new plan from the template
• Update an existing plan (add/remove steps, mark progress, apply answered questions)
• List all plans via plans/README.md index
• Store plans in plans/ folder with sequential IDs:

  plans/PLAN-0001_pipeline-dsl-parallel-execution.md
  plans/PLAN-0002_improve-code-coverage.md
  

• Maintain plans/README.md as an index table (ID, date, status, title, linked issue)
• When a plan is linked to a GitHub issue, replace the issue description with the plan content — the original issue description must be incorporated into the plan's "Feature Description" section before the replace

3. Refactor Planner Agent

Refactor .claude/agents/planner.md to:

• Retain the existing persona, architecture rules, style rules, CREATE/UPDATE modes, and refinement loop
• Delegate all plan file I/O to the plan skill (instead of doing it inline)
• Detect issue context automatically (from branch name or user prompt) and trigger issue sync via the skill

4. Storage Migration

New plans go to plans/ — existing plans in .ai/ are not migrated (leave them in place).

Acceptance Criteria

• .claude/templates/plan.template.md defines canonical plan structure (matches current planner agent's embedded template)
• .claude/skills/plan/SKILL.md implements create, update, list operations
• plans/ folder exists with plans/README.md index; index is updated on every create/update
• When a plan is linked to a GitHub issue, the issue description is replaced with the plan content (original issue description incorporated into plan's Feature Description section)
• .claude/agents/planner.md is refactored to delegate file I/O to the plan skill
• Existing .ai/ plans and .claude/metaprompts/ are left untouched
• All new/modified assets are governed by the meta-log skill (logged in meta/)

Notes

• Plans in plans/ are permanent artifacts — do not delete, only mark as completed or cancelled in the index
• The skill should support backporting: user can supply a custom date for historical plans
• Changes to .claude/templates/ do not trigger meta-log (per existing governance rules)
• .claude/metaprompts/ is out of scope for this issue