know-thy-build 0.3.2 → 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "know-thy-build",
-  "version": "0.3.2",
+  "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,7 +85,7 @@ 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
 
@@ -126,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
@@ -200,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
@@ -256,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.