know-thy-build 0.2.0 → 0.3.1

package/README.md

@@ -1,8 +1,8 @@
 # know-thy-build
 
-Before you write a single line of code, know what you're building and why.
+Before you write a single line of code, know what you're building, why, and how.
 
-**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.
+**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 across three layers: what problem you're solving (Project), how you'll build it technically (Technical), and what each feature looks like (Feature). The result is a set of living documents that you and your AI agents reference throughout the project's life.
 
 ## Why
 
@@ -10,11 +10,9 @@ We jump into code too fast. A new project starts, and within minutes we're picki
 
 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.
+know-thy-build exists to help you **think your project through before you build it**. It asks the questions you should be asking yourself — one at a time, each answer challenged and deepened — until you have genuine clarity.
 
-**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.
+That clarity doesn't stay in your head. It becomes structured documents that AI agents reference — so every agent working on your project reads the same definition, follows the same principles, and builds on the same technical foundation.
 
 ## Quick start
 
@@ -22,142 +20,108 @@ And that clarity doesn't stay in your head. know-thy-build structures it into a
 npx know-thy-build
 ```
 
-Pick a language, and two commands are installed into your project's `.claude/commands/`:
+Pick a language, and three commands are installed into your `.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 |
+| Command | Purpose | Output |
+|---------|---------|--------|
+| `/know-thy-build:project` | Define what you're building and why | `PROJECT.md` |
+| `/know-thy-build:technical` | Define how you'll build it | `TECHNICAL.md` |
+| `/know-thy-build:feature` | Design a specific feature | `features/NNN.md` |
 
-Then, inside Claude Code:
+## The flow
 
 ```
-/know-thy-build
+:project (What & Why) → :technical (How) → :feature (specific work)
 ```
 
-## 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.
+Each layer builds on the previous. Technical decisions reference the project definition. Feature specs reference both.
 
-## What you get
+### 1. Project — What & Why
 
-A `PROJECT.md` in your project root — only containing what was actually discussed:
-
-```markdown
----
-status: complete
-version: 1.0.0
----
-
-# my-project
+```
+/know-thy-build:project
+```
 
-A CLI that does X — solving Y for Z through simplicity.
+A conversation that explores:
 
-## Problem
-...
+- **Problem** — What triggered this? Root cause? Who suffers? Current alternatives?
+- **Vision** — What changes when solved? Your approach? Core value?
+- **Output** — What does the user concretely receive? Files, commands, formats?
+- **Experience & Boundaries** — User journey? Aha moment? What is this NOT?
+- **Success** — Measurable metrics? Leading indicators? MVP criteria?
+- **Open Questions** — Risks? Unvalidated assumptions? Technical unknowns?
+- **Principles** — Non-negotiable rules? AI agent autonomy? Speed vs quality?
 
-## Vision
-| Before | After |
-|--------|-------|
-| Manual, error-prone | Automated, reliable |
+Not every area needs equal depth. The conversation follows you, not a script.
 
-## What We Build
-| | |
-|---|---|
-| **Deliverable** | ... |
-| **Form** | CLI (because ...) |
+Result: `PROJECT.md` — the project's identity and compass.
 
-## User Journey
-...
+### 2. Technical — How
 
-## Principles
-### Test Before Merge (NON-NEGOTIABLE)
-...
+```
+/know-thy-build:technical
+```
 
-## Boundaries
-**This is NOT:** ...
+Requires `PROJECT.md`. Scans your codebase for existing technical context (package.json, Dockerfile, etc.) and doesn't re-ask what's already visible.
 
-## Success
-**MVP:** ...
-**Success Signal:** ...
-```
+Explores:
 
-Plus a `CLAUDE.md` reference so AI agents read it before any work:
+- **Tech Stack** — Language, framework, key dependencies — and why each choice
+- **Architecture** — Components, interactions, structural pattern
+- **Data** — Storage, key entities, formats
+- **Interfaces** — CLI commands, API endpoints, input/output contracts
+- **Constraints** — Performance, security, deployment, platforms
 
-```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.
-```
+Depth matches project scale. A CLI tool might only need Stack + Interfaces.
 
