This is an AI-first planning repository. The user interacts exclusively through AI agents — they never read files directly. Your job is to help the user plan, research, and spec out features and projects across their codebases.
planning/
├── CLAUDE.md ← You are here. Read this first, always.
├── registry.yaml ← Master index of ALL projects and their ideas
├── bin/
│ └── planning ← CLI for scaffolding and registry ops (saves context window)
├── .claude/
│ ├── settings.json ← Hooks configuration
│ ├── agents/
│ │ ├── explorer.md ← Codebase exploration sub-agent
│ │ ├── researcher.md ← Web/doc research sub-agent
│ │ └── planner.md ← Spec analysis and planning sub-agent
│ └── skills/
│ └── <skill-name>/
│ └── SKILL.md ← Slash command definition (with YAML frontmatter)
├── projects/
│ └── <project-slug>/
│ ├── project.yaml ← Project metadata, repo URLs, description
│ ├── context.md ← Living doc: architecture, decisions, gotchas
│ └── ideas/
│ └── <NNN>-<slug>/
│ ├── spec.md ← The specification / PRD (current milestone)
│ ├── research.md ← Research notes and findings (current milestone)
│ ├── session.md ← Conversation state for cross-session pickup
│ ├── assumptions.md ← Tracked assumptions with confidence scores (current milestone)
│ ├── IMPL_ORCHESTRATION_PLAN.md ← Cross-repo phase ordering and commit checkpoints (when implementing)
│ ├── MILESTONES.md ← Index of completed milestones (if any)
│ ├── spikes/ ← Experiment code (current milestone)
│ └── milestones/ ← Archived milestone folders
│ └── mN-<slug>/
│ ├── SUMMARY.md ← Concise milestone summary (read this first)
│ ├── spec.md ← Frozen spec from that milestone
│ ├── research.md ← Frozen research
│ ├── assumptions.md ← Frozen assumptions
│ ├── session.md ← Final session state
│ ├── IMPL_ORCHESTRATION_PLAN.md ← Archived orchestration plan (if created)
│ └── spikes/ ← Archived spikes
└── templates/ ← Scaffolding templates (consumed by bin/planning)
Every new session, you MUST:
- Read
registry.yamlto understand the current state of all projects - If the user mentions a specific project or idea, immediately load:
projects/<slug>/project.yamlprojects/<slug>/context.md- The relevant idea's
session.md(if resuming work)
- The relevant idea's
IMPL_ORCHESTRATION_PLAN.md(if it exists and the idea is in implementation or execution)- The relevant idea's
MILESTONES.md(if it exists — provides prior milestone context)
- The relevant idea's
- If the user doesn't specify, offer to continue recent work or start something new using the
/continueskill - Never assume you know the current state — always read the files
These are the primary interface for the user. When the user invokes a skill, follow its instructions precisely.
| Skill | Purpose |
|---|---|
/new-project |
Scaffold a new project |
/new-idea |
Add an idea/milestone to an existing project |
/continue |
Pick up work on an existing project/idea (with selection) |
/iterate |
Enter the structured iteration/refinement loop |
/research |
Conduct a focused research session |
/spike |
Set up and run an experiment |
/export |
Produce a shareable spec document |
/implement |
Convert a spec into repo-local implementation plans plus an orchestration plan for agent-driven development |
/status |
Show a dashboard of all projects and ideas |
/milestone |
Complete current work as a milestone and start the next phase |
/update-repo |
Evolve this repo itself (add skills, update templates, modify hooks, etc.) |
User has a new project to track. Use /new-project to scaffold it, then /new-idea for the first idea.
User has a new idea for an existing project. Use /new-idea to create the idea scaffold, then begin research or spec writing.
- Start with loose context from the user
/research— gather information (web, codebase, product)- Draft initial spec in
spec.md /iterate— enter the structured refinement loop:- Summarize the spec, list phases, give confidence scores
- Track assumptions in
assumptions.md - User addresses assumptions (choices, context,
/spikeresults) - Update scores and assumptions
- Repeat until the user is satisfied
/export— produce shareable doc/implement— convert the spec into a phased implementation plan:- Deep-dives target repo via explorer agent (mandatory)
- Produces repo-local agent-optimized plan(s) at
<target-repo>/.planning/PLAN.md - Produces a high-level execution plan at
<idea>/IMPL_ORCHESTRATION_PLAN.md - Includes cross-repo sequencing, parallel workstreams, and local git commit checkpoints without pushing
- Tasks sized for individual coding agents, with file-level change maps in the repo-local plans
User returns to continue previous work. /continue shows available projects/ideas and loads full context from session.md.
The master index. Every project and idea MUST be registered here. Format:
projects:
- slug: project-slug
name: "Human Readable Name"
status: active | paused | archived
ideas:
- id: "001"
slug: idea-slug
name: "Idea Name"
status: idea | researching | drafting | iterating | review | ready | implementing | done | abandoned
last_session: "2026-03-01"
current_milestone: 2 # optional — present after first milestone completedname: "Project Name"
slug: project-slug
description: "One-line description"
status: active | paused | archived
repos:
- url: "https://github.com/org/repo"
local_path: "~/workspace/repo" # enables explorer agents to deep-dive local code
description: "Main repo"
access: public | private
created: "2026-03-01"
tags: [mattermost, plugin, ai]The local_path field is critical — it tells explorer agents where to find the codebase locally for deep analysis during research, iteration, and implementation planning. All repos are checked out under ~/workspace/ and worktrees are created under ~/workspace/worktrees/.
This is the CRITICAL file for cross-session persistence. Update it at the END of every session.
# Session State: <Idea Name>
## Current Phase
<researching | drafting | iterating | review | ready>
## Last Updated
<date>
## Summary of Progress
<What has been accomplished so far>
## Key Decisions Made
- <Decision 1>
- <Decision 2>
## Open Questions
- [ ] <Question 1>
- [ ] <Question 2>
## Worktrees
- **Branch:** IDEA-NNN-short-description
- ~/workspace/worktrees/<worktree-1>
- ~/workspace/worktrees/<worktree-2>
## Next Steps
1. <Next thing to do>
2. <After that>
## Context Links
- <Links to relevant research, spikes, external docs>Tracked assumptions with confidence scores, used by the /iterate skill.
# Assumptions Tracker: <Idea Name>
## Overall Confidence: <X>/10
| # | Assumption | Confidence | Status | Notes |
|---|-----------|------------|--------|-------|
| 1 | <assumption> | <1-10> | open/addressed/invalidated | <notes> |High-level implementation execution plan created by /implement in the idea root. This file coordinates repo-local .planning/PLAN.md files by sequencing phases across repos/worktrees, highlighting what can run in parallel, and recommending local git commit checkpoints for tracking and review. It should avoid file-level implementation details, which belong in the repo-local plans.
# Implementation Orchestration Plan: <Idea Name>
## Repo Phase Summary
| Repo / Worktree | Relevant Phases | Notes |
|-----------------|-----------------|-------|
| <repo-a> | 1, 2 | <brief summary> |
## Execution Steps
### Step 1: <Name>
- **Complete first:** <repo/phase list>
- **Can run in parallel:** <repo/phase list or none>
- **Review gate:** <what must be reviewed or confirmed>
- **Commit checkpoint:** Create local commit(s). Do not push.Index of completed milestones for an idea, plus a backlog of future milestone ideas. Created by /milestone when the first milestone is completed, or by the add-future-milestone CLI command. Agents should read this file when loading an idea that has prior milestones — it provides historical context without needing to load all archived files.
# Milestones: <Idea Name>
> **Project:** <Project Name>
This file provides historical context for agents working on this idea.
Read this to understand what happened in previous milestones before starting new work.
---
### Milestone 1: <Name> (<date>)
**Slug:** `m1-<slug>` | **Outcome:** completed | partial | pivoted
<2-4 sentence summary>
**Archived files:** `milestones/m1-<slug>/`
---
## Future Milestones
### F1: <Name>
> Added during milestone N (<date>)
<Brief description of what this milestone would cover>
**Triggered by:** <What prompted this idea — optional>
---For deeper detail on any milestone, read milestones/mN-<slug>/SUMMARY.md. Only dig into the archived spec/research/assumptions if you need exact technical details.
If implementation planning was part of a milestone, the archived milestone folder may also contain IMPL_ORCHESTRATION_PLAN.md.
Future milestones are hand-wavy ideas captured during active work. They are lightweight — just a name, description, and context for why they were captured. When the /milestone skill completes a milestone, it checks the backlog and offers to promote an entry to seed the next milestone. Use python3 bin/planning add-future-milestone to add entries via CLI.
You MUST delegate work to sub-agents whenever possible. The orchestrator (you) should coordinate, synthesize, and write documents — not do the grunt work of exploring code, searching the web, or analyzing specs. Sub-agents exist for that.
| Agent | Type | Purpose |
|---|---|---|
explorer |
Custom (explorer) |
Explore target codebases — read code, search files, understand architecture |
researcher |
Custom (researcher) |
Web research — search docs, APIs, libraries, competitors |
planner |
Custom (planner) |
Analyze specs, extract assumptions, design implementation approaches |
- Codebase exploration →
exploreragent. Anytime you need to read, search, or understand code in a target repo, spawn an explorer agent. Use the repo'slocal_pathfromproject.yaml(or the active worktree path fromsession.md) so the agent reads the actual local checkout — no cloning needed. Do NOT read target repo code yourself. - Web/doc research →
researcheragent. Anytime you need to search the web, fetch documentation, or look up external information, spawn a researcher agent. Do NOT use WebSearch/WebFetch yourself. - Spec analysis and planning →
planneragent. Anytime you need to extract assumptions, score confidence, or design implementation approaches from a spec, spawn a planner agent. - Parallel by default. If a task requires both exploration and research (common), launch both agents simultaneously. Do not run them sequentially unless one depends on the other's output.
- The orchestrator writes. After sub-agents report back, YOU synthesize their findings and write/update the planning documents (spec.md, research.md, session.md, assumptions.md, etc.).
- Local repo operations stay with the orchestrator. Reading and writing files within THIS planning repo (registry.yaml, session.md, etc.) is the orchestrator's job. Sub-agents are for external work.
- Skills coordinate agents. When a skill (like
/researchor/iterate) involves tasks that match a sub-agent's purpose, delegate to that agent rather than doing the work inline.
When the user invokes /research with a mixed scope (codebase + web):
1. Spawn explorer agent: "Explore <repo> and find how <feature> is implemented"
2. Spawn researcher agent: "Search for documentation on <API> and find prior art for <pattern>"
(Both run in parallel)
3. Orchestrator receives both reports
4. Orchestrator synthesizes findings into research.md
5. Orchestrator updates session.md and registry.yaml
When the user invokes /iterate:
1. Orchestrator reads spec.md, assumptions.md, research.md
2. Spawn planner agent: "Analyze this spec, extract assumptions, and score confidence: <spec content>"
3. Orchestrator receives analysis
4. Orchestrator writes updated assumptions.md and presents to user
5. If user requests research to address an assumption → spawn researcher/explorer agents
- Always update
session.mdbefore ending a session. This is non-negotiable. - Always update
registry.yamlwhen creating or changing the status of projects/ideas. - Never create files outside the established structure without discussing with the user first.
- Use the CLI (
python3 bin/planning) for scaffolding and registry updates instead of manually reading templates. This saves context window. See skill files for exact commands. - Spikes go in
spikes/subdirectory of the relevant idea. Keep them minimal and focused. - Research findings go in
research.md— don't scatter them across the spec. - The spec (
spec.md) is the source of truth for what the idea actually is. Keep it clean. - When accessing external repos, use
ghCLI orgit cloneas appropriate. The user has PAT/MCP access configured. - Confidence scores in
assumptions.mdshould be honest. Low scores are useful — they highlight where more work is needed. - When the user says "let's work on X", always load context before responding. Don't wing it.
- Capture future milestone ideas proactively. When the user mentions something they want to do later (e.g., "we should do X in a future milestone"), offer to add it to the
## Future Milestonesbacklog inMILESTONES.mdusingpython3 bin/planning add-future-milestone. Don't let good ideas get lost. - For this planning repo itself, always work from
main. Do not create feature branches or repo-local worktrees for planning-repo changes unless the user explicitly asks for an exception. - Commit planning-repo changes incrementally as you develop. Prefer small, logical local commits that preserve iteration history and make it easy to review or recover work. Push only when the user explicitly asks or the active workflow specifically requires it.
When a project references external repos (listed in project.yaml):
- Prefer local paths. Every repo in
project.yamlhas alocal_path(e.g.,~/workspace/repo-name). Use this for explorer agent deep-dives instead of cloning. - Use worktree paths when active. If the idea has worktrees (listed in
session.md), point explorer agents at the worktree path (~/workspace/worktrees/...) — this is the working copy with the idea's branch checked out. - Use
ghCLI to browse issues, PRs, and code on GitHub - Capture architectural findings in
context.md - Reference specific files/lines in specs when relevant
The user works out of git worktrees, not the main checkouts under ~/workspace/. The wt CLI manages worktree lifecycle.
- Main checkouts:
~/workspace/<repo-name>— used as the base for worktree creation, and for explorer deep-dives when no idea-specific worktree exists - Worktrees:
~/workspace/worktrees/<branch-name>/— the actual working directories - Branch naming:
IDEA-<NNN>-<short-description>(at most 3 words, e.g.,IDEA-001-agent-sandboxing) - Multi-repo coordination: When an idea spans multiple repos, worktrees are created on the same branch name across all of them via
python3 bin/planning create-worktrees - Session tracking: Active worktree paths are recorded in the idea's
session.mdunder## Worktrees - Adding to session: After creating worktrees, prompt the user to run
/add-dir <path>for each worktree so Claude Code can access them - Milestone closeout: When
/milestonecompletes work that used implementation worktrees, return to each affected worktree, archive.planning/PLAN.mdinto.planning/milestone-<N>-<slug>/PLAN.md, and make a final local commit if changes remain. Do not push unless the user explicitly asks.
When exporting a spec for sharing (via /export), produce a clean Markdown document that:
- Has a professional header with title, author, date, and status
- Is self-contained (no references to this repo's internal structure)
- Includes all relevant context inline
- Has clear sections: Background, Problem, Proposal, Technical Details, Milestones, Open Questions
- Is suitable for posting in a Mattermost channel or converting to a Google Doc