session-planning

Skill: session-planning — Mandatory Planning Workflow for All AI Agents

When to use: At the start of EVERY non-trivial agentic session, before writing any code. This skill is universal — it works with Claude Code, Codex, Cursor, Aider, and any other AI tool that reads AGENTS.md or CLAUDE.md.

---

The 10-Step Workflow

Run these steps in order. Do not skip steps 6 (draft PR) or 7 (user confirmation).

Step 1 — Orient (free)

cat AGENTS.md                                    # cross-tool ground truth
cat CLAUDE.md                                    # project-specific rules
cat graphify-out/GRAPH_REPORT.md                 # codebase map (no token cost)
cat .claude/state/active-tasks.md               # what's already in flight
cat docs/changelog.md | head -40                # what recently changed

Step 2 — Understand the Task

• If from a GitHub issue: read the issue body, comments, linked PRs
• If from a user message: restate the task in one sentence to confirm understanding
• If resuming: read .claude/state/NEXT_ACTION.md and active-tasks.md

Step 3 — Load Relevant Skills

ls .claude/skills/                               # see all available skills
# Load skills matching the task type:
# Multi-file change       → implementation-planner
# Tests needed            → test-first-executor
# Auth/key/agent-tools    → risky-module-review
# Pre-merge review        → council-review
# Adding deps             → dependency-audit
# Codebase exploration    → graphify
# Cross-harness routing   → ecc-harness-patterns

Step 4 — Research (if novel task)

• If the task involves techniques not in the codebase, search OSS reference projects
• Use web search or GitHub MCP to read relevant repos
• Cite sources in the plan

Step 5 — Write the Plan

Use the implementation-planner skill or write directly:

## Plan: <task name>

**Goal:** one sentence

**Files to change:**
- `path/to/file.py` — what changes and why
- `path/to/other.py` — what changes and why

**Steps:**
1. Write tests first (test-first-executor)
2. Implement step A
3. Implement step B
4. Run pytest -x
5. Update changelog
6. Update active-tasks.md

**Risks:** list risky modules requiring risky-module-review

**Acceptance criteria:** how to verify it works