After starting Claude Code, create a small set of canonical artifacts. `CLAUDE.md` defines working rules, `SPEC.md` describes the project contract, `TASK_SPEC.md` bounds one task, `EVIDENCE.md` stores observed facts, and `RUNBOOK.md` records delivery history. The `docs/` files define the working order, future sprint contracts, and decision records.
# YourProjectName — project working rules
## 1. Baseline status
This file is the stable operational contract for people and AI assistants.
- **Product / MVP:** \`Waiting for MVP input\`
- **Stack / architecture:** \`Waiting for MVP input\`
- **Sprint dates and owners:** \`Waiting for MVP input\`
- **Current phase:** governance setup only
Do not invent YourProjectName behavior, users, metrics, stack, architecture, tests, deployment, production readiness, or user validation before an approved MVP specification exists.
## 2. Canonical artifacts
| Artifact | Canonical path | Responsibility | Update rule |
|---|---|---|---|
| Project contract | \`SPEC.md\` | Durable specification of the problem, user, outcome, scope, and acceptance | Edit after an agreed contract change |
| Task contract | \`TASK_SPEC.md\` | Contract for one small, verifiable piece of work | Update before work starts and when scope changes |
| Evidence | \`EVIDENCE.md\` | Factual log of verified results | Append only; never replace it with a plan or narration |
| Delivery history | \`RUNBOOK.md\` | Operational history, decisions, blockers, and handoff | Append only after factual verification |
| Sprint convention | \`docs/sprints/README.md\` | Format for future S1–S3 plans | Change only with a governance decision |
| Decision convention | \`docs/decisions/README.md\` | Format for stack, architecture, and scope decisions | Add a separate record for each decision |
Do not create parallel canonical names (\`EVIDENCE_LOG.md\`, \`docs/SPEC.md\`, or duplicate templates) without a separate decision record. In this project, \`EVIDENCE.md\` is the canonical evidence path.
## 3. Statuses and metadata
Every durable artifact must include: \`ID\`, \`Version\`, \`Status\`, \`Owner\`, \`Date\`, and \`Related artifacts\`.
Use these statuses:
- \`Draft\` — created but not approved;
- \`Ready\` — the contract is approved and work may begin;
- \`Active\` — work is in progress;
- \`Verified\` — the result is confirmed by fresh evidence;
- \`Superseded\` — replaced by a newer version.
Use separate markers for values inside documents: \`Confirmed\`, \`Assumption\`, \`Unknown\`, \`Needs verification\`, \`Blocked\`, and \`Waiting for MVP input\`.
A template, documented example, catalog entry, or plan text is not proof that a physical file exists, a command ran, or a result is high quality.
## 4. Controlled AI workflow
Before every change:
1. Read the current tree, related artifacts, and affected paths.
2. Record the task ID, goal, allowed paths, expected diff, and targeted check in \`TASK_SPEC.md\`.
3. Confirm that the change supports the scope in \`SPEC.md\`.
During the work:
- make one bounded slice per iteration;
- do not add unrelated cleanup, redesign, or dependencies without a decision;
- do not change files outside the allowed paths;
- mark assumptions and Unknowns explicitly;
- do not read or write secrets or credentials without separate permission;
- stop when scope expands, the contract is unclear, or no verification oracle exists.
After a change, a human must inspect the diff and choose \`continue\`, \`revise\`, or \`HOLD\`. The absence of a model error is not evidence.
## 5. Acceptance, verification, and rollback
Every task must contain:
- observable acceptance criteria;
- targeted commands or manual checks;
- expected and observed results;
- a checkpoint after the slice;
- stop conditions;
- a rollback/recovery path.
Sprint decisions are \`DONE\`, \`CONTINUE WITH APPROVAL\`, or \`HOLD\`. For a demo, separate blocking checks, advisory checks, evidence anchors, and the claims boundary. Demo readiness is not deployment authorization.
Rollback must explain how to return to the latest verified state, who decides, and what evidence is required. Do not run production, publish, migration, or destructive commands without separate authorization.
## 6. Artifact rules
- \`SPEC.md\` is the contract for the problem, primary user/JTBD, value proposition, success metric, core flow, scope, non-goals, release slice, and acceptance. It is not a task plan or evidence.
- \`TASK_SPEC.md\` is the contract for a concrete task: owner, input, output, constraints, verification, checkpoint, exit, and rollback. Until the MVP is defined, it is an inactive template.
- \`EVIDENCE.md\` contains observed facts only: source, expected, observed, timestamp, status, and limitations. Never call a documented example completed execution.
- \`RUNBOOK.md\` is delivery and handoff history; it is not a full chat transcript, specification, or substitute for evidence.
- \`docs/sprints/\` contains only future S1, S2, and S3 plans after the SPEC and stack are approved. Each sprint has one observable outcome.
- \`docs/decisions/\` contains separate records with context, options, decision, rationale, consequences, owner, and a verification trigger.
## 7. Change control and reporting
Record scope, canonical-path, status, or decision changes before implementation and link them through IDs. Do not silently rewrite history. Append to Evidence and the RUNBOOK only after verification.
The final report for every piece of work must include:
1. changed files;
2. actual commands and their status;
3. evidence links/IDs;
4. unresolved Unknowns and blockers;
5. rollback or recovery note;
6. handoff and the next bounded action.
## 8. Verification order
While runtime and stack are not selected, use structural/content checks for Markdown and Git. After the stack is selected, the default order is:
\`\`\`text
check → validate → build → targeted tests → demo gate
\`\`\`
Do not report a command that was not run and do not replace \`Unknown\` with a plausible result.
# SPEC.md — YourProjectName project contract
- **ID:** \`SPEC-SEA-001\`
- **Version:** \`0.1.0\`
- **Status:** \`Draft\`
- **Owner:** \`Waiting for MVP input\`
- **Date:** 2026-09-21
- **Related artifacts:** [\`CLAUDE.md\`](CLAUDE.md), [\`TASK_SPEC.md\`](TASK_SPEC.md), [\`EVIDENCE.md\`](EVIDENCE.md), [\`RUNBOOK.md\`](RUNBOOK.md)
> This document is a reviewer-oriented contract shell. MVP input has not been provided. Unfilled fields are \`Unknown\`, not assumptions about the product.
## Problem
\`Unknown — Waiting for MVP input.\`
## Primary user
\`Unknown — Waiting for MVP input.\`
## User / JTBD
- **When:** \`Unknown\`
- **I want to:** \`Unknown\`
- **So I can:** \`Unknown\`
- **Constraints:** \`Unknown\`
- **Evidence status:** \`Waiting for MVP input\`
## Value proposition
- **Problem:** \`Unknown\`
- **Alternative today:** \`Unknown\`
- **Promised outcome:** \`Unknown\`
- **Proof signal:** \`Unknown\`
- **Claims excluded until verified:** adoption, production impact, scalability, revenue, and user validation.
## Desired outcome
\`Unknown — do not define the product feature-first; start with one bounded outcome.\`
## Success metric
| Field | Value |
|---|---|
| Name | \`Unknown\` |
| Unit | \`Unknown\` |
| Baseline | \`Unknown\` |
| Target | \`Unknown\` |
| Observation window | \`Unknown\` |
| Collection method | \`Unknown\` |
| Guardrail metric | \`Unknown\` |
| Status | \`Waiting for MVP input\` |
## Core flow
\`Unknown — trigger → AI-assisted/product step → human checkpoint → observable result\`.
## Scope
### In scope
- One bounded MVP release slice after MVP input is received and approved.
- Only the behavior needed to verify the defined outcome.
### Non-goals
- Selecting a stack or architecture before a decision record.
- Creating three sprint plans before MVP scope is approved.
- Autonomous approval, merge, or deployment.
- Production readiness, scaling, billing, additional integrations, and broad roles unless required by the core flow.
## Release slice
\`Unknown — define after user, JTBD, core flow, and success signal are recorded.\`
## Acceptance criteria
1. The primary user, JTBD, outcome, and scope boundaries are recorded in this SPEC.
2. The release slice has observable acceptance and a reproducible verification path.
3. Every task has a bounded contract in \`TASK_SPEC.md\` or a linked task record.
4. Every claim has evidence in \`EVIDENCE.md\`.
5. Unverified claims are marked \`Unknown\` or \`Needs verification\`.
**Current acceptance status:** \`Blocked — Waiting for MVP input\`.
## Verification plan
Before MVP input arrives: structural/content review of the documents and Git status.
After MVP input arrives: targeted checks, tests, a demo quality gate, and handoff defined by sprint/task contracts. Commands are currently \`Unknown\` because the stack has not been selected.
## Assumptions
- The project should use AI-assisted delivery with human checkpoints. \`Assumption — confirm with the owner.\`
- The MVP will consist of three sprints, according to the intake note. \`Waiting for MVP input.\`
## Open decisions
- What is the product and its bounded core flow?
- Who is the primary user and decision owner?
- Which stack and architecture satisfy the MVP constraints?
- What are the metric baseline, target, and observation window?
- Which verification levels are required for each slice?
## MVP input gate
Do not start product implementation until the owner provides an MVP specification and the user/JTBD, outcome, scope/non-goals, acceptance, success metric, constraints, and three-sprint delivery approach are agreed.
# TASK_SPEC.md — bounded task contract
- **ID:** \`TASK-SEA-TEMPLATE-001\`
- **Version:** \`0.1.0\`
- **Status:** \`Draft\`
- **Owner:** \`Waiting for MVP input\`
- **Date:** 2026-09-21
- **Related artifacts:** \`CLAUDE.md\`, \`SPEC.md\`, \`EVIDENCE.md\`, \`RUNBOOK.md\`
> \`Template — no active task.\` This file describes the executor contract; it does not invent work. Fill it for a concrete bounded slice or create a linked task record using the same contract.
## Goal and linked outcome
- **Goal:** \`Waiting for MVP input\`
- **SPEC outcome:** \`SPEC-SEA-001 / desired outcome — Unknown\`
- **Current/desired behavior:** \`Unknown\`
## Owner and allowed paths
- **Owner:** \`Waiting for MVP input\`
- **Allowed paths:** \`Unknown — define before the iteration starts\`
- **Affected paths:** \`Unknown\`
## Inputs and constraints
- **Inputs:** \`MVP specification — pending\`
- **Constraints:** do not select a stack without a decision record; do not expand scope; do not read or write secrets; do not add unrelated cleanup.
- **Dependencies:** \`Unknown\`
## Expected output
\`Unknown — define the concrete reviewable increment after MVP input.\`
## In scope
\`Unknown — Waiting for MVP input.\`
## Non-goals
- Any changes outside the allowed paths.
- Redesign or broad cleanup not required by acceptance.
- Claims about deployment, production readiness, adoption, or user validation.
## Acceptance criteria
- [ ] Observable result is stated in behavioral terms.
- [ ] Scope and non-goals agree with \`SPEC-SEA-001\`.
- [ ] A verification command/manual check has an expected signal.
- [ ] An evidence entry links to the task ID.
- [ ] A human checkpoint is completed before continuing.
**Current acceptance status:** \`Blocked — no active task until MVP input.\`
## Verification
- **Targeted command:** \`Unknown — stack not selected\`
- **Manual check:** inspect the diff, acceptance, evidence anchor, and absence of scope drift.
- **Expected result:** \`Unknown\`
- **Observed result:** \`Not run\`
## Checkpoint and stop conditions
- **Checkpoint:** inspect the diff and targeted signal after every slice.
- **Stop when:** scope expands; the contract is unclear; affected paths are unexpected; the verification oracle is unavailable; rollback is undefined; or an unapproved dependency is needed.
- **Exit decision:** \`HOLD — waiting for MVP input\`
## Risks and open questions
- Product outcome, stack, architecture, owners, and acceptance are undefined.
- It is not yet clear which checks are blocking, advisory, or demo-only.
## Rollback / recovery
Before an active task exists: do not make product changes. For future work, describe the return to the latest \`Verified\` state, the rollback decision owner, and the evidence confirming recovery.
## Handoff
Next action: obtain the MVP specification, then create a concrete task contract and decision records before implementation.
# EVIDENCE.md — factual evidence ledger
- **ID:** \`EVIDENCE-SEA-001\`
- **Version:** \`0.1.0\`
- **Status:** \`Active\`
- **Owner:** \`Waiting for MVP input\`
- **Date:** 2026-09-21
- **Related artifacts:** \`CLAUDE.md\`, \`SPEC.md\`, \`TASK_SPEC.md\`, \`RUNBOOK.md\`
## Purpose and boundary
This is the canonical, append-only log of factual checks. A plan, template, documented example, or chat text is not evidence. Every entry must separate expected from observed and mark Unknowns.
Do not mix this file with \`RUNBOOK.md\` or rename it to \`EVIDENCE_LOG.md\` without a separate decision record.
## Entry schema
Every entry uses:
- **Evidence ID**
- **Related SPEC/TASK ID**
- **Claim under verification**
- **Source** — command, file, diff, log, or screenshot
- **Expected**
- **Observed**
- **Timestamp / environment**
- **Status** — \`PASS\`, \`FAIL\`, \`BLOCKED\`, \`UNKNOWN\`, \`SUPERSEDED\`
- **Reviewer / owner**
- **Limitations and follow-up**
## Evidence entries
### E-SEA-001 — initial repository baseline
- **Related SPEC/TASK ID:** \`SPEC-SEA-001\`; \`TASK-SEA-TEMPLATE-001\`
- **Claim under verification:** the repository begins without product implementation and requires governance setup.
- **Source:** initial tree inspection and the temporary intake note read during setup.
- **Expected:** the current tree contains only the pre-existing intake note and IDE metadata; no runtime or product implementation is claimed.
- **Observed:** before setup, the temporary intake note and \`.idea/\` were present; no source, tests, build manifest, Git metadata, or project rules were present.
- **Timestamp / environment:** 2026-09-21; macOS; local YourProjectName workspace.
- **Status:** \`PASS\`
- **Reviewer / owner:** \`Pending owner review\`
- **Limitations and follow-up:** this verifies only the initial structural baseline; it proves no product behavior, stack, deployment, user validation, or production readiness.
### E-SEA-002 — governance baseline verification
- **Related SPEC/TASK ID:** \`SPEC-SEA-001\`; \`TASK-SEA-TEMPLATE-001\`
- **Claim under verification:** canonical governance artifacts and future-work conventions are present without speculative MVP content.
- **Source:** \`find\`, \`git status --short\`, and a Python structural/content checklist run after creating the baseline.
- **Expected:** required canonical files exist; MVP, stack, architecture, sprint tasks, and product claims remain pending or Unknown.
- **Observed:** all required canonical files and directories were present; sprint files, a legacy evidence alias, and a duplicate specification path were absent; required headings were found; the temporary intake note remained pending owner decision.
- **Timestamp / environment:** 2026-09-21; macOS; local YourProjectName workspace.
- **Status:** \`PASS\`
- **Reviewer / owner:** \`Pending owner review\`
- **Limitations and follow-up:** Git status was inspected but files are not committed; no runtime checks exist yet.
# RUNBOOK.md — delivery history and handoff
- **ID:** \`RUNBOOK-SEA-001\`
- **Version:** \`0.1.0\`
- **Status:** \`Active\`
- **Owner:** \`Waiting for MVP input\`
- **Date:** 2026-09-21
- **Related artifacts:** \`CLAUDE.md\`, \`SPEC.md\`, \`TASK_SPEC.md\`, \`EVIDENCE.md\`
## Purpose and boundary
\`RUNBOOK.md\` is append-only operational history. It records goals, commands, decisions, blockers, recovery, and handoff for a new operator. It is not the project specification, the evidence ledger, or a full chat transcript.
## Entry format
Each entry includes: date/session, goal and scope, changed artifacts, commands and actual status, decisions and rationale, blockers/Unknowns, rollback or recovery, evidence links, handoff, and next action.
## Entries
### 2026-09-21 — governance baseline setup
- **Session:** initial YourProjectName project setup.
- **Goal and scope:** create project-management infrastructure before MVP implementation; preserve a bounded AI workflow and explicit evidence boundary.
- **Changed artifacts:** created \`CLAUDE.md\`, \`SPEC.md\`, \`TASK_SPEC.md\`, \`EVIDENCE.md\`, this \`RUNBOOK.md\`, \`docs/README.md\`, \`docs/sprints/README.md\`, \`docs/decisions/README.md\`, and \`.gitignore\`; initialized Git. The temporary intake note remains pending an explicit owner decision.
- **Commands and status:** \`git init\` — \`PASS\`; \`find\`/\`git status --short\`/Python structural-content checklist — \`PASS\`; temporary intake note deletion — \`BLOCKED by explicit-permission requirement\`.
- **Decisions:** \`EVIDENCE.md\` is this project's canonical evidence path; no stack, architecture, sprint task, product behavior, or metric was invented; future work is exactly three sprint plans after MVP input and approval.
- **Blockers / Unknowns:** MVP specification, primary user/JTBD, outcome, success metric, constraints, owner, stack, and architecture are pending.
- **Rollback / recovery:** restore the pre-setup workspace only if the owner explicitly requests it; otherwise revert setup changes through Git after inspecting the diff. No product code or destructive operation was performed.
- **Evidence:** \`E-SEA-001\` records the initial structural baseline; \`E-SEA-002\` remains \`UNKNOWN\` until checks run.
- **Handoff:** owner to provide the MVP specification. Next bounded action: update \`SPEC.md\`, create stack/architecture decision records, then decompose approved scope into S1–S3.
# Project documentation
## Canonical records
- [\`../CLAUDE.md\`](../CLAUDE.md) — stable rules for AI-assisted work and artifact governance.
- [\`../SPEC.md\`](../SPEC.md) — durable project contract.
- [\`../TASK_SPEC.md\`](../TASK_SPEC.md) — current bounded task contract/template.
- [\`../EVIDENCE.md\`](../EVIDENCE.md) — append-only factual verification ledger.
- [\`../RUNBOOK.md\`](../RUNBOOK.md) — append-only delivery history and handoff.
- [\`sprints/README.md\`](sprints/README.md) — format for the future three sprint plans.
- [\`decisions/README.md\`](decisions/README.md) — format for stack, architecture, and scope decisions.
## Working order
1. Read the current tree and \`CLAUDE.md\`.
2. Update \`SPEC.md\` only when product input or an approved decision changes the project contract.
3. Fill \`TASK_SPEC.md\` for one bounded slice before implementation.
4. Verify with targeted checks and record observed results in \`EVIDENCE.md\`.
5. Append the operational result and handoff to \`RUNBOOK.md\`.
There is one canonical path per artifact. Templates and examples must not diverge from the canonical records.
## Current gate
MVP input is pending. No implementation, stack selection, or sprint-specific plan is authorized by the current project documents.
# Sprint planning convention
- **ID:** \`SPRINT-GOV-001\`
- **Version:** \`0.1.0\`
- **Status:** \`Draft\`
- **Owner:** \`Waiting for MVP input\`
- **Date:** 2026-09-21
## Boundary
YourProjectName will be decomposed into exactly three MVP sprints only after \`SPEC.md\` is populated and the stack/architecture decisions are approved. Until then, \`S1\`, \`S2\`, and \`S3\` plan files intentionally do not exist.
## Required sprint contract
Each future \`S1\`, \`S2\`, or \`S3\` record must contain:
- one observable outcome and explicit non-goals;
- linked SPEC and task IDs;
- ordered small slices with owner, input, and expected output;
- allowed/affected paths and dependencies;
- a verification command or manual check for every slice;
- a checkpoint after each slice and human diff review;
- blocking versus advisory demo checks;
- readiness assumptions, safe fixtures, fallback, and blocking Unknowns;
- a rollback/recovery path;
- an exit decision: \`DONE\`, \`CONTINUE WITH APPROVAL\`, or \`HOLD\`;
- evidence links and a RUNBOOK handoff, including on \`HOLD\`.
## Creation gate
Create sprint files only when the owner approves the MVP contract, success metric, stack decision, architecture decision, and three-sprint boundaries. Do not fill dates, tasks, or technical choices from assumptions.
# Decision records
- **ID:** \`DECISIONS-GOV-001\`
- **Version:** \`0.1.0\`
- **Status:** \`Draft\`
- **Owner:** \`Waiting for MVP input\`
- **Date:** 2026-09-21
## Decision record format
Create one record per material stack, architecture, integration, or scope decision. Each record must include:
- decision ID, version, date, status, and owner;
- context and constraints;
- options considered, including why an option was not selected;
- chosen option and rationale;
- consequences, risks, and deferred work;
- verification or revisit trigger;
- linked SPEC, TASK, EVIDENCE, and RUNBOOK records.
A catalog entry or chat statement is not a decision. Do not select a technology until the MVP constraints are known and the record is reviewed.
## Pending decisions
| Decision | Status | Required input |
|---|---|---|
| Stack selection | \`Waiting for MVP input\` | MVP outcome, constraints, delivery environment, and verification needs |
| Architecture boundary | \`Waiting for MVP input\` | Core flow, data boundaries, integrations, and non-goals |
| Sprint allocation | \`Waiting for MVP input\` | Approved release slice and exactly three sprint outcomes |
Future records should use \`docs/decisions/DEC-<number>-<short-name>.md\` and update this index after verification.