planning

An AI-first planning framework for tracking project ideas, specifications, and research — designed to be used entirely through AI coding agents like Claude Code.

What Is This?

A structured repository where AI agents manage all the planning artifacts — specs, research notes, assumption tracking, session state — so you can think at the product level while your agent handles the bookkeeping.

You describe what you want to build. The agent researches, drafts specs, tracks assumptions with confidence scores, runs experiments, and produces implementation plans — all persisted across sessions so you never lose context.

Getting Started

1. Clone this repo and open it in Claude Code (or another AI coding agent)
2. The agent reads CLAUDE.md for instructions automatically
3. Use slash commands to drive the workflow:

Command	Purpose
/new-project	Create a new project
/new-idea	Add an idea to a project
/continue	Pick up previous work
/iterate	Refine a spec with assumption tracking
/research	Conduct focused research (web + codebase)
/spike	Run an experiment to validate an assumption
/implement	Convert a spec into repo-local implementation plans
/export	Generate a shareable spec document
/milestone	Complete current work as a milestone and start the next phase
/status	View project dashboard
/update-repo	Evolve the repo itself

How It Works

Planning Flow

Loose idea → /research → Draft spec → /iterate → Refined spec → /implement → Implementation plan
                                          ↑                          |
                                          └── /spike (validate) ─────┘

1. Research — The agent explores your codebase and searches the web in parallel using sub-agents
2. Draft — Findings are synthesized into a structured spec
3. Iterate — Assumptions are extracted, scored for confidence (1-10), and tracked. You address them one by one until confidence is high
4. Implement — The spec is converted into file-level implementation plans optimized for coding agents

How To Use This Repository

This repository is intended to be written, read, and maintained by agents. You should not need to manage the planning files by hand. The structure is designed so you can work from an AI coding agent locally, or even from Claude's mobile app when you want to capture and shape plans on the go.

Projects vs. Ideas

Projects are broad buckets like "Mattermost Core Product" or "Agents Plugin". Ideas are closer to Jira-epic-sized efforts within a project, such as "create a common library of npm-installable components". You will usually create projects infrequently, then create ideas more often as new initiatives come up.

For example, if a "Mattermost Core Product" project already exists, you might start with:

/new-idea in the mattermost core project, I have an idea about creating a common library of npm installable components

The skill scaffolds the idea, registers it, and creates the planning files the agent will maintain for you.

Start With a Brain Dump

After creating an idea, give the agent everything you know: what you want to accomplish, where you think the solution should go, constraints, guesses, unknowns, examples, and any relevant context. This does not need to be polished. The goal is to give the agent enough raw material to research, organize, and challenge the plan.

If the idea touches codebases listed in the project, the planner can create worktrees for those repositories using the IDEA-00x slug. You will need the wt CLI installed for this workflow. When prompted, use /add-dir for any relevant worktree directories so the agent can access them.

Research and Evidence

Once the brain dump is in place, run /research. You can be prescriptive about what to investigate, or vague and let the agent decide what to inspect. Research may include codebase exploration, web searches, product analysis, documentation review, or anything else needed to turn the brain dump into a grounded plan.

When /research finishes, the agent will draft or update the spec, research notes, and assumption tracker. From there, the goal is to replace assumptions with firm evidence from code, documentation, real-world behavior, spikes, or your explicit steering.

Reduce Uncertainty With Spikes

Use /spike when the plan depends on something uncertain and testable. The agent may suggest spikes itself, especially when an assumption is blocking confidence.

Spikes are small, focused proofs of concept. They answer questions like:

• What is the actual signature of a third-party library function?
• How does the server plugin system handle reconnects after a plugin crashes?
• Can this API support the shape of interaction the spec depends on?

The spike skill is one of the most useful ways to reduce assumptions before implementation work begins.

Iterate Until the Plan Is Ready

After research and useful spikes are complete, run /iterate. The planner scores confidence out of 10 for the overall spec and for individual parts of the plan. Confidence is based on evidence: referenced code, research findings, spike results, or decisions you have explicitly made.

During iteration, the agent walks through assumptions and gives you options. This is where you steer the plan. You can accept a recommendation, reject it, provide missing context, ask for more research, or request another spike. It is normal for /iterate to lead back into /research or /spike; that usually means the plan is getting sharper.

Repeat /iterate until the overall confidence is at least 8/10. Ideally, each important section is also at least 8/10. If a section remains lower, ask:

what can I do to increase confidence?

Sometimes the answer is that you cannot fully know until implementation. That is fine. Perfect is the enemy of good; the point is to make the plan strong enough that implementation failures reveal genuine surprises rather than missing planning work.

