project-structure

gvarela's avatarfrom gvarela

Enforces project documentation structure in docs/plans/ directories - research.md for facts, design.md for decisions, tasks.md for implementation, thoughts/ for explorations.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 10, 2025⬇️3downloads

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.
nameproject-structure
descriptionEnforces 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/