know-thy-build 0.3.1 → 0.4.0

package/README.md

@@ -24,9 +24,9 @@ Pick a language, and three commands are installed into your `.claude/commands/`:
 
 | 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` |
+| `/know-thy-build:project` | Define what you're building and why | `docs/PROJECT.md` |
+| `/know-thy-build:technical` | Define how you'll build it | `docs/TECHNICAL.md` |
+| `/know-thy-build:feature` | Design a specific feature | `docs/features/NNN.md` |
 
 ## The flow
 
@@ -54,7 +54,7 @@ A conversation that explores:
 
 Not every area needs equal depth. The conversation follows you, not a script.
 
-Result: `PROJECT.md` — the project's identity and compass.
+Result: `docs/PROJECT.md` — the project's identity and compass.
 
 ### 2. Technical — How
 
@@ -74,7 +74,7 @@ Explores:
 
 Depth matches project scale. A CLI tool might only need Stack + Interfaces.
 
-Result: `TECHNICAL.md` — the technical foundation.
+Result: `docs/TECHNICAL.md` — the technical foundation.
 
 ### 3. Feature — Specific work
 
@@ -93,16 +93,20 @@ Each feature spec covers:
 
 Features are quick — 3-8 exchanges. Create new ones or edit existing ones by number.
 
-Result: `features/001.md`, `features/002.md`, ...
+Result: `docs/features/001.md`, `docs/features/002.md`, ...
 
 ## Evolution
 
 All documents support evolution. Run the same command again on a completed document:
 
-- `/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:project` on a complete `docs/PROJECT.md` → evolve mode
+- `/know-thy-build:technical` on a complete `docs/TECHNICAL.md` → evolve mode
 - `/know-thy-build:feature` → edit existing features by number
 
+### Migration from v0.3.x
+
+If you have existing `PROJECT.md`, `TECHNICAL.md`, or `features/` at your project root, they will be automatically moved to `docs/` the next time you run any `/know-thy-build:*` command. References in `CLAUDE.md` are updated automatically.
+
 Changes are tracked with reasoning in a changelog — not just *what* changed, but *why*.
 
 ## Session resilience
@@ -136,6 +140,45 @@ Supported shortcuts: `en`, `ko`, `ja`, `zh`, `es`, `fr`, `de`, `pt` — or pass
 
 All conversation and generated documents use the chosen language. Technical terms stay in English.
 
+## Foundations
+
+know-thy-build draws on established techniques from philosophy, software engineering, and AI research.
+
+### Core method: Socratic Prompting
+
+The tool applies the [Socratic method](https://en.wikipedia.org/wiki/Socratic_method) — questioning to surface latent knowledge rather than providing answers directly. In Plato's *Meno*, Socrates demonstrates that learning is **recollection** (anamnesis): the right questions draw out what the learner already knows. know-thy-build operates on the same premise — you already know what you want to build, you just haven't articulated it yet.
+
+- Chang, ["Prompting Large Language Models With the Socratic Method"](https://arxiv.org/abs/2303.08769) (2023) — adapts Socratic strategies into LLM prompting templates
+- Princeton NLP, ["The Socratic Method for Self-Discovery in Large Language Models"](https://princeton-nlp.github.io/SocraticAI/) — explicitly connects Socratic dialogue to self-discovery in LLMs
+- [SocraticLM](https://proceedings.neurips.cc/paper_files/paper/2024/hash/9bae399d1f34b8650351c1bd3692aeae-Abstract-Conference.html) (NeurIPS 2024 Spotlight) — Socratic teaching paradigm outperforming GPT-4 by >12%
+
+### Dialectical reasoning
+
+Each exchange follows a thesis-antithesis-synthesis cycle: the user states what they want (thesis), the tool challenges it (antithesis), and a refined understanding emerges (synthesis). This is [Hegelian dialectic](https://en.wikipedia.org/wiki/Dialectic#Hegelian_dialectic) applied to project definition.
+
+- ["Self-reflecting LLMs: A Hegelian Dialectical Approach"](https://arxiv.org/abs/2501.14917) (2025)
+
+### Requirements elicitation
+
+In software engineering, [requirements elicitation](https://en.wikipedia.org/wiki/Requirements_elicitation) is the process of discovering what stakeholders actually need — a discipline that recognizes requirements are *discovered*, not merely captured.
+
+- Zave & Jackson, "Four Dark Corners of Requirements Engineering" (1997, ACM TOSEM)
+- ["AI-based Multiagent Approach for Requirements Elicitation and Analysis"](https://arxiv.org/abs/2409.00038) (2024)
+
+### Design Thinking (Define phase)
+
+know-thy-build's output maps to the **Define** phase of [Design Thinking](https://web.stanford.edu/~mshanks/MichaelShanks/files/509554.pdf) (Stanford d.school) — synthesizing fuzzy intuitions into a structured problem statement that guides everything that follows.
+
+### The Rubber Duck, upgraded
+
+[Rubber duck debugging](https://en.wikipedia.org/wiki/Rubber_duck_debugging) works because articulating forces clarity. know-thy-build is a rubber duck that talks back — one that not only forces articulation but actively probes weak spots and challenges surface-level answers.
+
+### Multi-Agent Debate
+
+Even within a single facilitator, know-thy-build adopts multiple perspectives — questioning like a PM, challenging like an architect, probing edge cases like QA. The principle that opposing viewpoints produce better outcomes is well-established.
+
+- Liang et al., ["Encouraging Divergent Thinking in Large Language Models through Multi-Agent Debate"](https://arxiv.org/abs/2305.19118) (EMNLP 2024)
+
 ## License
 
 MIT

package/package.json

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

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

@@ -27,21 +27,45 @@ Technical terms (e.g. CLI, API, MVP) stay in English. Everything else uses the s
 
 ## Before You Begin
 
+### 0. Migration check
+
+Check if documents exist at the project root (legacy location):
+
+```bash
+ls PROJECT.md TECHNICAL.md 2>/dev/null
+ls features/*.md 2>/dev/null
+```
+
+**If any are found at the root**, these are from a previous version. Migrate them to `docs/`:
+
+1. Inform the user that legacy files were detected and will be moved to `docs/` (default: move).
+2. Execute:
+   ```bash
+   mkdir -p docs
+   [ -f PROJECT.md ] && mv PROJECT.md docs/PROJECT.md
+   [ -f TECHNICAL.md ] && mv TECHNICAL.md docs/TECHNICAL.md
+   [ -d features ] && mv features docs/features
+   ```
+3. If `CLAUDE.md` exists, update any path references from `PROJECT.md` to `docs/PROJECT.md`, and `TECHNICAL.md` to `docs/TECHNICAL.md`, `features/` to `docs/features/`.
+4. Inform the user what was moved.
+
+If no legacy files are found, skip silently.
+
 ### 1. Read project context
 
 ```bash
-cat PROJECT.md 2>/dev/null
-cat TECHNICAL.md 2>/dev/null
+cat docs/PROJECT.md 2>/dev/null
+cat docs/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 `docs/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.
+If `docs/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
+ls docs/features/*.md 2>/dev/null | sort -V
 ```
 
 ### 3. Route based on state
@@ -61,27 +85,35 @@ ls features/*.md 2>/dev/null | sort -V
 
 ### 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`.
+Find the highest existing number and increment by 1. Zero-pad to 3 digits. If `docs/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?
+#### Problem — What's broken or missing?
 
-> Discover: The concrete thing to implement.
+> Discover: The specific pain this feature addresses. This is not the project-level problem (that's in PROJECT.md) — this is the concrete gap or friction that triggered "we need this feature."
 
-- 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?
+- What's not working right now? What's the user struggling with?
+- What happens today without this feature? (workaround, manual step, error, confusion...)
+- Who hits this problem and how often?
+
+#### Value — Why is this worth building?
+
+> Discover: The value this feature delivers and how it connects to the bigger picture.
 
-#### Why — Why does this matter?
+- What changes for the user when this exists?
+- How does this connect to the project's vision or principles in PROJECT.md?
+- What happens if we don't build it? Is there a cost of inaction?
 
-> Discover: The motivation. Link to PROJECT.md if relevant.
+#### Solution — How does this solve it?
 
-- 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?
+> Discover: The concrete thing to implement. Not implementation details, but the user-facing shape of the solution.
+
+- 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?
 
 #### Scope — Where are the edges?
 
@@ -118,9 +150,9 @@ Don't drag the conversation. Features should be quick.
 
 ### Generate Feature Spec
 
-Create the `features/` directory if it doesn't exist.
+Create the `docs/features/` directory if it doesn't exist.
 
-Write to `features/{{NNN}}.md`:
+Write to `docs/features/{{NNN}}.md`:
 
 **Frontmatter:**
 ```yaml
@@ -148,13 +180,17 @@ During conversation, use `status: drafting`. On finalization, set to `complete`.
 
 <!-- One-liner: what this feature does -->
 
-## What
+## Problem
+
+<!-- What's broken or missing today. The specific pain this feature addresses. -->
+
+## Value
 
-<!-- Concrete description of what gets built -->
+<!-- What changes when this exists. Link to PROJECT.md vision/principles if relevant. -->
 
-## Why
+## Solution
 
-<!-- Motivation. Reference PROJECT.md if relevant -->
+<!-- Concrete description of what gets built and how the user experiences it -->
 
 ## Scope
 
@@ -188,7 +224,7 @@ When the user chooses to edit an existing feature by number:
 ### 1. Read the feature
 
 ```bash
-cat features/{{NNN}}.md 2>/dev/null
+cat docs/features/{{NNN}}.md 2>/dev/null
 ```
 
 ### 2. Present the current state
@@ -244,7 +280,7 @@ Write whatever content has been confirmed so far. The next `/know-thy-build:feat
 ## Closing
 
 **After CREATE:**
-- Feature spec has been saved to `features/{{NNN}}.md`
+- Feature spec has been saved to `docs/features/{{NNN}}.md`
 - They can start implementing whenever ready
 - Run `/know-thy-build:feature` again for the next feature
 

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

@@ -28,17 +28,41 @@ Technical terms (e.g. CLI, API, NON-NEGOTIABLE) stay in English. Everything else
 
 ## Before You Begin
 
-Silently scan the project for existing context:
+### 0. Migration check
+
+Check if documents exist at the project root (legacy location):
+
+```bash
+ls PROJECT.md TECHNICAL.md 2>/dev/null
+ls features/*.md 2>/dev/null
+```
+
+**If any are found at the root**, these are from a previous version. Migrate them to `docs/`:
+
+1. Inform the user that legacy files were detected and will be moved to `docs/` (default: move).
+2. Execute:
+   ```bash
+   mkdir -p docs
+   [ -f PROJECT.md ] && mv PROJECT.md docs/PROJECT.md
+   [ -f TECHNICAL.md ] && mv TECHNICAL.md docs/TECHNICAL.md
+   [ -d features ] && mv features docs/features
+   ```
+3. If `CLAUDE.md` exists, update any path references from `PROJECT.md` to `docs/PROJECT.md`, and `TECHNICAL.md` to `docs/TECHNICAL.md`, `features/` to `docs/features/`.
+4. Inform the user what was moved.
+
+If no legacy files are found, skip silently.
+
+### 1. Scan project 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
+cat CLAUDE.md docs/PROJECT.md 2>/dev/null
 ```
 
-Route based on PROJECT.md state:
+Route based on `docs/PROJECT.md` state:
 
-### No PROJECT.md → CREATE mode
+### No docs/PROJECT.md → CREATE mode
 
 Note the blank canvas and begin exploring areas.
 
@@ -55,7 +79,7 @@ Present what was gathered so far and ask:
 ### `status: evolving` → RESUME EVOLVE mode
 
 Read `evolveProgress` from frontmatter and resume:
-> "We started evolving PROJECT.md before. Here's where we left off: [summary]. Shall we continue?"
+> "We started evolving docs/PROJECT.md before. Here's where we left off: [summary]. Shall we continue?"
 
 ### `status: complete` → EVOLVE mode
 
@@ -216,7 +240,7 @@ After exploring an area, summarize and read it back. Ask the user to confirm or
 
 Don't checkpoint after every question. Checkpoint when you've accumulated enough — typically after a natural cluster.
 
-**At each checkpoint, save progress to PROJECT.md** with `status: drafting`:
+**At each checkpoint, save progress to `docs/PROJECT.md`** with `status: drafting`:
 
 ```yaml
 ---
@@ -243,9 +267,9 @@ Signs the conversation is ready:
 
 ---
 
-## Generate PROJECT.md
+## Generate docs/PROJECT.md
 
-Finalize the document. Update frontmatter:
+Finalize the document. Write to `docs/PROJECT.md`. Create the `docs/` directory if it doesn't exist. Update frontmatter:
 
 ```yaml
 ---
@@ -459,19 +483,19 @@ If `CLAUDE.md` exists → prepend reference (if not already present). If not →
 **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.
+This project follows the principles defined in [PROJECT.md](./docs/PROJECT.md).
+AI agents MUST read docs/PROJECT.md before starting any work.
 NON-NEGOTIABLE rules in PROJECT.md cannot be overridden.
 ```
 
 ## Closing
 
 **After CREATE:**
-- PROJECT.md has been generated.
+- `docs/PROJECT.md` has been generated.
 - This document is the compass for all agents working on this project.
 - Run `/know-thy-build:project` again when the project's direction shifts.
 
 **After EVOLVE:**
-- PROJECT.md has been updated.
+- `docs/PROJECT.md` has been updated.
 - The changelog records not just what changed, but why.
 - Run `/know-thy-build:project` again whenever the direction shifts.

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

@@ -29,15 +29,39 @@ Technical terms (e.g. REST, PostgreSQL, Docker, CI/CD) stay in English. Everythi
 
 ## Before You Begin
 
+### 0. Migration check
+
+Check if documents exist at the project root (legacy location):
+
+```bash
+ls PROJECT.md TECHNICAL.md 2>/dev/null
+ls features/*.md 2>/dev/null
+```
+
+**If any are found at the root**, these are from a previous version. Migrate them to `docs/`:
+
+1. Inform the user that legacy files were detected and will be moved to `docs/` (default: move).
+2. Execute:
+   ```bash
+   mkdir -p docs
+   [ -f PROJECT.md ] && mv PROJECT.md docs/PROJECT.md
+   [ -f TECHNICAL.md ] && mv TECHNICAL.md docs/TECHNICAL.md
+   [ -d features ] && mv features docs/features
+   ```
+3. If `CLAUDE.md` exists, update any path references from `PROJECT.md` to `docs/PROJECT.md`, and `TECHNICAL.md` to `docs/TECHNICAL.md`, `features/` to `docs/features/`.
+4. Inform the user what was moved.
+
+If no legacy files are found, skip silently.
+
 ### 1. Read project context
 
 ```bash
-cat PROJECT.md 2>/dev/null
-cat TECHNICAL.md 2>/dev/null
+cat docs/PROJECT.md 2>/dev/null
+cat docs/TECHNICAL.md 2>/dev/null
 ```
 
-**If PROJECT.md doesn't exist or has `status: drafting`:**
-> "PROJECT.md needs to be complete first — the technical design should follow the project definition. Run `/know-thy-build:project` first."
+**If `docs/PROJECT.md` doesn't exist or has `status: drafting`:**
+> "docs/PROJECT.md needs to be complete first — the technical design should follow the project definition. Run `/know-thy-build:project` first."
 → Stop here.
 
 ### 2. Scan existing technical context
@@ -50,14 +74,14 @@ ls .github/workflows/ .gitlab-ci.yml 2>/dev/null
 cat CLAUDE.md 2>/dev/null
 ```
 
-### 3. Route based on TECHNICAL.md state
+### 3. Route based on `docs/TECHNICAL.md` state
 
-**No TECHNICAL.md → CREATE mode**
-Present what you found from PROJECT.md and codebase:
+**No `docs/TECHNICAL.md` → CREATE mode**
+Present what you found from `docs/PROJECT.md` and codebase:
 > "PROJECT.md defines [one-liner summary]. I can see [tech context from files]. Let's define the technical foundation."
 
 **`status: drafting` → RESUME mode**
-Read frontmatter, present progress, offer to continue.
+Read `docs/TECHNICAL.md` frontmatter, present progress, offer to continue.
 
 **`status: complete` → EVOLVE mode**
 Present current technical definition:
@@ -168,7 +192,7 @@ Slots to fill:
 
 Same pattern as project — checkpoint after natural clusters, not every question.
 
-**Save progress to TECHNICAL.md** with `status: drafting`:
+**Save progress to `docs/TECHNICAL.md`** with `status: drafting`:
 
 ```yaml
 ---
@@ -194,9 +218,9 @@ Not every area needs to be explored. A CLI tool might only need Stack + Interfac
 
 ---
 
-## Generate TECHNICAL.md
+## Generate docs/TECHNICAL.md
 
-Write to `TECHNICAL.md` in the project root.
+Write to `docs/TECHNICAL.md`. Create the `docs/` directory if it doesn't exist.
 
 **Frontmatter:**
 ```yaml
@@ -316,11 +340,11 @@ lastEvolve: {{date}}
 ## Closing
 
 **After CREATE:**
-- TECHNICAL.md has been generated.
+- `docs/TECHNICAL.md` has been generated.
 - This defines the technical foundation for all implementation work.
 - Feature specs (`/know-thy-build:feature`) will reference this automatically.
 - Run `/know-thy-build:technical` again when technical direction shifts.
 
 **After EVOLVE:**
-- TECHNICAL.md has been updated with changelog.
+- `docs/TECHNICAL.md` has been updated with changelog.
 - Review if existing features need adjustment based on technical changes.