Design and Plan

Overview

Help turn ideas into fully formed designs and specs through natural collaborative dialogue, then set up the project context files that ensure every future AI interaction has the right guidance.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you’re building, present the design, get user approval, and finally lay the groundwork that keeps AI agents oriented throughout development.

Anti-Pattern: “This Is Too Simple To Need A Design”

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. “Simple” projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.

Checklist

You MUST create a task for each of these items and complete them in order:

1. Explore project context — check files, folders, docs, recent commits
2. Ask clarifying questions — one at a time, understand purpose/constraints/success criteria
3. Propose 2-3 approaches — with trade-offs and your recommendation; always offer “Other (describe your own)”
4. Present design — in sections scaled to their complexity, get user approval after each section
5. Write design doc — save to docs/plans/YYYY-MM-DD-<topic>-design.md and commit
6. Set up or update project context — create or update AGENTS.md, CHANGELOG.md, and docs scaffold (see section below)
7. Transition to implementation — invoke writing-plans skill to create implementation plan

Process Flow

1. Explore context → 2. Ask clarifying questions → 3. Propose approaches → 4. Present design sections → (revise if needed) → 5. Write design doc → 6. Set up / update project context → 7. Invoke writing-plans

The terminal state is invoking writing-plans. Do NOT invoke any other implementation skill. The ONLY skill you invoke after design-and-plan is writing-plans.

The Process

Understanding the idea:

• Check out the current project state first (files, folders, docs, recent commits)
• Ask questions one at a time to refine the idea
• Prefer multiple choice questions when possible, use open-ended questions when you don’t understand something
• Only ONE question per message – if a topic needs more exploration, break it into multiple questions
• Focus on understanding: purpose, constraints, success criteria

Exploring approaches:

• Propose 2-3 different approaches with trade-offs
• Present options conversationally with your recommendation and reasoning
• Lead with your recommended option and explain why

Presenting the design:

• Once you believe you understand what you’re building, present the design
• Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
• Ask after each section whether it looks right so far
• Cover: architecture, components, data flow, error handling, testing
• Be ready to go back and clarify if something doesn’t make sense

After the Design

Documentation:

• Write the validated design to docs/plans/YYYY-MM-DD-<topic>-design.md
• Use elements-of-style:writing-clearly-and-concisely skill if available
• Commit the design document to git

Project Context Setup:

• Follow the “Project Context Setup” section below
• New project: create all files and commit with: chore: set up project context (AGENTS.md, CHANGELOG, docs)
• Existing project: check what already exists; only create missing files, and add a CHANGELOG entry for the new feature being designed

Implementation:

• Invoke the writing-plans skill to create a detailed implementation plan
• If writing-plans is not available, produce the implementation plan yourself: list all tasks as bite-sized steps (2–5 min each), each with exact file paths, code snippets, commands, and a commit step. Save to docs/plans/YYYY-MM-DD-<topic>-plan.md
• Do NOT invoke any other skill. writing-plans (or its fallback) is the next step.

Project Context Setup

These files keep AI agents (and human developers) oriented throughout the project’s lifetime.

New project: create all files listed below. Existing project (adding a feature): check what already exists first. Only create missing files. At minimum, add a CHANGELOG entry for the work being designed. Skip creating AGENTS.md or docs scaffold if they already exist — update them only if the new feature introduces genuinely new architecture or conventions.

AGENTS.md — Minimal AI Guidance

AGENTS.md is read by AI agents at the start of every session. Keep it short. Every token here is consumed on every request, and models follow roughly 150–200 instructions reliably — bloated files actually hurt performance.

The ideal AGENTS.md contains:

• One sentence describing what this project is and why it exists
• Package manager, if not the ecosystem default (e.g., pnpm, poetry, cargo)
• Non-standard build/test/lint commands (skip if they’re obvious from the project type)
• Pointers to deeper docs for language conventions, architecture, and decisions

What does NOT belong here: file paths (they change), style rules (put them in docs/conventions/), step-by-step setup (put in README), comprehensive architecture (put in docs/architecture.md).

Template:

# [Project Name]

[One sentence: what this does and why it matters.]

## Commands
- Build: `[command]`
- Test: `[command]`
- Lint: `[command]`

## Guidance
- Architecture overview: `docs/architecture.md`
- Coding conventions: `docs/conventions/`
- Decision log: `docs/decisions/`
- Implementation plans: `docs/plans/`

After creating AGENTS.md, create a symlink so Claude Code users also benefit:

ln -s AGENTS.md CLAUDE.md

If this is a monorepo, also create a lightweight AGENTS.md in each package directory describing that package’s purpose and specific tech.

Skip any section of the template that doesn’t apply. A two-line AGENTS.md is better than a padded one.

CHANGELOG.md — Project Memory

A CHANGELOG.md gives AI agents and humans a fast, reliable summary of what has been built without requiring them to parse git history. AI agents working on this project should update it with every meaningful change.

Use Keep a Changelog format:

# Changelog

All notable changes to this project will be documented in this file.
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [Unreleased]
### Added
- Initial project setup and design

Add a note to AGENTS.md pointing to it:

## Changelog
Keep `CHANGELOG.md` up to date. Add an entry under `[Unreleased]` for every
meaningful change: new features, behavior changes, removed functionality.
Use categories: Added, Changed, Deprecated, Removed, Fixed, Security.

docs/ — Progressive Disclosure Scaffold

Create the skeleton so AI agents can discover deeper context as needed. Don’t fill everything in now — just the structure and the architecture summary you already have from the design.

docs/
├── architecture.md        ← High-level system design (summarize from design doc)
├── conventions/
│   └── README.md          ← Index of conventions files; add language-specific files as needed
└── decisions/
    └── 0001-initial-architecture.md   ← ADR for the key choices made during design

docs/architecture.md — Summarize the validated design: what the system does, its main components, how data flows, and key technology choices. This is a living document; it should reflect the current system, not aspirations.

docs/decisions/0001-initial-architecture.md — Record the “why” behind the approach chosen during design. Future significant decisions get their own numbered ADR files. Use this format:

# ADR 0001: [Decision Title]

## Status
Accepted

## Context
[What prompted this decision and what alternatives existed]

## Decision
[What was decided]

## Consequences
[What this enables, constrains, or requires going forward]

docs/conventions/README.md — Start with a one-liner index; add language/framework-specific files (typescript.md, python.md, testing.md, etc.) only as real conventions emerge during development. Reference them from AGENTS.md so agents load only what’s relevant.

Key Principles

• One question at a time — Don’t overwhelm with multiple questions
• Multiple choice preferred — Easier to answer than open-ended when possible
• YAGNI ruthlessly — Remove unnecessary features from all designs
• Explore alternatives — Always propose 2-3 approaches before settling
• Incremental validation — Present design, get approval before moving on
• Minimal context files — AGENTS.md that’s too long hurts more than helps; be ruthless about what goes in
• Living documents — CHANGELOG and architecture.md should be updated as the project evolves, not just at setup
• Be flexible — Go back and clarify when something doesn’t make sense