project-planning

name	project-planning
description	Plan new projects: adaptive interview, tech decisions, fill all project documentation (project-knowledge) in one session. Use when: "сделай описание проекта", "запиши описание проекта в документацию", "проведи со мной интервью для описания проекта", "заполни документацию проекта", "начни планирование проекта", "давай опишем проект", "plan a new project", "fill project documentation"

Project Planning

Conduct adaptive interview → make tech decisions → fill all project documentation in one session.

Project Documentation Autosync

Project documentation source of truth is Claude-side: CLAUDE.md and .claude/**. Codex-side AGENTS.md and .codex/** are generated runtime files.

After changing any project-local .claude/** file, immediately run:

~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply

If sync reports a conflict, stop and report it. Include generated .codex/** changes in the same commit as the .claude/** source change.

Output Files

Project Knowledge (.claude/skills/project-knowledge/references/):

• project.md — overview, audience, problem, key features, scope
• architecture.md — tech stack, project structure, dependencies, data model
• patterns.md — git workflow (code patterns, testing, business rules are filled later during development)
• deployment.md — platform, environment, CI/CD, monitoring
• ux-guidelines.md — only if project has significant UI

Interview Methodology

One question at a time. Ask one question, wait for the answer, then form the next question based on the response.

Build on answers. If user mentioned a domain — ask domain-relevant follow-ups. If they said something vague — clarify that specific point.

Confirm understanding. After 3-5 questions, briefly summarize what you understood. Catches misunderstandings early.

Help when stuck. When user says "not sure" or "don't know":

1. Say it's OK
2. Offer 2-3 common approaches for their type of project
3. Ask which is closer
4. If still uncertain and optional — mark TBD, move on
5. If still uncertain and required — break into simpler sub-questions

Recount on scope changes. If user suddenly adds many features or reveals unexpected complexity — stop and recount total scope. Show the updated list, confirm you understood correctly.

If code exists. Scan the codebase in parallel with the interview to pre-fill technical decisions and ask more targeted questions.

Phase 1: Project Discovery

1.1 Interview

Verify that project-knowledge directory and CLAUDE.md exist. If missing — tell user to run /init-project first.

Ask user to describe the project in free form. Let them say as much or as little as they want.

Then ask adaptive questions to cover three areas:

Project Overview:

• What the project does (one-line + context)
• Who uses it and why (target audience + use case)
• What problem it solves (core pain point)
• 3-5 key features (high-level only)
• Scope boundaries (explicit exclusions)

Features & MVP:

• Key features with descriptions
• What's included in MVP (launch scope)
• What comes later (post-launch ideas) — note these for the backlog
• Priority for each: Critical / Important / Nice-to-have

Development Approach:

• All at once or phased?
• If phased: how to group features, what's MVP
• If migration: current system, data migration, risks, rollback plan

1.2 Checkpoint

Move to Phase 2 when you can:

• Write a clear, non-vague project.md
• List key features with priorities and MVP scope
• Describe the development approach

TBD is acceptable for optional aspects.

Phase 2: Technical Decisions

2.1 New Project (no code)

1. Propose tech stack based on Phase 1: frontend, backend, database, key dependencies
2. Verify choices against current docs (Context7 if available). Update if you find deprecations or better alternatives.
3. Propose deployment: platform, CI/CD approach, environments
4. Present proposal to user with rationale for each choice. Iterate until user approves.

2.2 Existing Code

1. Extract stack from the codebase: package files, configs, directory structure
2. Verify against current docs (Context7 if available)
3. Confirm with user: show what you found, ask about gaps (deployment, missing pieces)
4. Iterate until confirmed.

2.3 Checkpoint

Move to Phase 3 when:

• Tech stack (frontend, backend, database, key dependencies) approved by user
• Deployment platform and CI/CD approach agreed
• No open questions on technical choices

Phase 3: Fill Documentation

Documentation goal: someone opens these files and understands the project without reading code. Describe what exists, what it does, and why. Record decisions, operational details (server addresses, deploy procedures, log locations), high-level component overview. Write in prose, link to source files for code details. Each fact lives in one file only.

Use Edit tool to replace template placeholders with real content. Content language: English.

3.1 Project Knowledge Files

project.md — from Phase 1 interview:

• Project overview, target audience, core problem
• Key features with priorities and MVP scope
• Post-launch ideas (if discussed)
• Out of scope

architecture.md — from Phase 2 decisions + codebase analysis:

• Tech stack with "why" for each choice
• Project structure (directory tree)
• Key dependencies (only critical ones, not everything)
• External integrations
• Data flow
• Data model (fill if known, leave template sections if TBD)

patterns.md — fill git workflow section:

• Branch structure (main + dev)
• Testing requirements
• Security gates (pre-commit, pre-push)
• Leave code patterns, testing methods, and business rules sections minimal — filled during development as patterns emerge

deployment.md — from Phase 2 decisions:

• Platform, type, rationale
• Deployment triggers (what deploys where)
• Environments and URLs
• Environment variables (reference .env.example)
• Monitoring: fill if configured, note "not yet configured" if not

ux-guidelines.md — only if project has significant UI. Skip entirely for CLIs, APIs, bots without custom UI.

3.2 Backlog (if applicable)

If post-launch features were discussed during the interview, offer to save them to a backlog. Ask user where to create the backlog file.

3.3 Checkpoint

All output files from "Output Files" section created. No template placeholders remain.

Phase 4: Review & Commit

4.1 Self-Verify

Before presenting to user, verify:

• project.md contains all key features discussed in interview
• architecture.md tech stack matches user-approved decisions from Phase 2
• No template placeholders remain

Fix any issues before proceeding.

4.2 Documentation Review

Run documentation-reviewer agent (spawn_agent, sonnet) on the project. Fix critical and major findings. Minor findings — fix or leave at your discretion.

4.3 Show Files

Show user the list of created files with links. Include ux-guidelines.md and backlog file if they were created. Ask if everything is correct or needs changes.

4.4 Iterate

• Changes requested → edit files → show updated list → repeat
• Questions → answer → continue waiting for approval
• Repeat until user approves

4.5 Commit

After approval, ask user if they want to commit. If yes — commit all created documentation files.

Final message (in the user's language): "Documentation is complete — you can start development."