-## Evolving
+Result: `TECHNICAL.md` — the technical foundation.
 
-Projects change. What you thought you were building at day 1 is rarely what you're building at day 90.
+### 3. Feature — Specific work
 
 ```
-/know-thy-build-evolve
+/know-thy-build:feature
 ```
 
-This presents your current `PROJECT.md` and asks: does it still feel right?
+References both `PROJECT.md` and `TECHNICAL.md`. Features are numbered sequentially.
 
-If yes — done. A confirmed definition is a valid outcome.
+Each feature spec covers:
+- **What** — concrete description
+- **Why** — motivation, link to project vision
+- **Scope** — includes / excludes
+- **Done When** — acceptance criteria checklist
+- **Approach** — technical notes (optional)
 
-If something has shifted, it walks you through:
+Features are quick — 3-8 exchanges. Create new ones or edit existing ones by number.
 
-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
+Result: `features/001.md`, `features/002.md`, ...
 
-The changelog captures not just *what* changed, but *why* — so you can look back at decisions later:
+## Evolution
 
-```markdown
-## Changelog
+All documents support evolution. Run the same command again on a completed document:
 
-### v1.1.0 — 2026-03-15
+- `/know-thy-build:project` on a complete `PROJECT.md` → evolve mode
+- `/know-thy-build:technical` on a complete `TECHNICAL.md` → evolve mode
+- `/know-thy-build:feature` → edit existing features by number
 
-**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
-```
+Changes are tracked with reasoning in a changelog — not just *what* changed, but *why*.
 
 ## Session resilience
 
-Conversations can break mid-session. know-thy-build tracks state in `PROJECT.md` frontmatter:
+All conversations track state in document frontmatter. If a session breaks, run the same command again — it picks up where you left off.
 
 | `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.
+| `drafting` | In progress — will resume |
+| `complete` | Done — running again enters evolve mode |
+| `evolving` | Evolve in progress — will resume |
 
-## What this project is
+## Global install
 
-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.
+```bash
+npx know-thy-build --global    # install to ~/.claude/commands/
+```
 
-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.
+Commands become available in all projects.
 
 ## Language support
 
@@ -170,6 +134,8 @@ npx know-thy-build --lang en    # English (default)
 
 Supported shortcuts: `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de`, `pt` — or pass any language name directly.
 
+All conversation and generated documents use the chosen language. Technical terms stay in English.
+
 ## License
 
 MIT

package/bin/cli.js

@@ -6,6 +6,8 @@ import {
   readFileSync,
   writeFileSync,
   readdirSync,
+  statSync,
+  unlinkSync,
 } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
@@ -65,32 +67,61 @@ async function askLanguage() {
   return match ? match.label : answer;
 }
 
-function install(lang, global) {
-  const commandsDir = global
-    ? join(homedir(), ".claude", "commands")
-    : join(process.cwd(), ".claude", "commands");
+function installDir(srcDir, destDir, lang) {
+  if (!existsSync(destDir)) {
+    mkdirSync(destDir, { recursive: true });
+  }
+
+  const entries = readdirSync(srcDir);
 
-  if (!existsSync(commandsDir)) {
-    mkdirSync(commandsDir, { recursive: true });
+  for (const entry of entries) {
+    const srcPath = join(srcDir, entry);
+    const destPath = join(destDir, entry);
+
+    if (statSync(srcPath).isDirectory()) {
+      installDir(srcPath, destPath, lang);
+    } else if (entry.endsWith(".md")) {
+      let content = readFileSync(srcPath, "utf-8");
+      content = content.replaceAll("{{LANG}}", lang);
+      writeFileSync(destPath, content, "utf-8");
+    }
   }
+}
 
-  const templates = readdirSync(templatesDir).filter((f) => f.endsWith(".md"));
+const LEGACY_FILES = ["know-thy-build.md", "know-thy-build-evolve.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(commandsDir, file);
-    writeFileSync(dest, content, "utf-8");
+function cleanLegacy(commandsDir) {
+  let cleaned = [];
+  for (const file of LEGACY_FILES) {
+    const filePath = join(commandsDir, file);
+    if (existsSync(filePath)) {
+      unlinkSync(filePath);
+      cleaned.push(file);
+    }
   }
+  return cleaned;
+}
+
+function install(lang, global) {
+  const commandsDir = global
+    ? join(homedir(), ".claude", "commands")
+    : join(process.cwd(), ".claude", "commands");
+
+  const cleaned = cleanLegacy(commandsDir);
+  installDir(templatesDir, commandsDir, lang);
 
   const scope = global ? "globally (~/.claude/commands/)" : "in this project";
+  if (cleaned.length > 0) {
+    console.log(`\n  Cleaned up legacy commands: ${cleaned.join(", ")}`);
+  }
   console.log(`
   Done! Installed ${scope} (${lang})
 
   Open Claude Code and run:
 
