project-structure
Enforces project documentation structure in docs/plans/ directories - research.md for facts, design.md for decisions, tasks.md for implementation, thoughts/ for explorations.
When & Why to Use This Skill
The Project Structure skill enforces a rigorous documentation framework within the docs/plans/ directory to streamline the software development lifecycle. By systematically categorizing project information into facts (research.md), architectural decisions (design.md), actionable implementation steps (tasks.md), and creative explorations (thoughts/), it minimizes cognitive overhead and prevents documentation rot. This skill ensures that every team member has a clear, searchable, and organized source of truth for the 'what', 'why', and 'how' of any technical project.
Use Cases
- Standardizing New Project Kickoffs: Automatically establish a consistent directory structure for new features to ensure all research and design decisions are captured from day one.
- Architectural Decision Records (ADR): Utilize the design.md file to document technical trade-offs and rationales, providing a clear historical context for future maintenance and preventing repetitive debates.
- Streamlining Developer Onboarding: Provide new team members with a structured knowledge base where facts are separated from ongoing experiments, significantly reducing the time to first commit.
- Complex Task Decomposition: Convert high-level design goals into granular, executable steps in tasks.md to improve project tracking, execution accuracy, and code review efficiency.
- Managing Research and Discovery: Use research.md to consolidate external documentation and codebase facts, ensuring that implementation is based on verified data rather than assumptions.
| name | project-structure |
|---|---|
| description | Enforces project documentation structure in docs/plans/ directories - research.md for facts, design.md for decisions, tasks.md for implementation, thoughts/ for explorations. |
Project Structure
Document Separation
research.md - Facts only (internal codebase + external research)
- WHAT EXISTS: Current code, external patterns, options, capabilities
- NO decisions, NO rationale, NO implementation steps
design.md - Decisions + rationale only
- WHAT to build, WHY chosen
- Architectural decisions, trade-offs, scope
- NO facts without decisions, NO implementation steps
tasks.md - Implementation only
- HOW to implement: specific steps, file changes, tests
- NO rationale, NO alternatives
thoughts/ - Explorations & refinements
- Questions, experiments, discussions
- Understanding refinements before decisions
- Informal notes, brainstorming
- Anything not ready for formal docs
Quick Check
- Decision? → design.md
- Fact/Option? → research.md
- Step/Code? → tasks.md
- Exploring/Unsure? → thoughts/