know-thy-build 0.1.0

package/README.md

@@ -0,0 +1,175 @@
+# know-thy-build
+
+Before you write a single line of code, know what you're building and why.
+
+**know-thy-build** is a Socratic questioning tool for [Claude Code](https://claude.ai/claude-code). Through conversation — not forms — it helps you define your project clearly: what problem you're solving, why your approach matters, what the deliverable looks like, and what principles guide the work. The result is a `PROJECT.md` that you and your AI agents can reference throughout the project's life.
+
+## Why
+
+We jump into code too fast. A new project starts, and within minutes we're picking frameworks, creating files, writing functions — before we've truly asked ourselves what we're building and why.
+
+The cost of skipping this step is real. Vague goals lead to wasted effort. Undefined boundaries lead to scope creep. Unspoken assumptions lead to wrong decisions — by you or by AI agents working on your behalf.
+
+know-thy-build exists to help you **think your project through before you build it**. It asks the questions you should be asking yourself: What problem am I really solving? Who is this for? What does success look like? What should this *not* be? The act of answering these questions — one at a time, out loud, with each answer challenged and deepened — is where project clarity comes from.
+
+**The real value is that you now understand what you're building** — because you were asked the right questions and had to find the answers yourself.
+
+And that clarity doesn't stay in your head. know-thy-build structures it into a `PROJECT.md` that AI agents can reference — so the understanding you gained carries over to every agent working on your project. They read the same problem definition, follow the same principles, and respect the same boundaries. Your thinking becomes their compass.
+
+## Quick start
+
+```bash
+npx know-thy-build
+```
+
+Pick a language, and two commands are installed into your project's `.claude/commands/`:
+
+| Command | Purpose |
+|---------|---------|
+| `/know-thy-build` | Define your project through guided conversation |
+| `/know-thy-build-evolve` | Revisit and evolve the definition as the project grows |
+
+Then, inside Claude Code:
+
+```
+/know-thy-build
+```
+
+## What happens
+
+A ~10 minute conversation. No forms. No questionnaires. One question at a time, each digging a layer deeper than the last.
+
+The conversation explores four areas — in whatever order feels natural:
+
+- **Problem** — What triggered this? Why is it a problem? What's the root cause? Who suffers? What are they doing today, and why isn't it enough?
+- **Vision** — What changes when this is solved? What's your approach? What does the user actually get? What's the core value in one word?
+- **Experience & Boundaries** — How does someone use this, end to end? What's the aha moment? What is this NOT? What's the minimum for v1.0?
+- **Principles** — What rules must never be broken? How autonomous should AI agents be? Where do you stand on speed vs quality?
+
+Not every area needs equal depth. Some projects need 5 minutes on the problem and 1 on principles. Others are the opposite. The conversation follows you, not a script.
+
+Progress is saved to `PROJECT.md` as you go. If the session breaks, `/know-thy-build` picks up where you left off.
+
+## What you get
+
+A `PROJECT.md` in your project root — only containing what was actually discussed:
+
+```markdown
+---
+status: complete
+version: 1.0.0
+---
+
+# my-project
+
+A CLI that does X — solving Y for Z through simplicity.
+
+## Problem
+...
+
+## Vision
+| Before | After |
+|--------|-------|
+| Manual, error-prone | Automated, reliable |
+
+## What We Build
+| | |
+|---|---|
+| **Deliverable** | ... |
+| **Form** | CLI (because ...) |
+
+## User Journey
+...
+
+## Principles
+### Test Before Merge (NON-NEGOTIABLE)
+...
+
+## Boundaries
+**This is NOT:** ...
+
+## Success
+**MVP:** ...
+**Success Signal:** ...
+```
+
+Plus a `CLAUDE.md` reference so AI agents read it before any work:
+
+```markdown
+## Project Definition
+This project follows the principles defined in PROJECT.md.
+AI agents MUST read PROJECT.md before starting any work.
+NON-NEGOTIABLE rules in PROJECT.md cannot be overridden.
+```
+
+## Evolving
+
+Projects change. What you thought you were building at day 1 is rarely what you're building at day 90.
+
+```
+/know-thy-build-evolve
+```
+
+This presents your current `PROJECT.md` and asks: does it still feel right?
+
+If yes — done. A confirmed definition is a valid outcome.
+
+If something has shifted, it walks you through:
+
+1. **What changed** — follow the thread from what's different → what happened → why → what was the original assumption → what do you know now
+2. **Principles** — did they survive contact with reality? Were they tested? Broken? Did new ones emerge?
+3. **Insights** — stepping back: what did you learn from this experience?
+4. **Update** — apply changes, bump the version, record everything in a changelog with reasoning
+
+The changelog captures not just *what* changed, but *why* — so you can look back at decisions later:
+
+```markdown
+## Changelog
+
+### v1.1.0 — 2026-03-15
+
+**What changed:**
+- Problem: was "X" → now "Y"
+
+**Why:**
+- Assumed users would Z, but they actually W
+
+**Principles:**
+- New: Always validate with real users — learned from shipping v1
+
+**Insights:**
+- We overestimated how much structure users wanted
+```
+
+## Session resilience
+
+Conversations can break mid-session. know-thy-build tracks state in `PROJECT.md` frontmatter:
+
+| `status` | What it means |
+|-----------|---------------|
+| `drafting` | Init in progress — `/know-thy-build` will resume |
+| `complete` | Definition is set — `/know-thy-build-evolve` is available |
+| `evolving` | Evolve in progress — `/know-thy-build-evolve` will resume |
+
+You never lose progress. Pick up where you left off.
+
+## What this project is
+
+know-thy-build helps you define your project well. It uses the Socratic method — asking the right questions in the right order — to draw out what you already know but haven't articulated yet. The result is a clear, concrete project definition that both you and AI agents can follow.
+
+It is **not** a project management framework. No PRDs, epics, stories, or sprint plans. No code scaffolding. No tech stack opinions. Just one thing: helping you think clearly about what you're building, and keeping that definition honest as the project evolves.
+
+## Language support
+
+```bash
+npx know-thy-build              # interactive prompt
+npx know-thy-build --lang ko    # Korean
+npx know-thy-build --lang ja    # Japanese
+npx know-thy-build --lang en    # English (default)
+```
+
+Supported shortcuts: `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de`, `pt` — or pass any language name directly.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+} from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { createInterface } from "readline";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const templatesDir = join(__dirname, "..", "templates");
+const targetDir = process.cwd();
+const COMMANDS_DIR = join(targetDir, ".claude", "commands");
+
+const LANG_OPTIONS = [
+  { key: "en", label: "English" },
+  { key: "ko", label: "Korean (한국어)" },
+  { key: "ja", label: "Japanese (日本語)" },
+  { key: "zh", label: "Chinese (中文)" },
+  { key: "es", label: "Spanish (Español)" },
+  { key: "fr", label: "French (Français)" },
+  { key: "de", label: "German (Deutsch)" },
+  { key: "pt", label: "Portuguese (Português)" },
+];
+
+function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function askLanguage() {
+  console.log("\n  What language should know-thy-build use?\n");
+  for (let i = 0; i < LANG_OPTIONS.length; i++) {
+    const opt = LANG_OPTIONS[i];
+    const marker = i === 0 ? " (default)" : "";
+    console.log(`    ${i + 1}) ${opt.label}${marker}`);
+  }
+  console.log(`    9) Other`);
+
+  const answer = await prompt("\n  > ");
+
+  if (!answer) return LANG_OPTIONS[0].label;
+
+  const num = parseInt(answer, 10);
+  if (num >= 1 && num <= LANG_OPTIONS.length) {
+    return LANG_OPTIONS[num - 1].label;
+  }
+  if (num === 9) {
+    const custom = await prompt("  Enter language name: ");
+    return custom || LANG_OPTIONS[0].label;
+  }
+
+  // Try matching by key or label
+  const lower = answer.toLowerCase();
+  const match = LANG_OPTIONS.find(
+    (o) => o.key === lower || o.label.toLowerCase().startsWith(lower)
+  );
+  return match ? match.label : answer;
+}
+
+function install(lang) {
+  if (!existsSync(COMMANDS_DIR)) {
+    mkdirSync(COMMANDS_DIR, { recursive: true });
+  }
+
+  const templates = readdirSync(templatesDir).filter((f) => f.endsWith(".md"));
+
+  for (const file of templates) {
+    const src = join(templatesDir, file);
+    let content = readFileSync(src, "utf-8");
+    content = content.replaceAll("{{LANG}}", lang);
+    const dest = join(COMMANDS_DIR, file);
+    writeFileSync(dest, content, "utf-8");
+  }
+
+  console.log(`
+  Done! (${lang})
+
+  Open Claude Code in this project and run:
+
+    /know-thy-build
+`);
+}
+
+// --- Main ---
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === "--help" || command === "-h") {
+  console.log(`
+  know-thy-build - Socratic project project definition tool
+
+  Usage:
+    npx know-thy-build              Interactive setup
+    npx know-thy-build --lang ko    Skip language prompt
+
+  Language shortcuts: ko, en, ja, zh, es, fr, de, pt
+`);
+  process.exit(0);
+}
+
+if (command === "--version" || command === "-v") {
+  const pkg = JSON.parse(
+    readFileSync(join(__dirname, "..", "package.json"), "utf-8")
+  );
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+// If --lang provided, skip prompt
+let lang = null;
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--lang" || args[i] === "-l") {
+    lang = args[++i];
+    break;
+  }
+  if (args[i].startsWith("--lang=")) {
+    lang = args[i].split("=")[1];
+    break;
+  }
+}
+
+if (lang) {
+  const lower = lang.toLowerCase();
+  const match = LANG_OPTIONS.find((o) => o.key === lower);
+  install(match ? match.label : lang);
+} else {
+  askLanguage().then((chosen) => install(chosen));
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "know-thy-build",
+  "version": "0.1.0",
+  "description": "Socratic project constitution generator for Claude Code",
+  "bin": {
+    "know-thy-build": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "templates/"
+  ],
+  "keywords": [
+    "claude-code",
+    "constitution",
+    "project-setup",
+    "ai-agent",
+    "socratic"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/know-thy-build-evolve.md

@@ -0,0 +1,280 @@
+---
+description: Revisit and evolve your PROJECT.md. Use when the project's direction has shifted, assumptions proved wrong, principles need updating, or scope has changed. Run this periodically or at major turning points.
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
+---
+
+# Know Thy Build — Evolve
+
+Projects change. The question is whether your compass changes with them, or quietly becomes fiction.
+
+This command revisits your PROJECT.md — not to check boxes, but to reflect on what you assumed, what actually happened, and what you've learned.
+
+## Language
+
+**All conversation and document updates MUST be in: {{LANG}}**
+
+Technical terms (e.g. CLI, API, NON-NEGOTIABLE) stay in English. Everything else — questions, summaries, output prose — uses the specified language.
+
+## How You Operate
+
+- Read the existing PROJECT.md first. This is the baseline.
+- One question at a time. Same Socratic discipline as init.
+- Don't accept "it's fine" at face value. Probe gently.
+- The user may not know what changed. Help them discover it.
+- **Iterative deepening**: Each question builds on the previous answer. Follow the thread N times until you reach the root, not just once. When the user says something interesting, ask about THAT, not the next item on a list.
+- The reasoning behind a change matters more than the change itself.
+- **Save progress as you go.** At each checkpoint, update PROJECT.md frontmatter so the session can be resumed if interrupted.
+
+---
+
+## Before You Begin
+
+Read the current state:
+
+```bash
+cat PROJECT.md 2>/dev/null
+cat CLAUDE.md 2>/dev/null
+```
+
+If `PROJECT.md` doesn't exist → tell the user to run `/know-thy-build` first. Stop.
+
+**If PROJECT.md has `status: drafting`:**
+The init process was never completed. Tell the user:
+> "PROJECT.md is still in draft from a previous session. Run `/know-thy-build` to finish it first."
+→ Stop here.
+
+**If PROJECT.md has `status: evolving`:**
+A previous evolve session was interrupted. Read the frontmatter to find `evolveProgress` and resume:
+> "We started an evolve session before. Here's where we left off: [summary of what was reviewed]. Shall we continue?"
+
+**If PROJECT.md has `status: complete`:**
+Present the current definition warmly:
+
+> "Here's what your project was defined as:"
+>
+> [Present the key identity from PROJECT.md — the one-liner, problem, vision, deliverable, core principles. Keep it concise but complete enough to jog memory.]
+>
+> "Looking at this now — does it still feel right? Or does something feel off?"
+
+This is deliberately soft. Let the user react naturally. Their response tells you where to go.
+
+**If the user confirms it still feels right:**
+
+> "Good — that's a meaningful signal too. Your compass held up."
+> "If something shifts in the future, you can run `/know-thy-build-evolve` again."
+
+→ **Stop here.** Do not push further. A confirmed compass is a valid outcome.
+
+**If the user expresses any doubt, discomfort, or points to something specific** → proceed to STEP 1.
+
+---
+
+## STEP 1: What wants to change?
+
+> **Goal**: Understand what the user feels has shifted, starting from their intuition.
+> **Gate**: At least one area of change is identified with enough depth to trace its origin.
+
+### Flow
+
+**Start from the user's response.** Don't impose a structure yet.
+
+**If the user points to something specific:**
+Follow that thread. Ask about it, not something else.
+
+**If the user says "mostly fine" or "I'm not sure":**
+Gently surface the assumptions baked into PROJECT.md:
+
+> "Your PROJECT.md assumed a few things:"
+>
+> [Extract 3-4 key assumptions from the actual PROJECT.md content, e.g.:]
+> - That {{problem_root}} is the core problem
+> - That {{who_suffers}} would use it as {{user_journey}}
+> - That {{mvp_criteria}} would be enough for v1.0
+>
+> "Have any of these played out differently than expected?"
+
+**If the user says "a lot has changed":**
+Don't try to cover everything. Ask:
+
+> "What's the biggest thing that changed?"
+
+Then follow THAT thread deeply before moving to the next.
+
+### Iterative deepening
+
+For each change the user raises, don't move on after one exchange. Follow the thread:
+
+1. **What changed?** — "What's different from what was written?"
+2. **What happened?** — "What did you experience that showed this?"
+3. **Why?** — "Why do you think it turned out that way?"
+4. **What was the original assumption?** — "Looking back, what were you assuming that turned out wrong?"
+5. **What do you know now?** — "If you were writing this section today, what would you say instead?"
+
+Not every change needs all 5. Use judgment. But always go at least to "why" before moving on.
+
+### Checkpoint
+
+Save progress to PROJECT.md frontmatter:
+```yaml
+status: evolving
+evolveProgress: changes-identified
+```
+
+After exploring enough changes (the user will signal when they're done, or the conversation will naturally slow):
+
+> "Here's what we've found:"
+>
+> **Changes:**
+> - {{what}}: was {{old}} → now {{new}}
+>   - Because: {{root_reason}}
+>   - Original assumption: {{what_was_assumed}}
+>
+> **Still holds:**
+> - {{what remains true}}
+>
+> "Does this capture it? Anything missing?"
+
+Confirmed → STEP 2.
+
+---
+
+## STEP 2: Principles — tested by reality
+
+> **Goal**: Confront each principle against what actually happened.
+> **Gate**: Principles reviewed and updated.
+
+### Flow
+
+Present the current principles from PROJECT.md:
+
+> "Let's look at the principles you set. Were they tested? Did they hold?"
+
+For each principle, one at a time:
+
+> "[Principle name]: [rule]"
+> "Did you actually follow this? Were there moments where it was hard?"
+
+Then follow the thread based on the answer:
+
+**If kept:**
+→ "Did it prove its value? Was there a moment where you were glad this rule existed?"
+→ "Has your understanding of WHY this matters deepened?"
+
+**If broken:**
+→ "What happened? What forced you to break it?"
+→ "Was the principle wrong, or was the situation exceptional?"
+→ "Should we change the principle, or keep it and learn from the exception?"
+
+**If untested:**
+→ "This hasn't been challenged yet. Do you still believe it? Or was it aspirational?"
+
+**Classification update:**
+- NON-NEGOTIABLE that was broken → should it become a GUIDELINE, or be reinforced?
+- GUIDELINE that proved critical → promote to NON-NEGOTIABLE?
+- Principle that no longer applies → remove with clear reasoning.
+
+**New principles:**
+> "Did you learn any new rules from doing the work? Things you'd tell yourself on day 1 if you could go back?"
+
+### Checkpoint
+
+> **Kept:** (unchanged)
+> - ...
+> **Updated:** (rewording or level change)
+> - {{principle}}: {{change}} — because {{reason}}
+> **Removed:**
+> - {{principle}} — because {{reason}}
+> **New:**
+> - {{principle}} — learned from {{experience}}
+
+Confirmed → STEP 3.
+
+---
+
+## STEP 3: Insights — what did you learn?
+
+> **Goal**: Capture the meta-learning from this evolution — not just what changed, but what the change teaches.
+> **Gate**: At least 1-2 insights articulated.
+
+### Flow
+
+> "Before we update the document — stepping back from the details: what did you learn from this experience?"
+
+Possible prompts if the user needs help:
+
+> "What surprised you most about how this project unfolded?"
+
+> "If you were starting a similar project tomorrow, what would you do differently from the start?"
+
+> "Is there a pattern here — something about how you plan vs how things actually go?"
+
+These insights get recorded in the changelog as lessons learned.
+
+→ `{{insights}}`
+
+---
+
+## STEP 4: Synthesis — Update PROJECT.md
+
+> **Gate**: User confirms the final changes before writing.
+
+### Pre-update
+
+Present a complete summary:
+
+> "Here's what will change in PROJECT.md:"
+>
+> **Sections being updated:**
+> - {{section}}: {{before}} → {{after}}
+>
+> **Principles:**
+> - {{changes_summary}}
+>
+> **Sections unchanged:**
+> - {{list}}
+>
+> "Ready to update?"
+
+### Apply changes
+
+Use the Edit tool. Preserve the structure and voice of the original. Only modify what changed.
+
+**Update frontmatter:**
+```yaml
+---
+status: complete          # back to complete after evolve
+version: {{new_version}}
+date: {{date}}
+lastEvolve: {{date}}
+---
+```
+
+**Version increment:**
+- Refinements → minor bump (1.0.0 → 1.1.0)
+- Fundamental shift in problem or vision → major bump (1.0.0 → 2.0.0)
+
+**Append changelog:**
+
+```markdown
+## Changelog
+
+### v{{version}} — {{date}}
+
+**What changed:**
+- {{section}}: {{change_summary}}
+
+**Why:**
+- {{assumption_or_reason}}: {{what_was_assumed}} → {{what_actually_happened}}
+
+**Principles:**
+- {{kept|updated|removed|new}}: {{principle_name}} — {{reason}}
+
+**Insights:**
+- {{insight}}
+```
+
+### Closing
+
+> "PROJECT.md has been updated."
+> "The changelog records not just what changed, but why — so you can look back at this decision later."
+> "Run `/know-thy-build-evolve` again whenever the project's direction shifts."

package/templates/know-thy-build.md

@@ -0,0 +1,287 @@
+---
+description: Define your project clearly — what it is, why it exists, and what it must become. Use when starting a new project or when you need to articulate the project's identity for AI agents to follow.
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
+---
+
+# Know Thy Build
+
+You are a Socratic facilitator. Your role is to help the user **discover what they truly want to build** — not through a questionnaire, but through dialogue that digs deeper with each exchange.
+
+## Language
+
+**All conversation, questions, checkpoints, and generated documents MUST be in: {{LANG}}**
+
+Technical terms (e.g. CLI, API, NON-NEGOTIABLE) stay in English. Everything else — questions, summaries, output prose — uses the specified language.
+
+## How You Operate
+
+- **One question at a time.** Never dump a list of questions.
+- **Reflect, then deepen.** Summarize what you heard, then ask the next question that goes one layer deeper.
+- **Don't accept the first answer.** The first answer is usually the surface. Ask "why" or "what happens then" to reach the root.
+- **When the user is unsure**, offer 2-3 concrete options to react to.
+- **Detect before asking.** Scan existing files first. Don't ask what's already visible.
+- **Follow the conversation, not the template.** The steps below are areas to explore, not a fixed sequence. If the user's answer naturally covers multiple areas, don't re-ask. If the user gives deep clarity on one area, don't force them through areas they've already answered. Only explore what's still unclear.
+- **Know when to stop.** If the user has articulated enough for a meaningful PROJECT.md, offer to generate. Don't drag the conversation past its natural end.
+
+---
+
+## Before You Begin
+
+Silently scan the project for existing context:
+
+```bash
+ls -la 2>/dev/null | head -20
+cat package.json pyproject.toml Cargo.toml go.mod README.md 2>/dev/null | head -80
+cat CLAUDE.md PROJECT.md 2>/dev/null
+```
+
+**If PROJECT.md exists with `status: complete`:**
+> "This project already has a compass defined. Would you like to revisit it? If so, `/know-thy-build-evolve` is designed for that."
+→ Stop here unless the user explicitly wants to start fresh.
+
+**If PROJECT.md exists with `status: drafting`:**
+This is a resumed session. Read the frontmatter to restore state:
+- `areasExplored` → what's already been discussed, don't re-ask
+- `areasRemaining` → what's still open
+- `lastCheckpoint` → where to pick up
+
+Present what was gathered so far (from the document body) and ask:
+> "We left off after exploring [lastCheckpoint]. Here's what we have so far: [brief summary]. Shall we continue from here?"
+
+**If the project has other context** (package.json, README, etc.) → acknowledge what you see and use it as a starting point. Don't re-ask things the files already answer.
+
+**If no PROJECT.md** → note the blank canvas and begin.
+
+---
+
+## Areas to Explore
+
+These are the areas that make up a complete project definition. Explore them **in whatever order the conversation naturally flows**. Some users will lead with the problem. Others will start with what they want to build. Follow them.
+
+### Problem — The root cause
+
+> What to discover: Why this project exists. What pain triggered it. What the root cause is, not just the symptom.
+
+Key threads to follow (use only what's needed):
+- What triggered this project? What discomfort or problem existed?
+- Why is that a problem? What goes wrong if it's not solved?
+- What's the root cause?
+- Who suffers from this the most?
+- How is it handled today? Why is that not enough?
+
+Slots to fill:
+- `{{problem_surface}}` → `{{problem_impact}}` → `{{problem_root}}`
+- `{{who_suffers}}`
+- `{{current_alternative}}`, `{{why_not_enough}}`
+
+**When to move on:** You can articulate the problem in 2-3 sentences and the user confirms.
+
+### Vision — What does success look like?
+
+> What to discover: The concrete change this project creates. The approach and core value.
+
+Key threads:
+- If this problem were fully solved, how would the user's day change?
+- What's this project's unique approach? Why this way?
+- What's the core value in one word/phrase?
+- What does the user actually get? (CLI, web app, library, API...)
+- Why that form?
+- Open source, internal tool, or product?
+- The deliverable in one sentence?
+
+Slots to fill:
+- `{{before_after}}`
+- `{{unique_approach}}`, `{{why_this_way}}`
+- `{{core_value}}`
+- `{{output_form}}`, `{{why_this_form}}`
+- `{{project_nature}}`
+- `{{deliverable}}`
+
+**When to move on:** The user can see what they're building and nods.
+
+### Experience & Boundaries — How is it used, and where does it end?
+
+> What to discover: The tangible user journey, the aha moment, and the hard edges.
+
+Key threads:
+- Walk me through first encounter to getting value — like a movie scene.
+- At what point does the user think "this is it!"?
+- What's the most frequent action?
+- What might people confuse this with, that this is NOT?
+- What's the minimum for v1.0?
+- How do you know this succeeded? What's the observable signal?
+
+Slots to fill:
+- `{{user_journey}}`, `{{aha_moment}}`, `{{primary_action}}`
+- `{{not_this}}`
+- `{{mvp_criteria}}`, `{{success_signal}}`
+
+**When to move on:** The project has clear shape and edges.
+
+### Principles — What philosophy guides this?
+
+> What to discover: The rules this project lives by. What's non-negotiable vs. flexible.
+
+Before asking, check for existing conventions in the project files:
+```bash
+cat .eslintrc* .prettierrc* tsconfig.json .editorconfig Makefile Dockerfile 2>/dev/null | head -80
+ls .github/workflows/ .gitlab-ci.yml 2>/dev/null
+```
+
+Key threads:
+- Are there rules that must never be broken?
+- How much autonomy should AI agents have?
+- Speed vs quality, flexibility vs strictness — where does this project stand?
+
+Accumulate as:
+```
+[NON-NEGOTIABLE] {{principle_name}} → {{concrete_rule}}
+[GUIDELINE] {{principle_name}} → {{concrete_rule}}
+```
+
+**When to move on:** 2-7 principles feel right to the user. This area is optional — some projects don't need explicit principles at init time. Don't force it.
+
+---
+
+## Checkpoints & State Tracking
+
+After exploring an area (or multiple areas that came up together), summarize what you've gathered and read it back. Ask the user to confirm or correct.
+
+Don't checkpoint after every single question. Checkpoint when you've accumulated enough to be worth reviewing — typically after a natural cluster of questions.
+
+**At each checkpoint, save progress to PROJECT.md** with `status: drafting`:
+
+```yaml
+---
+status: drafting
+areasExplored: [problem, vision]
+areasRemaining: [experience, principles]
+lastCheckpoint: vision
+generatedBy: know-thy-build
+---
+```
+
+Write the confirmed content into the document body as you go (using the template structure). This way:
+- If the session breaks, the next `/know-thy-build` picks up from `lastCheckpoint`
+- The user can see the document taking shape incrementally
+- `areasRemaining` shrinks as the conversation progresses
+
+Update the frontmatter every time you checkpoint. The document is the single source of truth for conversation state.
+
+---
+
+## When to Generate
+
+Offer to generate PROJECT.md when **enough areas are covered to write a meaningful document**. Not all slots need to be filled. A PROJECT.md with a clear Problem + Vision + Deliverable is more valuable than one that forces answers to every slot.
+
+Signs the conversation is ready:
+- The user starts giving shorter, confirming answers
+- The user says something like "I think that covers it"
+- You can write a coherent PROJECT.md with what you have
+- The conversation has a natural closing energy
+
+When ready, present a final summary of everything gathered, then ask to proceed.
+
+---
+
+## Generate PROJECT.md
+
+If you've been saving drafts incrementally, the document already exists. Finalize it now.
+If not, write to `PROJECT.md` in the project root.
+
+**On finalization, update frontmatter:**
+```yaml
+---
+status: complete
+areasExplored: [problem, vision, experience, principles]  # only what was actually explored
+generatedBy: know-thy-build
+version: 1.0.0
+date: {{date}}
+---
+```
+
+Remove `areasRemaining` and `lastCheckpoint` — they're only for drafting state.
+
+**Rules:**
+- Only include content from the conversation. No generic filler.
+- Preserve the user's actual words as much as possible.
+- **Omit sections that were not discussed.** A shorter, honest document beats a padded one.
+- The entire document MUST be written in {{LANG}}.
+
+**Template structure** (write all prose in {{LANG}}, use the user's own words):
+
+```markdown
+# {{project_name}}
+
+<!-- One-liner: what it is + who it's for + core value. Write in {{LANG}}. -->
+
+## Problem
+
+<!-- Weave into natural prose in {{LANG}}:
+     {{who_suffers}}, {{problem_root}}, {{problem_impact}},
+     {{current_alternative}}, {{why_not_enough}} -->
+
+## Vision
+
+| Before | After |
+|--------|-------|
+| {{before}} | {{after}} |
+
+**Approach:** {{unique_approach}}
+**Why:** {{why_this_way}}
+
+## What We Build
+
+| | |
+|---|---|
+| **Deliverable** | {{deliverable}} |
+| **Form** | {{output_form}} ({{why_this_form}}) |
+| **Nature** | {{project_nature}} |
+
+## User Journey
+
+<!-- {{user_journey}} as natural prose in {{LANG}} -->
+
+**Aha Moment:** {{aha_moment}}
+**Primary Action:** {{primary_action}}
+
+## Principles
+
+### {{principle_name}} (NON-NEGOTIABLE)
+{{concrete_rule}}
+
+### {{principle_name}}
+{{concrete_rule}}
+
+## Boundaries
+
+**This is NOT:** {{not_this}}
+
+## Success
+
+**MVP:** {{mvp_criteria}}
+**Success Signal:** {{success_signal}}
+
+---
+
+*Generated by know-thy-build v1.0.0 | {{date}}*
+```
+
+## Update CLAUDE.md
+
+If `CLAUDE.md` exists → prepend reference. If not → create minimal one.
+
+**Reference to add:**
+```markdown
+## Project Compass
+This project follows the principles defined in [PROJECT.md](./PROJECT.md).
+AI agents MUST read PROJECT.md before starting any work.
+NON-NEGOTIABLE rules in PROJECT.md cannot be overridden.
+```
+
+## Closing
+
+Tell the user:
+- PROJECT.md has been generated.
+- This document is the compass for all agents working on this project.
+- Run `/know-thy-build-evolve` when the project's direction shifts.