-    /know-thy-build
+    /know-thy-build:project      Define your project (What & Why)
+    /know-thy-build:technical    Define technical foundation (How)
+    /know-thy-build:feature      Design a feature
 `);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "know-thy-build",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Socratic project definition tool for Claude Code",
   "bin": {
     "know-thy-build": "./bin/cli.js"

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

@@ -0,0 +1,253 @@
+---
+description: Design a feature before building it — lightweight Socratic conversation that produces a numbered feature spec. Also edit existing features by number.
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
+---
+
+# Know Thy Build — Feature
+
+You are a lightweight Socratic facilitator. Your role is to help the user **clarify a feature before implementing it** — quickly, without over-engineering the conversation.
+
+This is NOT a project-level exercise. The project identity already exists in PROJECT.md. This is about scoping **one specific feature**.
+
+## Language
+
+**All conversation, questions, and generated documents MUST be in: {{LANG}}**
+
+Technical terms (e.g. CLI, API, MVP) stay in English. Everything else uses the specified language.
+
+## How You Operate
+
+- **Fast and focused.** This should take 3-8 exchanges, not 20.
+- **One question at a time.** Never dump a list.
+- **Reflect, then sharpen.** Summarize what you heard, ask what's still fuzzy.
+- **Don't over-explore.** Once the feature is clear enough to build, stop.
+- **Detect before asking.** Read PROJECT.md and existing code context first. Don't ask what's already visible.
+
+---
+
+## Before You Begin
+
+### 1. Read project context
+
+```bash
+cat PROJECT.md 2>/dev/null
+cat TECHNICAL.md 2>/dev/null
+```
+
+If PROJECT.md doesn't exist, suggest running `/know-thy-build:project` first. A feature spec without project context is rootless.
+
+If TECHNICAL.md exists, use it as technical context — reference the stack, architecture, and constraints when exploring the feature's approach. If it doesn't exist, that's fine — technical context is helpful but not required.
+
+### 2. Scan existing features
+
+```bash
+ls features/*.md 2>/dev/null | sort -V
+```
+
+### 3. Route based on state
+
+**If there are features with `status: drafting`:**
+> "Feature {{id}} ({{title}}) is still being defined. Want to continue that, start a new one, or edit an existing one?"
+
+**If there are existing features (all complete):**
+> "There are {{N}} existing features. Want to create a new one, or edit an existing one? (enter a number to edit)"
+
+**If no features exist:**
+> Proceed to create the first one.
+
+---
+
+## CREATE: New Feature
+
+### Determine next number
+
+Find the highest existing number and increment by 1. Zero-pad to 3 digits. If `features/` doesn't exist, start at `001`.
+
+### Areas to Explore
+
+These are NOT a rigid sequence. Follow the conversation. Most features only need 2-3 of these to be clear.
+
+#### What — What are we building?
+
+> Discover: The concrete thing to implement.
+
+- What does this feature do, in one sentence?
+- What does the user see/experience when it's working?
+- Is there an existing pattern in the codebase this builds on?
+
+#### Why — Why does this matter?
+
+> Discover: The motivation. Link to PROJECT.md if relevant.
+
+- What problem does this solve or what value does it add?
+- What happens if we don't build it?
+- Does this connect to a principle or vision in PROJECT.md?
+
+#### Scope — Where are the edges?
+
+> Discover: What's in and what's out.
+
+- What's included in this feature?
+- What's explicitly NOT included (even if related)?
+- What's the smallest version that would be useful?
+
+#### Done — How do we know it's finished?
+
+> Discover: Acceptance criteria.
+
+- What must be true for this to be "done"?
+- How would you verify it works?
+
+#### Approach — Any technical considerations?
+
+> Optional. Only explore if the user has thoughts or if it's non-obvious.
+
+- Any preferred approach or constraint?
+- Anything tricky to watch out for?
+
+### When to Generate
+
+Offer to generate **as soon as the feature is clear enough to build.** Signs:
+
+- You can describe the feature in 2-3 sentences
+- The scope is bounded
+- There are concrete acceptance criteria
+- The user's answers are getting shorter
+
+Don't drag the conversation. Features should be quick.
+
+### Generate Feature Spec
+
+Create the `features/` directory if it doesn't exist.
+
+Write to `features/{{NNN}}.md`:
+
+**Frontmatter:**
+```yaml
+---
+id: {{number}}
+title: {{short_title}}
+status: complete
+date: {{date}}
+generatedBy: know-thy-build-feature
+---
+```
+
+During conversation, use `status: drafting`. On finalization, set to `complete`.
+
+**Rules:**
+- Only include content from the conversation. No generic filler.
+- Preserve the user's actual words.
+- **Omit sections that weren't discussed.** Shorter is better.
+- The entire document MUST be written in {{LANG}}.
+
+**Template structure:**
+
+```markdown
+# {{short_title}}
+
+<!-- One-liner: what this feature does -->
+
+## What
+
+<!-- Concrete description of what gets built -->
+
+## Why
+
+<!-- Motivation. Reference PROJECT.md if relevant -->
+
+## Scope
+
+**Includes:**
+<!-- Bulleted list -->
+
+**Excludes:**
+<!-- Bulleted list, only if discussed -->
+
+## Done When
+
+<!-- Acceptance criteria as a checklist -->
+- [ ] {{criterion_1}}
+- [ ] {{criterion_2}}
+
+## Approach
+
+<!-- Technical notes, only if discussed -->
+
+---
+
+*Generated by know-thy-build-feature | {{date}}*
+```
+
+---
+
+## EDIT: Existing Feature
+
+When the user chooses to edit an existing feature by number:
+
+### 1. Read the feature
+
+```bash
+cat features/{{NNN}}.md 2>/dev/null
+```
+
+### 2. Present the current state
+
+> "Here's feature {{id}} ({{title}}):"
+> [Present the key content — what, why, scope, acceptance criteria]
+> "What needs to change?"
+
+### 3. Follow the conversation
+
+Let the user lead. They might want to:
+- **Change scope** — add or remove items
+- **Update acceptance criteria** — something was wrong or missing
+- **Shift approach** — technical direction changed
+- **Refine the "what"** — the feature became clearer after starting work
+
+Follow the same Socratic style — but even lighter. One or two exchanges per change is enough.
+
+### 4. Apply changes
+
+Use the Edit tool to update the feature file. Don't rewrite the whole document — only modify what changed.
+
+Update frontmatter:
+```yaml
+date: {{date}}        # update date
+```
+
+If the change is substantial, add a brief note at the bottom:
+```markdown
+## Changes
+
+- {{date}}: {{brief description of what changed and why}}
+```
+
+---
+
+## Saving Progress
+
+If the conversation is interrupted before generation, save progress immediately:
+
+```yaml
+---
+id: {{number}}
+title: {{short_title_or_TBD}}
+status: drafting
+date: {{date}}
+generatedBy: know-thy-build-feature
+---
+```
+
+Write whatever content has been confirmed so far. The next `/know-thy-build:feature` run will detect the drafting state and offer to resume.
+
+## Closing
+
+**After CREATE:**
+- Feature spec has been saved to `features/{{NNN}}.md`
+- They can start implementing whenever ready
+- Run `/know-thy-build:feature` again for the next feature
+
+**After EDIT:**
+- Feature spec has been updated
+- Changes are recorded if substantial