# PROJECT.md Template

Template for `.planning/PROJECT.md` — the living project context document.

<template>

```markdown
# [Project Name]

## What This Is

[Current accurate description — 2-3 sentences. What does this product do and who is it for?
Use the user's language and framing. Update whenever reality drifts from this description.]

## Core Value

[The ONE thing that matters most. If everything else fails, this must work.
One sentence that drives prioritization when tradeoffs arise.]

## Business Context

<!-- OPTIONAL — only for monetized or customer-facing projects. Delete this section otherwise. -->

- **Customer**: [Who pays / who uses — one line]
- **Revenue model**: [How it makes money — one line]
- **Success metric**: [The number that matters — one line]
- **Strategy notes**: [Link to external strategy doc, if any]

## Mode

<!-- The detected build mode-combination — recorded once here, read by every strategy/build skill so they adapt instead of re-detecting (see exploration-and-adaptability.md). -->

- **Origin:** [greenfield | brownfield-extend | rewrite/refactor]
- **Design input:** [none | a provided design to ingest, at `<path-or-link>` | an existing design system to honor] <!-- record the location ONCE here; ui-researcher / frontend-architecture / legacy-inventory all ingest the SAME design from this pointer -->
- **Code-quality baseline:** [clean | legacy-debt | vibe-coded-to-harden]
- **Combination:** [the named combination, e.g. "greenfield-rewrite + new-design + salvageable-old-code"]

## Sources

<!-- The literal sources this project grounds in — their LOCATIONS, so agents can explore them DIRECTLY (not just the distilled inventories). Recorded by the entry point / whenever a source is added. Read by `gsd_run query grounding required` (the `sources` field). Each line: - <kind> · <path-or-url> [— <note>]. Kinds: design · legacy · vibe · context-app. The provided design is also mirrored in ## Mode's Design input line. -->

- (none yet)

## Strategy Plan

<!-- The archetype-tailored strategy path for this project — written by new-project / new-milestone from the archetype + Mode, per strategy-flow.md. The recommended steps to run before/around the build loop; refreshed at milestone boundaries. Each step's status: recommended | done | skipped. -->

**Archetype:** [e.g. backend service · real domain · public+PII · deployed]

**Recommended path:** [the ordered strategy steps for this archetype, e.g. model-domain → recommend-architecture → security-strategy (L2) → testing-strategy → infrastructure-strategy → cicd-strategy → build]

| Step | Status |
|---|---|
| [model-domain] | [recommended] |
| [recommend-architecture] | [recommended] |

### Skip-ledger

<!-- A deliberately-declined recommended step. Enforcers treat a ledgered skip as a DECISION (note once, don't re-nag); new-milestone re-surfaces it only when scope makes it relevant again.
     EXACT format (the `—` is an em-dash, required — skill names contain hyphens, so the separator must be unambiguous):
     - <skill> — skipped (<reason>, <YYYY-MM-DD>)
     e.g.  - testing-strategy — skipped (throwaway prototype, 2026-06-23) -->

- (none yet)

## Requirements

### Validated

<!-- Shipped and confirmed valuable. -->

(None yet — ship to validate)

### Active

<!-- Current scope. Building toward these. -->

- [ ] [Requirement 1]
- [ ] [Requirement 2]
- [ ] [Requirement 3]

### Out of Scope

<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->

- [Exclusion 1] — [why]
- [Exclusion 2] — [why]

## Context

[Background information that informs implementation:
- Technical environment or ecosystem
- Relevant prior work or experience
- User research or feedback themes
- Known issues to address]

## Constraints

- **[Type]**: [What] — [Why]
- **[Type]**: [What] — [Why]

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

## Key Decisions

<!-- Decisions that constrain future work. Add throughout project lifecycle. -->

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |

---
*Last updated: [date] after [trigger]*
```

</template>

<guidelines>

**What This Is:**
- Current accurate description of the product
- 2-3 sentences capturing what it does and who it's for
- Use the user's words and framing
- Update when the product evolves beyond this description

**Core Value:**
- The single most important thing
- Everything else can fail; this cannot
- Drives prioritization when tradeoffs arise
- Rarely changes; if it does, it's a significant pivot

**Business Context:**
- Optional — only for monetized or customer-facing projects
- Delete the entire section for internal tools, experiments, or meta workspaces
- 4 fields max, one line each — a constraint reference, not a business plan
- Use **Strategy notes** to link out to a dedicated strategy doc rather than duplicating it here
- Informs requirement prioritization: features serving the customer/revenue model come first

**Mode:**
- The detected build mode-combination across three orthogonal dimensions (Origin × Design-input × Code-quality), per `exploration-and-adaptability.md`
- Detected per-area but summarized here for the project; downstream strategy/build skills read this instead of re-running `ls`-based detection
- Update it when the mode changes (e.g. a greenfield project gains a salvageable codebase, or a new design is provided)

**Requirements — Validated:**
- Requirements that shipped and proved valuable
- Format: `- ✓ [Requirement] — [version/phase]`
- These are locked — changing them requires explicit discussion

**Requirements — Active:**
- Current scope being built toward
- These are hypotheses until shipped and validated
- Move to Validated when shipped, Out of Scope if invalidated

**Requirements — Out of Scope:**
- Explicit boundaries on what we're not building
- Always include reasoning (prevents re-adding later)
- Includes: considered and rejected, deferred to future, explicitly excluded

**Context:**
- Background that informs implementation decisions
- Technical environment, prior work, user feedback
- Known issues or technical debt to address
- Update as new context emerges

**Constraints:**
- Hard limits on implementation choices
- Tech stack, timeline, budget, compatibility, dependencies
- Include the "why" — constraints without rationale get questioned

**Key Decisions:**
- Significant choices that affect future work
- Add decisions as they're made throughout the project
- Track outcome when known:
  - ✓ Good — decision proved correct
  - ⚠️ Revisit — decision may need reconsideration
  - — Pending — too early to evaluate

**Last Updated:**
- Always note when and why the document was updated
- Format: `after Phase 2` or `after v1.0 milestone`
- Triggers review of whether content is still accurate

</guidelines>

<evolution>

PROJECT.md evolves throughout the project lifecycle.
These rules are embedded in the generated PROJECT.md (## Evolution section)
and implemented by workflows/transition.md and workflows/complete-milestone.md.

**After each phase transition:**
1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

**After each milestone:**
1. Full review of all sections
2. Core Value check — still the right priority?
3. Business Context check (if present) — customer, revenue model, success metric still accurate?
4. Audit Out of Scope — reasons still valid?
5. Update Context with current state (users, feedback, metrics)

</evolution>

<brownfield>

For existing codebases:

1. **Onboard or map codebase first** via `/gsd:onboard` (recommended first-time path) or `/gsd:map-codebase`

2. **Infer Validated requirements** from existing code:
   - What does the codebase actually do?
   - What patterns are established?
   - What's clearly working and relied upon?

3. **Gather Active requirements** from user:
   - Present inferred current state
   - Ask what they want to build next

4. **Initialize:**
   - Validated = inferred from existing code
   - Active = user's goals for this work
   - Out of Scope = boundaries user specifies
   - Context = includes current codebase state

</brownfield>

<state_reference>

STATE.md references PROJECT.md:

```markdown
## Project Reference

See: .planning/PROJECT.md (updated [date])

**Core value:** [One-liner from Core Value section]
**Current focus:** [Current phase name]
```

This ensures Claude reads current PROJECT.md context.

</state_reference>