init

Greenfield Project Documentation Scaffolding

You are scaffolding documentation for a new project. Your job is to gather context from the user, then generate a complete documentation foundation.

Phase 1: Gather Context

Start by understanding what the user has provided. The user may supply anywhere from a single sentence to extensive detail. Adapt accordingly.

Minimum Required

You need at least one of these before generating anything:

• Project description — what the project does or will do
• Pain point / problem statement — what problem the project solves

If the user hasn't provided either, ask a single direct question:

What does this project do, or what problem does it solve?

Optional Context (don't ask unprompted — use if provided)

Baseline Product References

When the user references an existing product or project as a baseline for their idea — phrases like "like Y but with X", "similar to Y except", "Y-inspired", "based on Y" — treat this as a signal to narrow focus:

1. Acknowledge the reference and note the baseline product name.
2. Respond with: "You can use /greenfield-start:research <Y> later to fill in the baseline features provided by Y. For now, let's focus on what makes your project unique — the things that excited you about this idea."
3. Continue the conversation focused on the delta: the novel features, the insight, the differentiators. Do not attempt to capture Y's feature set.
4. In generated documentation, record the reference where appropriate:
   • product-brief.md may note "Inspired by Y" in the vision or background section
   • requirements.md may note which feature areas are expected to align with Y's baseline, using HTML comment placeholders (<!-- baseline features — run /greenfield-start:research Y -->) rather than attempting to enumerate them

The user may also supply any of the following. Use whatever is provided to populate the corresponding documents more thoroughly:

• Technology choices or constraints — languages, frameworks, infrastructure decisions and their rationale
• Feature requirements — what the system needs to do, at any level of detail
• Architecture or component descriptions — how things connect
• Implementation phases or roadmap — how the work is sequenced
• Coding conventions — language standards, testing practices, style preferences
• Non-goals — what the project explicitly won't do
• Target users — who this is for

If the user provides extensive context, extract and organize it into the appropriate documents. If they provide minimal context, generate structural templates with placeholder sections they can fill in later.

Phase 2: Generate Documentation

Generate all files below into the current working directory. Use the Write tool for each file.

Before writing, check for existing files. If any target files already exist, inform the user and ask whether to overwrite or skip them.

File: CLAUDE.md

# [Project Name]

You must start by reading the project's [README](README.md).

File: README.md

Generate based on context provided. Structure:

# [Project Name]

[1-2 sentence project description derived from user input]

## Getting Started

[If roadmap exists: "Read the [roadmap](docs/roadmap.md) for the implementation sequence."]
[If architecture exists: "Read the [architecture](docs/architecture.md) overview before writing code."]
[If neither: "Read the [product brief](docs/product-brief.md) for project context."]

## Documentation

| Document | Purpose |
|---|---|
| [Product Brief](docs/product-brief.md) | Problem statement, vision, goals, non-goals |
| [Architecture](docs/architecture.md) | System overview and technology decisions |
| [Requirements](docs/requirements.md) | What to build, prioritized |
| [Roadmap](docs/roadmap.md) | Phased implementation plan |
| [Conventions](docs/conventions.md) | Coding standards and common pitfalls |
| [Documentation Philosophy](docs/documentation-philosophy.md) | How to write and organize docs |
| [Decision Records](docs/decisions/) | Architecture decision log |
| [Implementation Guides](docs/guides/) | Component-specific implementation details |

## Project Structure

[If the user described components or a directory layout, include it here. Otherwise omit this section entirely — don't generate a speculative structure.]

File: docs/documentation-philosophy.md

Write this file verbatim — it is the canonical documentation philosophy:

# Documentation Philosophy

This document governs how documentation is written and organized in this project. All contributors — human and agent — follow these rules.

## Core Axiom

There is no distinction between human developers and coding agents. README.md is the starting place for everyone.

Agent-specific instruction files (CLAUDE.md, AGENTS.md, etc.) must contain only a single directive pointing to README.md. The sole exception: skill, agent, command, and asset files — whether part of a coding agent plugin or project-level tooling (e.g., documentation maintenance skills in `.claude/skills/`).

## Writing Style

- Be concise and direct. Assume competence.
- Lead with the actionable information. Background and rationale follow, not the other way around.
- Avoid duplicating content across files. Link instead.

## Organization

### Separate by Domain

Each documentation need gets its own file: project description, product requirements, feature roadmap, coding conventions, decision records, implementation guides, etc. Do not combine unrelated domains into a single document.

### Progressive Disclosure

Cognitive overload is a real concern for both humans and agents.

- **Top-level documents** contain concise, globally applicable directives and summaries.
- **Subdirectories and linked files** hold extensive instructions, details, and background.
- Use inline links next to directives when a single reference suffices (e.g., "Follow the [pull request process](guides/pr-process.md)").
- Use a markdown table as a directory index when listing multiple documents by topic (e.g., a decision log with columns for topic, decision, date, and slug).

### File Naming

Use `kebab-case.md` for documentation file names. `SCREAMING_CASE.md` is reserved for root-level tool files where the convention is expected (README.md, CLAUDE.md, AGENTS.md, etc.).

### File Prefixes

Prefer date prefixes (`YYYY-MM-DD-slug.md`) over monotonic counters (`001-slug.md`) for sequenced documents like decision records. Counter prefixes are problematic when documents are created in parallel branches — what do multiple decision documents sharing the same numerical prefix mean? Are they correlated or just a merge conflict? Date prefixes carry real information and tolerate concurrent creation gracefully — multiple documents sharing a date have a simple interpretation: they were simply created around the same time.

## Documentation Maintenance

Documentation is a living artifact, not a write-once deliverable. As work is planned and executed, the corresponding documentation must be updated to reflect current reality. Stale documentation is worse than no documentation — it actively misleads.

### When to Update

- **Planning**: When new work is planned, update roadmap phases, requirements, and architecture as needed.
- **Implementation**: When work completes a requirement or acceptance criterion, mark it done. When patterns emerge, add them to conventions.
- **Decisions**: When a technical decision is made, create a decision record immediately — not after the fact.

### Per-Document Maintenance

Each document type has specific maintenance instructions in a corresponding skill file. These skills contain the detailed process, templates, and rules for keeping each document current.

| Document | Maintenance Skill |
|---|---|
| [Roadmap](roadmap.md) | [.claude/skills/maintain-roadmap.md](../.claude/skills/maintain-roadmap.md) |
| [Requirements](requirements.md) | [.claude/skills/maintain-requirements.md](../.claude/skills/maintain-requirements.md) |
| [Architecture](architecture.md) | [.claude/skills/maintain-architecture.md](../.claude/skills/maintain-architecture.md) |
| [Conventions](conventions.md) | [.claude/skills/maintain-conventions.md](../.claude/skills/maintain-conventions.md) |
| [Decision Records](decisions/) | [.claude/skills/maintain-decisions.md](../.claude/skills/maintain-decisions.md) |
| [Implementation Guides](guides/) | [.claude/skills/maintain-guides.md](../.claude/skills/maintain-guides.md) |

File: docs/product-brief.md

If the user provided a problem statement or pain point, write a real product brief with these sections:

# Product Brief

## Problem Statement

[Derived from user input — what pain exists and why current approaches fall short]

## Vision

[1-2 sentences on what success looks like]

## Goals

[Numbered list of concrete goals derived from user input]

## Non-Goals

[If user provided non-goals, list them. Otherwise include this placeholder:]
<!-- Define what this project explicitly will NOT do. -->

## Target User

[If user described who this is for, write it. Otherwise omit this section.]

## Success Criteria

[If derivable from user input, list measurable outcomes. Otherwise include this placeholder:]
<!-- Define how you know the project succeeded. -->

If the user provided only a short description, still generate the brief but keep sections proportionally short. Use <!-- placeholder --> HTML comments for sections that need future input — never leave visible "TODO" markers.

File: docs/architecture.md

If the user provided technology decisions or component descriptions, generate a populated architecture doc:

# Architecture

## System Overview

[Diagram or prose describing how components relate. Use ASCII diagrams if the user described a multi-component system.]

## Technology Stack

| Component | Technology | Rationale |
|---|---|---|
| ... | ... | ... |

## Architecture Decisions

See [decisions/](decisions/) for the full decision log.

[List and link to any decision records generated.]

## Key Constraints

[If the user mentioned constraints, list them. Otherwise omit.]

If the user provided minimal context, generate a structural template:

# Architecture

## System Overview

<!-- Describe how the system's components relate to each other. -->

## Technology Stack

| Component | Technology | Rationale |
|---|---|---|

## Architecture Decisions

See [decisions/](decisions/) for the full decision log.

File: docs/requirements.md

If the user provided feature requirements, organize them with priority and phase columns:

# Requirements

Requirements are organized by component. Each requirement has a priority (P0 = must-have, P1 = high value, P2 = nice-to-have) and a phase reference from the roadmap.

---

## [Component Name]

| ID | Requirement | Priority | Phase |
|---|---|---|---|
| XX-01 | ... | P0 | 1 |

Use short uppercase prefixes for IDs derived from component names (e.g., CV for Canvas, AU for Auth).

If minimal context, generate the structural template with the header, priority legend, and one empty component section as an example.

File: docs/roadmap.md

If the user provided phases or implementation sequence:

# Roadmap

## Phasing Philosophy

[Derived from user input, or default: "Each phase delivers standalone value. Earlier phases establish patterns that later phases extend rather than replace."]

---

## Phase 1: [Name]

**Goal:** [What this phase achieves]

### Deliverables

[List of deliverables]

### Acceptance Criteria

- [ ] [Testable criterion]

### Dependencies

[What this phase needs]

---

[Additional phases as provided]

## Implementation Order

[If the user specified build order within phases, include it.]

If minimal context, generate:

# Roadmap

## Phasing Philosophy

Each phase delivers standalone value. Earlier phases establish patterns that later phases extend rather than replace.

---

<!-- Define phases below. Each phase should have: Goal, Deliverables, Acceptance Criteria, Dependencies. -->

File: docs/conventions.md

If the user specified languages, standards, or practices:

# Coding Conventions

## Languages and Configuration

[List languages, runtimes, config modes from user input]

## General Rules

[Derived from user input, or sensible defaults for the stated stack]

## Testing Standards

[If user provided testing practices, list them. Otherwise:]
<!-- Define testing standards: unit test expectations, E2E requirements, test runner, coverage thresholds. -->

## Common Pitfalls

<!-- Document known gotchas as they're discovered during implementation. -->

If minimal context:

# Coding Conventions

## Languages and Configuration

<!-- List languages, runtimes, and configuration modes. -->

## General Rules

<!-- Project-wide coding rules. -->

## Testing Standards

<!-- Define testing standards: unit test expectations, E2E requirements, test runner, coverage thresholds. -->

## Common Pitfalls

<!-- Document known gotchas as they're discovered during implementation. -->

Directory: docs/decisions/

Create docs/decisions/README.md:

If the user provided technology decisions, generate individual decision record files (docs/decisions/YYYY-MM-DD-slug.md) and populate the index:

# Architecture Decisions

| Topic | Decision | Date | Slug |
|---|---|---|---|
| [Topic] | [One-line summary] | [Today's date] | [link to file] |

Each decision record follows this format:

# [Topic]: [Decision]

**Decision:** [What was decided]

## Rationale

[Why this choice was made — from user input]

## Trade-offs Accepted

[What downsides were acknowledged]

If no decisions were provided, generate just the empty index:

# Architecture Decisions

| Topic | Decision | Date | Slug |
|---|---|---|---|

Directory: docs/guides/

Do not create placeholder guide files. Guides are created during implementation when component-specific details emerge. Just ensure the directory exists.

Directory: .claude/skills/

Generate documentation maintenance skills into .claude/skills/. These skills provide detailed instructions for keeping each document type current as the project evolves.

File: .claude/skills/maintain-roadmap.md

---
name: maintain-roadmap
description: Update roadmap.md when acceptance criteria are met, phases complete, or implementation sequence changes. Trigger after completing implementation work or planning sessions.
---

# Roadmap Maintenance

## When to Trigger

- After implementation work that completes one or more acceptance criteria
- After a phase is fully delivered
- When dependencies or sequencing between phases changes
- When new phases are added during planning

## Maintenance Process

### Marking Acceptance Criteria Complete

When work satisfies an acceptance criterion, change its checkbox from unchecked to checked:

- `- [ ] criterion` becomes `- [x] criterion`

### Marking a Phase Complete

When all acceptance criteria for a phase are checked, add a completion marker to the phase header:

- `## Phase 1: Foundation` becomes `## Phase 1: Foundation ✅`

### Adding New Phases

When planning introduces new phases, follow the existing phase template:

**Goal** — what this phase achieves.
**Deliverables** — list of concrete deliverables.
**Acceptance Criteria** — testable criteria as checkboxes.
**Dependencies** — what this phase requires from prior phases or external systems.

Place new phases in logical sequence. Update the Implementation Order section if one exists.

### Resequencing

If implementation reveals that phase order should change, update the phase numbers and the Implementation Order section. Add a decision record explaining why the sequence changed.

File: .claude/skills/maintain-requirements.md

---
name: maintain-requirements
description: Update requirements.md when features are implemented, new requirements emerge, or priorities shift. Trigger after completing features or during planning.
---

# Requirements Maintenance

## When to Trigger

- After implementing a requirement
- When new requirements are discovered during implementation
- When priorities shift (P0/P1/P2 changes)
- When requirements are split, merged, or removed

## Maintenance Process

### Marking Requirements Implemented

Add a Status column to track implementation state if one doesn't exist. When a requirement is implemented, mark it:

| ID | Requirement | Priority | Phase | Status |
|---|---|---|---|---|
| AU-01 | User authentication via OAuth | P0 | 1 | ✅ Done |
| AU-02 | Role-based access control | P1 | 2 | |

### Adding New Requirements

When implementation reveals new requirements:

1. Use the component's existing ID prefix (e.g., `AU` for Auth)
2. Assign the next sequential number within that component
3. Set priority based on impact (P0 = must-have, P1 = high value, P2 = nice-to-have)
4. Assign to the appropriate roadmap phase

If the requirement belongs to a new component, create a new section with an appropriate ID prefix.

### Removing or Deferring Requirements

Do not delete requirements. Instead:

- **Deferred**: Change the Phase to `deferred` and add a brief note why
- **Removed**: Change the Status to `Removed` and add a brief note why

This preserves the decision history.

File: .claude/skills/maintain-conventions.md

---
name: maintain-conventions
description: Update conventions.md when new coding patterns, standards, or pitfalls are established. Trigger when implementation reveals reusable patterns or common mistakes.
---

# Conventions Maintenance

## When to Trigger

- When a coding pattern is established that should be followed consistently
- When a pitfall or gotcha is discovered that others should know about
- When testing standards or practices evolve
- When new tools or libraries are adopted that have usage conventions

## Maintenance Process

### Adding a Convention

Add new conventions to the appropriate section in conventions.md. If no section fits, create one.

Conventions should be:

- **Specific and actionable** — "Use `zod` for all API input validation" not "Validate inputs"
- **Justified** — include a one-line rationale if the convention isn't obvious
- **Exemplified** — include a short code example for non-trivial patterns

### Adding a Pitfall

Add to the Common Pitfalls section:

- **[Brief description]** — [What goes wrong and how to avoid it]

### Updating Existing Conventions

When a convention changes (e.g., migrating from one library to another), update the existing entry rather than adding a new one. If the change is significant, also create a decision record.

File: .claude/skills/maintain-architecture.md

---
name: maintain-architecture
description: Update architecture.md when components are added or removed, technology choices change, or system relationships evolve. Trigger after architectural changes during implementation.
---

# Architecture Maintenance

## When to Trigger

- When a new component or service is introduced
- When a technology choice changes
- When component relationships or data flow changes
- When external integrations are added or modified
- When constraints change

## Maintenance Process

### Adding Components

Update the System Overview section to include the new component. If an ASCII diagram exists, update it to show the new component and its relationships.

### Updating the Technology Stack

Add or update rows in the Technology Stack table:

| Component | Technology | Rationale |
|---|---|---|
| [Component] | [Technology] | [Why this choice was made] |

If a technology replaces an existing one, update the row and create a decision record documenting the change.

### Updating System Overview

When the architecture evolves beyond what the overview describes, rewrite the overview to reflect current reality. The overview should always describe the system as it is, not as it was originally planned.

### Cross-References

When adding architectural components, check whether they need:

- New entries in requirements.md
- New or updated decision records
- Updates to the roadmap

File: .claude/skills/maintain-decisions.md

---
name: maintain-decisions
description: Create decision records when significant technical choices are made. Trigger when adopting technologies, choosing patterns, accepting trade-offs, or changing architectural direction.
---

# Decision Records Maintenance

## When to Trigger

- When choosing between alternative technologies or approaches
- When adopting a pattern that will be used project-wide
- When accepting a trade-off that constrains future work
- When reversing or modifying a previous decision
- When an external constraint forces an architectural change

## Maintenance Process

### Creating a Decision Record

Create a new file in `docs/decisions/` using today's date:

**Filename:** `YYYY-MM-DD-slug.md` (e.g., `2026-03-15-use-postgres-over-mysql.md`)

**Content:**

    # [Topic]: [Decision]

    **Decision:** [Clear statement of what was decided]

    ## Rationale

    [Why this choice was made — what factors were considered, what alternatives were evaluated]

    ## Trade-offs Accepted

    [What downsides or limitations were knowingly accepted]

### Updating the Index

Add a row to `docs/decisions/README.md`:

| Topic | Decision | Date | Slug |
|---|---|---|---|
| [Topic] | [One-line summary] | YYYY-MM-DD | [link to file] |

### Superseding Decisions

When a previous decision is reversed or modified:

1. Create a new decision record explaining the change
2. Add a note at the top of the original record: `> **Superseded by [new-decision](YYYY-MM-DD-slug.md)**`
3. Update both records in the index

File: .claude/skills/maintain-guides.md

---
name: maintain-guides
description: Create or update implementation guides when components have non-obvious setup, configuration, or usage patterns. Trigger after implementing components with noteworthy operational details.
---

# Implementation Guides Maintenance

## When to Trigger

- After implementing a component with non-obvious setup or configuration
- When a workflow requires multiple steps that should be documented
- When a component has operational details (deployment, monitoring, debugging) worth capturing
- When onboarding to a component requires context that isn't in the code itself

## Maintenance Process

### Creating a Guide

Create a new file in `docs/guides/`:

**Filename:** `kebab-case-component-name.md` (e.g., `auth-system.md`, `data-pipeline.md`)

**Content Structure:**

    # [Component Name] Guide

    ## Overview

    [1-2 sentences: what this component does and why it exists]

    ## Setup

    [Steps to get this component running locally or in a new environment]

    ## Usage

    [How to use this component — key APIs, entry points, common operations]

    ## Configuration

    [Environment variables, config files, feature flags]

    ## Troubleshooting

    [Common issues and their solutions]

Omit sections that don't apply. Not every guide needs every section.

### Updating the README

When creating a new guide, verify that the guides directory link is present in the Documentation table in README.md.

### Keeping Guides Current

When modifying a component that has an existing guide, check whether the guide still reflects reality. Update it if the setup, configuration, or usage has changed.

Phase 3: Summary

After generating all files, provide a concise summary:

Generated [N] files in [directory]:

- README.md
- CLAUDE.md
- docs/product-brief.md
- docs/documentation-philosophy.md
- docs/architecture.md
- docs/requirements.md
- docs/roadmap.md
- docs/conventions.md
- docs/decisions/README.md
[- docs/decisions/YYYY-MM-DD-*.md (if any)]
- .claude/skills/maintain-roadmap.md
- .claude/skills/maintain-requirements.md
- .claude/skills/maintain-conventions.md
- .claude/skills/maintain-architecture.md
- .claude/skills/maintain-decisions.md
- .claude/skills/maintain-guides.md

[If templates were generated with placeholders:]
Several documents contain placeholder sections. Fill them in as the project evolves,
or run this command again with more context to populate them.

Important Rules

• Never fabricate requirements, decisions, or architecture the user didn't describe. Templates with placeholders are better than invented content.
• Match depth to input. A one-sentence description produces concise docs with structural templates. A multi-paragraph brief produces thorough, populated docs.
• Use today's date for any decision record file prefixes.
• Create directories with mkdir -p before writing files into them (including .claude/skills/).
• HTML comments (<!-- -->) for placeholders, not visible TODO markers or bracket placeholders like [fill in later].
• Follow the documentation philosophy exactly — kebab-case filenames, progressive disclosure, no duplication, concise language.