Export for Review

When the spec is ready, use /export to turn it into a clean, shareable document suitable for Confluence or an RFC review. The exported version should be self-contained and free of internal planning-repo bookkeeping.

Move Into Implementation Planning

Use /implement when you are happy with the spec and confidence level. The skill sends sub-agents into the relevant repositories to create medium-level technical plans based on the actual code and the goal of the idea.

Each relevant repository gets a repo-local plan at:

.planning/PLAN.md

These plans capture what should change, generally how it should change, and where the work belongs. They should not be line-by-line implementation scripts.

The idea also gets an orchestration plan:

IMPL_ORCHESTRATION_PLAN.md

This file describes the phased execution order across repositories, including what can run in parallel and what should be reviewed between phases. This plan also provides guidance for discrete points where atomic commits can be made. This can help with review later.

Execute With Team Implementation

After /implement, clear or reset your agent context if needed, then use /continue to reload the idea before handing off to the /teamimplement skill if that skill is available in your environment.

/teamimplement consumes the repo-local .planning/PLAN.md files and the orchestration plan. It breaks the work into tasks, spins up a team of agents, and runs each phase through a deeper cycle:

1. Plan the phase in .planning/phase-x/PLAN.md
2. Implement the phase
3. Review the code and adherence to the original plan
4. Rework implementation if review finds issues
5. Write .planning/phase-x/SUMMARY.md for future agents

The team implementation workflow is also intended to perform real browser-based QA validation when appropriate. Give the agent any required environment details up front, such as Mattermost server URLs, usernames, passwords, feature flags, plugin deployment steps, or test data requirements.

Continue Async Work

Planning and implementation can take hours. Use /continue to resume without restoring an entire previous chat. This is especially useful after /clear, after /implement, or when returning later from a different device.

The repository is designed for async collaboration: the durable state lives in the project, idea, spec, research, assumptions, and session files rather than in one long chat transcript.

The End Goal

The goal is to collaborate with an agent like an engineer: shape the plan, challenge assumptions, gather evidence, and produce something implementation agents can execute with high confidence.

When implementation succeeds, is tested, and has been validated, you have a strong point for human code review and targeted refactoring. When implementation fails, it is often a signal that something was missing from the planning phase. Feed that learning back into the spec, assumptions, or future milestones.

Cross-Session Persistence

Every idea has a session.md that captures progress, decisions, open questions, and next steps. When you return with /continue, the agent loads full context and picks up exactly where you left off.

Multi-Milestone Support

Large features are broken into milestones. When a phase is complete, /milestone archives everything and resets the workspace for the next phase — with full history preserved.

Repository Structure

planning/
├── CLAUDE.md              ← Agent instructions (Claude Code)
├── AGENTS.md              ← Agent instructions (other AI agents)
├── registry.yaml          ← Master index of all projects and ideas
├── bin/planning           ← CLI for scaffolding (saves agent context window)
├── projects/
│   └── <project-slug>/
│       ├── project.yaml   ← Project metadata and repo URLs
│       ├── context.md     ← Living architecture and decision notes
│       └── ideas/
│           └── <NNN>-<slug>/
│               ├── spec.md         ← The specification / PRD
│               ├── research.md     ← Research notes and findings
│               ├── session.md      ← Cross-session conversation state
│               ├── assumptions.md  ← Tracked assumptions with confidence scores
│               ├── IMPL_ORCHESTRATION_PLAN.md ← Cross-repo implementation order
│               ├── MILESTONES.md   ← Completed milestone index
│               ├── spikes/         ← Experiment code
│               └── milestones/     ← Archived milestone artifacts
├── templates/             ← Scaffolding templates
└── .claude/
    ├── settings.json      ← Hooks (session start, stop, compaction)
    ├── agents/            ← Sub-agent definitions (explorer, researcher, planner)
    └── skills/            ← Slash command definitions

Requirements

• Claude Code (or another AI coding agent that reads AGENTS.md)
• Python 3 (for bin/planning CLI)
• PyYAML (pip install pyyaml)
• wt CLI (for creating and managing implementation worktrees)
• gh CLI (optional, for GitHub integration)

Customization

• Add your own skills — Create .claude/skills/<name>/SKILL.md with frontmatter and instructions
• Modify templates — Edit files in templates/ to change how new specs, sessions, etc. are scaffolded
• Add hooks — Edit .claude/settings.json to run shell commands on session events
• Tune agent instructions — Edit CLAUDE.md to match your workflow preferences

License

MIT