msd-core/get-shit-done/templates/project.md

PROJECT.md Template

Template for .planning/PROJECT.md - the full project context captured during initialization.

Greenfield Project (v1.0)

# [Project Name]

## Vision

[What this is and why it matters. 2-4 paragraphs capturing the full picture.
Use the user's language and framing. Include motivation, not just description.
This should feel like the user explaining their project to a smart collaborator.]

## Problem

[What problem exists, who has it, why it matters, what the current state is.
Be specific - vague problems lead to vague solutions.
Include the pain, the gap, or the opportunity that makes this worth building.]

## Success Criteria

How we know this worked:

- [ ] [Measurable outcome 1 - specific, verifiable]
- [ ] [Measurable outcome 2 - specific, verifiable]
- [ ] [Measurable outcome 3 - specific, verifiable]
- [ ] [Add as many as genuinely needed]

## Scope

### Building
- [Feature/capability 1]
- [Feature/capability 2]
- [Feature/capability 3]

### Not Building
- [Explicit exclusion 1 - prevents scope creep]
- [Explicit exclusion 2 - clarifies boundaries]
- [Explicit exclusion 3 - manages expectations]

## Context

[Background information that informs implementation:
- Current state (greenfield)
- Relevant prior work or experience
- Technical environment or ecosystem context
- Explored alternatives and why they were rejected]

## Constraints

- **[Constraint type]**: [What] - [Why]
- **[Constraint type]**: [What] - [Why]
- **[Constraint type]**: [What] - [Why]

Common types: Tech stack, Timeline, Resources, Dependencies, Compatibility, Performance, Security

## Decisions Made

Key decisions from project exploration:

| Decision | Choice | Rationale |
|----------|--------|-----------|
| [Area/Topic] | [What we decided] | [Why this choice] |
| [Area/Topic] | [What we decided] | [Why this choice] |

## Open Questions

Things to figure out during execution:

- [ ] [Question 1 - known unknown to resolve]
- [ ] [Question 2 - decision to make later]
- [ ] [Question 3 - area needing research]

---
*Initialized: [date]*

Brownfield Project (v1.1+)

After shipping v1.0, update PROJECT.md to include current state:

# [Project Name]

## Current State (Updated: YYYY-MM-DD)

**Shipped:** v[X.Y] [Name] (YYYY-MM-DD)
**Status:** [Production / Beta / Internal / Live with users]
**Users:** [If known: "~500 downloads, 50 DAU" or "Internal use only" or "N/A"]
**Feedback:** [Key themes from user feedback, or "Initial release, gathering feedback"]

**Codebase:**
- [X,XXX] lines of [primary language]
- [Key tech stack: framework, platform, deployment target]
- [Notable dependencies or architecture]

**Known Issues:**
- [Issue 1 from v1.x that needs addressing]
- [Issue 2]
- [Or "None" if clean slate]

## v[Next] Goals

**Vision:** [What's the goal for this next iteration?]

**Motivation:**
- [Why this work matters now]
- [User feedback driving it]
- [Technical debt or improvements needed]

**Scope (v[X.Y]):**
- [Feature/improvement 1]
- [Feature/improvement 2]
- [Feature/improvement 3]

**Success Criteria:**
- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]
- [ ] [Measurable outcome 3]

**Not Building (this version):**
- [Not doing X in this version]
- [Not doing Y in this version]

## Constraints

- **[Constraint type]**: [What] - [Why]
- **[Constraint type]**: [What] - [Why]

## Open Questions

- [ ] [Question for this version]
- [ ] [Question for this version]

---

<details>
<summary>Original Vision (v1.0 - Archived)</summary>

## Vision

[Original vision content]

## Problem

[Original problem statement]

## Success Criteria

- [x] [Outcome 1] - Achieved
- [x] [Outcome 2] - Achieved
- [x] [Outcome 3] - Achieved

## Scope

### Built
- [What was built]

### Not Built
- [What was excluded]

## Context

[Original context]

## Constraints

[Original constraints]

## Decisions Made

[Original decisions table]

</details>

**Greenfield:** - Don't compress - capture everything from questioning - Use user's words - preserve their language and framing - Be specific - vague inputs create vague outputs - Include rationale - "what" without "why" loses context - Mark unknowns - open questions are valuable, not failures

Brownfield:

• Current State shows real-world context (shipped, users, feedback)
• v[Next] Goals focuses on the upcoming work
• Original Vision collapsed in <details> for reference
• Checkboxes marked [x] for achieved goals
• This makes all plans brownfield-aware automatically

<state_summary> When creating STATE.md, extract a summary from PROJECT.md:

Building: [One-liner from Vision]

Core requirements:

• [Top 3 from Success Criteria]

Constraints:

• [Key constraints]

This goes in STATE.md's immutable "Project Summary" section. </state_summary>