thought-cabinet 0.1.13 → 0.2.1

package/docs/CLI.md

@@ -75,22 +75,35 @@ thc prune --apply  # Actually remove stale mappings
 | `--apply`              | Apply changes (default is dry-run) |
 | `--config-file <path>` | Path to config file                |
 
+### `thc migrate`
+
+Migrate configuration from `~/.config/thought-cabinet/` to `~/.thought-cabinet/`. Moves config file, agent assets, and thoughts repos, then updates all paths in the config.
+
+```bash
+thc migrate            # Interactive migration with confirmation
+thc migrate --dry-run  # Show what would be migrated without changes
+```
+
+| Flag                   | Description                                |
+| ---------------------- | ------------------------------------------ |
+| `--dry-run`            | Show migration plan without making changes |
+| `--config-file <path>` | Path to legacy config file                 |
+
 ## Agent Configuration
 
-### `thc agent init`
+### `thc skill install`
 
-Interactively discover and install skills and agents to your AI coding agent's config directory.
+Install all bundled skills and agents to your AI coding agent's config directory.
 
-Assets are installed via **symlink** by default: a canonical copy is stored in `.thought-cabinet/` (project) or `~/.config/thought-cabinet/` (global), and symlinks are created in the agent's config directory. This means updating the canonical copy updates all agents at once.
+Assets are installed via **symlink** by default: a canonical copy is stored in `.thought-cabinet/` (project) or `~/.thought-cabinet/` (global), and symlinks are created in the agent's config directory. This means updating the canonical copy updates all agents at once.
 
 ```bash
-thc agent init                          # Interactive installation
-thc agent init --all                    # Install all without prompting
-thc agent init --target claude-code     # Install for a specific agent
-thc agent init --target cursor codex    # Install for multiple agents
-thc agent init --global                 # Install to global scope
-thc agent init --mode copy              # Copy files instead of symlinking
-thc agent init --force                  # Overwrite existing installations
+thc skill install                       # Install all assets
+thc skill install --target claude-code  # Install for a specific agent
+thc skill install --target cursor codex # Install for multiple agents
+thc skill install --global              # Install to global scope
+thc skill install --mode copy           # Copy files instead of symlinking
+thc skill install --force               # Overwrite existing installations
 ```
 
 | Flag                   | Description                                                                                |
@@ -98,9 +111,7 @@ thc agent init --force                  # Overwrite existing installations
 | `--target <agents...>` | Target agents (e.g., `claude-code`, `codebuddy`, `cursor`, `codex`, `gemini-cli`, `cline`) |
 | `-g, --global`         | Install to global scope                                                                    |
 | `--mode <mode>`        | Installation mode: `symlink` (default) or `copy`                                           |
-| `--source <path>`      | Source directory for assets                                                                |
 | `--force`              | Force overwrite of existing installations                                                  |
-| `--all`                | Install all assets without prompting                                                       |
 
 #### Installed Skills
 
@@ -239,7 +250,7 @@ thc config --json    # Output as JSON
 | `--json`               | Output configuration as JSON |
 | `--config-file <path>` | Path to config file          |
 
-Configuration is stored at `~/.config/thought-cabinet/config.json` (respects `XDG_CONFIG_HOME`).
+Configuration is stored at `~/.thought-cabinet/config.json` (falls back to `~/.config/thought-cabinet/config.json`; respects `XDG_CONFIG_HOME`).
 
 ## Hooks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thought-cabinet",
-  "version": "0.1.13",
+  "version": "0.2.1",
   "description": "Thought Cabinet (thc) — CLI for structured AI coding workflows with filesystem-based memory and context management.",
   "type": "module",
   "main": "dist/index.js",

package/src/agent-assets/skills/creating-plan/SKILL.md

@@ -144,6 +144,12 @@ After structure approval:
 
 2. **Write plan** using [plan-template.md](plan-template.md)
    - **MUST** Read the template and follow the structure exactly.
+   - **TDD compatibility check**: For every change block, verify:
+     - `Testable Behaviors` appears **before** `Reference Implementation`
+     - Each testable behavior bullet is specific enough to write a failing test from (includes input, condition, and expected output/behavior)
+     - Each bullet maps to exactly one test — split compound behaviors
+     - The code block is labeled "Reference Implementation", not "Code to write"
+   - If a change block has no conditional logic, no data transformation, and is a pure pass-through, it may omit testable behaviors — document why.
 
 3. **Sync thoughts directory**:
    ```bash

package/src/agent-assets/skills/creating-plan/plan-template.md

@@ -50,12 +50,24 @@
 
 **File**: `path/to/file.ext`
 **Changes**: [Summary of changes]
-**Testable behaviors**: [List the behaviors this change introduces or modifies — these become TDD RED tests during implementation]
+
+##### Testable Behaviors (RED tests)
+
+> Each bullet is one TDD RED test. `implementing-plan` writes each test first, watches it fail, then writes the minimal code to pass it.
+
+- [Input/condition] → [expected output/behavior]
+- [Edge case] → [expected behavior]
+- [Error case] → [expected fallback]
+
+##### Reference Implementation
 
 ```[language]
-// Specific code to add/modify
+// Suggested implementation — written AFTER the RED tests pass.
+// implementing-plan must not read this before writing the failing tests.
 ```
 
+---
+
 ### Success Criteria:
 
 #### Automated Verification:
@@ -81,18 +93,11 @@
 
 ---
 
-## Testing Strategy
-
-### Unit Tests:
-
-- [What to test]
-- [Key edge cases]
+## Integration Testing
 
-### Integration Tests:
+[End-to-end scenarios that require multiple components working together — not covered by unit tests above]
 
-- [End-to-end scenarios]
-
-### Manual Testing Steps:
+## Manual Testing Steps
 
 1. [Specific verification step]
 2. [Edge case to test manually]
@@ -126,6 +131,26 @@ Always separate into two categories:
 - Performance under real conditions
 - User acceptance criteria
 
+## TDD Compatibility Requirements
+
+When writing each change block, ask:
+
+1. **Are the testable behaviors specific enough to write a failing test from?**
+   - Bad: "handles null input"
+   - Good: "`envCreateTime=null` with cutoff set → returns `false` (safe fallback)"
+
+2. **Is the behavior written before the code block?**
+   - The testable behaviors section must appear before the reference implementation.
+   - The implementer reads behaviors first and writes the RED test before reading the code.
+
+3. **Does each bullet map to exactly one test?**
+   - Compound behaviors (A and B) → split into two bullets.
+   - Each bullet = one `def "..."()` / `it(...)` / `test(...)`.
+
+4. **Is the code block labeled "Reference Implementation"?**
+   - Never label it "Code to write" or "Implementation".
+   - The label signals it is consulted only after RED → GREEN, not before.
+
 ## Common Patterns
 
 ### Database Changes:

package/src/agent-assets/skills/implementing-plan/SKILL.md

@@ -30,7 +30,14 @@ The procedure for each unit of work:
 
 After all TDD cycles in the phase are complete, run the phase's automated verification commands as the final gate.
 
-**Resolving conflicts with the plan**: If the plan says "no tests needed", evaluate independently — apply TDD unless genuinely untestable (pure wiring, no behavioral logic). Document any skip with a reason in the phase completion message.
+**Resolving conflicts with the plan**: If the plan says "no tests needed", evaluate independently. The plan may be wrong — verify by reading existing test files. Apply TDD unless the code meets ALL of these criteria:
+1. Zero conditional logic (no if/else, no switches, no ternaries, no loops with conditions)
+2. Zero data transformation (no mapping, filtering, formatting, restructuring)
+3. The function is a pure pass-through that only calls other already-tested functions with static arguments
+
+"Wiring", "integration-level", "mostly delegation", and "would require too many mocks" are NOT valid reasons to skip TDD. If mocking is hard, that's a design signal — simplify the interface or extract testable units.
+
+**When skipping TDD**: Document the skip in the phase completion message with the specific criteria met (1-3 above). If you cannot clearly articulate which criterion applies, you must write tests.
 
 ## Getting Started
 
@@ -38,9 +45,10 @@ When given a plan path:
 
 1. Read the plan completely - check for existing checkmarks (- [x])
 2. Read ALL files mentioned in the plan without limit/offset
-3. Understand how the pieces fit together
-4. Create a todo list to track progress
-5. Begin implementation of the **first uncompleted phase only**
+3. **Read existing test files** for every module the plan modifies (use glob: `**/__tests__/*`, `**/*.test.*`, `**/*.spec.*` near changed files). This is mandatory — never assume "no tests exist" without checking.
+4. Understand how the pieces fit together
+5. Create a todo list to track progress
+6. Begin implementation of the **first uncompleted phase only**
 
 If no plan path provided, ask for one:
 
@@ -81,9 +89,37 @@ How should I proceed?
 
 Before writing any production code for a phase:
 
-1. Identify the testable behaviors the phase introduces or changes
-2. Apply the `test-driven-development` RED-GREEN-REFACTOR cycle for each behavior
-3. Only after all TDD cycles are complete, proceed to the completion checklist below
+1. Read existing test files for the modules being changed (if not already read in Getting Started)
+2. For each change block in the phase, read only the **Testable Behaviors** section — do NOT read the Reference Implementation yet
+3. For each testable behavior bullet, execute one RED-GREEN-REFACTOR cycle:
+   - **RED**: Write one failing test for that behavior. Run it. Confirm it fails for the right reason.
+   - **GREEN**: Write the minimal production code to pass it. Run it. Confirm it passes.
+   - **REFACTOR**: Clean up. Run tests. Stay green.
+4. Only after all behavior bullets have passing tests, read the Reference Implementation and reconcile — adjust your implementation if it diverges from the plan's intent, but do not delete passing tests.
+5. Proceed to the phase completion checklist.
+
+### How to Extract Work Items from a Plan Change Block
+
+A change block looks like:
+
+```
+##### Testable Behaviors (RED tests)
+- `cutoff empty` → `isEnvCreatedAfterCutoff` returns `true`
+- `createTime after cutoff` → returns `true`
+- `createTime before cutoff` → returns `false`
+- `createTime null + cutoff set` → returns `false` (safe fallback)
+
+##### Reference Implementation
+[code]
+```
+
+Map this to a work queue:
+1. `def "isEnvCreatedAfterCutoff: cutoff empty returns true"()` → RED → GREEN
+2. `def "isEnvCreatedAfterCutoff: createTime after cutoff returns true"()` → RED → GREEN
+3. `def "isEnvCreatedAfterCutoff: createTime before cutoff returns false"()` → RED → GREEN
+4. `def "isEnvCreatedAfterCutoff: null createTime with cutoff set returns false"()` → RED → GREEN
+
+Each bullet is one test. Complete all cycles for this change block before moving to the next.
 
 ## Phase Completion Checklist
 

package/src/agent-assets/skills/init-agent-memory/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: init-agent-memory
+description: Initializes agent memory for a new project by creating a concise AGENTS.md and supporting docs with progressive disclosure. Use when onboarding an agent to a repository, bootstrapping first-run project context, or replacing an overly long memory file with a scoped index to docs references.
+---
+
+# Initializing Agent Memory
+
+Create high-signal project memory for new repositories by generating `AGENTS.md` plus focused supporting docs under `docs/`, then creating `CLAUDE.md` as a compatibility symlink.
+
+## Workflow Overview
+
+1. **Gather context** - Read user instructions and repository facts; ask only unresolved questions
+2. **Research evidence** - Identify tech stack, project layout, commands, and repeated architectural patterns with file:line references
+3. **Propose structure** - Share planned AGENTS.md sections and supporting docs before writing
+4. **Write docs** - Generate `AGENTS.md`, supporting docs, and the `CLAUDE.md` symlink
+5. **Quality review** - Validate constraints from the request and improve clarity
+
+## Step 1: Gather Context
+
+### Read Inputs First
+
+If present, read these in order:
+1. User-provided memory instructions (for example `init_agent_memory.md`)
+2. Existing `AGENTS.md` and `CLAUDE.md`
+3. `README.md` and package/build metadata
+
+Read full files before drafting. Do not assume conventions.
+
+### Ask Only Missing Questions
+
+Only ask if required information cannot be inferred from repository files. Keep questions minimal and concrete.
+
+Example:
+
+```text
+I can generate the initial memory docs. One point is still unclear: should AGENTS.md include only project-level workflows, or also team-specific process notes?
+```
+
+## Step 2: Research Evidence
+
+Collect concrete references for each required section.
+
+### Required Evidence Buckets
+
+- **Project overview (WHY):** repository purpose and problem domain
+- **Tech stack (WHAT):** languages, frameworks, runtime, major tooling
+- **Key directories (WHAT):** top-level modules and responsibilities
+- **Essential commands (HOW):** build, test, lint, run workflows used daily
+- **Architectural patterns:** conventions/design decisions that appear in multiple files
+
+### Evidence Rules
+
+- Use file:line references instead of code snippets
+- Prefer primary sources (`src/`, command definitions, config files)
+- For architectural patterns, include only patterns supported by at least two code references
+- If evidence conflicts across docs and code, prefer the code and mention mismatch briefly
+
+## Step 3: Propose Structure
+
+Before writing files, share a concise structure proposal and get confirmation.
+
+Use this format:
+
+```text
+Here is the proposed memory layout.
+
+AGENTS.md (under 150 lines):
+1. Project Overview
+2. Tech Stack
+3. Key Directories
+4. Essential Build/Test Commands
+5. Additional Documentation
+
+Supporting docs:
+- docs/architectural-patterns.md
+
+I will keep AGENTS.md as an index and push detail into supporting docs (progressive disclosure).
+I will then create CLAUDE.md as a symlink to AGENTS.md for backward compatibility.
+Should I proceed with this structure?
+```
+
+If the user already requested this exact structure explicitly, treat that as approval and proceed.
+
+## Step 4: Write Docs
+
+### 4a. Create `AGENTS.md`
+
+Use [claude-memory-template.md](claude-memory-template.md).
+
+Required constraints:
+- Keep total length under 150 lines
+- Include WHAT, WHY, HOW coverage
+- Use file:line references instead of code snippets
+- Do not include formatting/style rules that linters already enforce
+- Add an "Additional Documentation" section that points to `docs/*`
+
+### 4b. Create `docs/architectural-patterns.md`
+
+Use [architectural-patterns-template.md](architectural-patterns-template.md).
+
+Required constraints:
+- Document only recurring patterns and conventions
+- Every pattern needs concrete evidence with file:line references
+- Focus on decisions that influence future implementation work
+
+### 4c. Create `CLAUDE.md` Symlink
+
+After writing `AGENTS.md`, create `CLAUDE.md` as a symlink to `AGENTS.md` in the same directory.
+
+If `CLAUDE.md` already exists as a regular file (not a symlink):
+1. Read the existing `CLAUDE.md` content
+2. Identify any useful, non-redundant content not already covered by the new `AGENTS.md`
+3. Incorporate that content into `AGENTS.md` (respecting the 150-line limit) or into a supporting doc under `docs/`
+4. Remove the old `CLAUDE.md` file and replace it with the symlink
+
+Create the symlink with:
+```bash
+ln -sf AGENTS.md CLAUDE.md
+```
+
+Required constraints:
+- `AGENTS.md` is the canonical file
+- `CLAUDE.md` is a symlink (not a duplicate copy)
+- The symlink target resolves to `AGENTS.md` from the repository root
+- Pre-existing `CLAUDE.md` content must be preserved (merged into `AGENTS.md` or `docs/`) before replacement
+
+### 4d. Progressive Disclosure Rules
+
+- Keep `AGENTS.md` concise and universally applicable
+- Put specialized details in `docs/*.md`
+- References from `AGENTS.md` should be direct and descriptive
+- Avoid deep reference chains
+
+## Step 5: Quality Review
+
+Run this checklist before presenting output:
+
+- [ ] `AGENTS.md` is under 150 lines
+- [ ] `CLAUDE.md` is a symlink to `AGENTS.md`
+- [ ] Sections cover project overview, tech stack, key directories, essential commands, additional docs
+- [ ] File:line references are present and accurate
+- [ ] No code snippets in `AGENTS.md`
+- [ ] No generic formatting/style guidance duplicated from linters
+- [ ] `docs/architectural-patterns.md` includes only repeated patterns with evidence
+- [ ] Terminology is consistent (`AGENTS.md`, `CLAUDE.md` symlink, "Additional Documentation", `docs/`)
+
+Present result with file paths and invite targeted revision requests.
+
+## Guidelines
+
+**Scope discipline:**
+- Optimize for first-session usefulness, not exhaustive documentation
+- Prefer omission over speculative or weakly supported claims
+
+**Progressive disclosure:**
+- `AGENTS.md` is an entrypoint index
+- Keep advanced details in dedicated `docs/` files
+
+**Reliability:**
+- Cite source lines for every non-trivial claim
+- Re-check references after edits

package/src/agent-assets/skills/init-agent-memory/architectural-patterns-template.md

@@ -0,0 +1,36 @@
+# Architectural Patterns
+
+Document recurring patterns observed across the codebase. Include only patterns backed by multiple examples.
+
+## Pattern: [Name]
+
+- Intent: [Why this pattern exists]
+- How it appears:
+  - [Description of implementation shape]
+- Evidence:
+  - `path/to/file:line`
+  - `path/to/another-file:line`
+- Implication for new changes:
+  - [How contributors/agents should align with this pattern]
+
+## Pattern: [Name]
+
+- Intent: [Why this pattern exists]
+- How it appears:
+  - [Description of implementation shape]
+- Evidence:
+  - `path/to/file:line`
+  - `path/to/another-file:line`
+- Implication for new changes:
+  - [How contributors/agents should align with this pattern]
+
+## Placement
+
+Store this file at `docs/architectural-patterns.md` (same level as `AGENTS.md`).
+
+## Exclusions
+
+Do not include:
+- One-off implementation details found in only one file
+- Preference statements without evidence
+- Forward-looking proposals not present in current code

package/src/agent-assets/skills/init-agent-memory/claude-memory-template.md

@@ -0,0 +1,40 @@
+# AGENTS.md Template
+
+Use this template to create the concise canonical memory document.
+
+## Project Overview
+
+- Purpose: [What the project does and why it exists]
+- Scope: [Core responsibilities and boundaries]
+- Evidence: `path/to/file:line`
+
+## Tech Stack
+
+- Languages/runtime: [TypeScript, Node.js, etc.]
+- Frameworks/libraries: [Commander.js, Vitest, etc.]
+- Tooling: [build/lint/test tools]
+- Evidence: `path/to/file:line`
+
+## Key Directories
+
+- `src/...`: [responsibility]
+- `...`: [responsibility]
+- Evidence per directory: `path/to/file:line`
+
+## Essential Build/Test Commands
+
+- `...`: [what it does and when to use it]
+- `...`: [what it does and when to use it]
+- Evidence: `path/to/file:line`
+
+## Additional Documentation
+
+- `docs/architectural-patterns.md`: Recurring design patterns and conventions
+- Add only docs that provide specialized detail not suitable for AGENTS.md
+
+## Constraints
+
+- Keep full document under 150 lines
+- Use file:line references instead of code snippets
+- Keep guidance universally applicable for contributors and agents
+- Treat `AGENTS.md` as canonical, then create `CLAUDE.md` as a symlink to `AGENTS.md`

package/src/agent-assets/skills/navigate-thoughts/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: navigate-thoughts
+description: Resolves thoughts/ paths and navigates thought documents. Use when user references a thoughts/ path, asks to find/read/list thoughts documents, or encounters symlinks in the thoughts directory.
+---
+
+# Navigating Thoughts
+
+Resolve thoughts paths to canonical form and locate documents in the local thoughts directory.
+
+## Background
+
+`thoughts/` is a symlink-based directory managed by ThoughtCabinet. It points into a central thoughts git repo but is accessed locally via relative paths from the project root.
+
+**Directory structure:**
+- `thoughts/{user}/` — Personal repo-specific notes
+- `thoughts/shared/` — Team-shared repo-specific notes (plans, research, PRs)
+- `thoughts/global/` — Cross-repository notes
+- `thoughts/searchable/` — Hard links for search tools (NOT canonical, never reference)
+
+**Common subdirectories under `shared/`:**
+- `shared/plans/` — Implementation plans (`YYYY-MM-DD-description.md`)
+- `shared/research/` — Research documents (`YYYY-MM-DD-description.md`)
+
+## Workflow
+
+1. **Normalize path**
+   - Strip `searchable/` segment: `thoughts/searchable/shared/plans/foo.md` → `thoughts/shared/plans/foo.md`
+   - Ensure `thoughts/` prefix (add if user gives bare path like `shared/plans/foo.md`)
+   - If user gives a description instead of a path, proceed to search
+
+2. **Locate document**
+   - Exact path given: read it directly
+   - Partial/fuzzy: `ls` the likely directory, then match by name or grep for content
+   - No path given: `ls -lt thoughts/shared/ thoughts/{user}/ | head -20` to show recent documents
+
+3. **Present**
+   - Read and present the document content
+   - If the path was non-canonical (e.g. contained `searchable/`), note the canonical path
+
+## Rules
+
+- **NEVER reference `thoughts/searchable/` paths** in output — always use canonical paths
+- **All paths are relative** to the project root (e.g. `thoughts/shared/plans/...`, never absolute)
+- If `thoughts/` doesn't exist, tell the user to run `thc thoughts init`
+- When listing, prefer `ls -lt` (recent first) for discoverability

package/src/agent-assets/skills/onboard/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: onboard
+description: Onboard an AI agent to a new project by initializing ThoughtCabinet thoughts repo and bootstrapping agent memory. Use when starting work on a new repository, setting up a fresh project for AI-assisted development, or when the user asks to onboard, bootstrap, or initialize a project.
+---
+
+# Onboarding a New Project
+
+Set up a new project for AI-assisted development: initialize the thoughts repo and bootstrap agent memory in one workflow.
+
+## Workflow Context
+
+This skill orchestrates two capabilities that are normally run separately:
+- `thc init` — connects the project to a thoughts repo
+- `init-agent-memory` skill — creates AGENTS.md and supporting docs
+
+After onboarding, the project is ready for skills like `creating-plan`, `research-codebase`, and `implementing-plan`.
+
+## Workflow Overview
+
+1. **Pre-flight + Initialize thoughts** - Run `onboard.sh`: check environment, run `thc init`
+2. **Bootstrap agent memory** - Invoke `init-agent-memory` skill (if needed)
+3. **Verify** - Run `onboard.sh --verify-only`: confirm everything is wired up
+
+## Step 1: Pre-flight and Initialize Thoughts
+
+Run: `bash onboard.sh`
+
+**Exit codes determine next action**:
+- **1** — Fatal error (not a git repo, thc missing, init failed). Stop and report.
+- **2** — Thoughts ready, AGENTS.md not found. Proceed to Step 2.
+- **3** — Thoughts + AGENTS.md both exist. Ask user if they want to regenerate memory or skip to Step 3.
+
+If thoughts was already initialized and user wants to re-initialize:
+```bash
+bash onboard.sh --force
+```
+
+## Step 2: Bootstrap Agent Memory
+
+**If AGENTS.md already exists**: Ask the user whether to regenerate or skip.
+
+**If AGENTS.md does not exist**: Invoke the `init-agent-memory` skill.
+
+**Note**: `thoughts/CLAUDE.md` (from Step 1) and root `CLAUDE.md` (from this step) serve different purposes:
+- `thoughts/CLAUDE.md` — thoughts directory usage rules
+- `./CLAUDE.md` — project memory for the AI agent (symlink to AGENTS.md)
+
+## Step 3: Verify and Present
+
+Run: `bash onboard.sh --verify-only`
+
+Present results to user:
+
+```
+Project onboarding complete!
+
+- thoughts/ connected to [thoughts repo path]
+- AGENTS.md created with project context
+- Git hooks installed (auto-sync on commit)
+
+You're ready to use skills like /creating-plan, /research-codebase, and /implementing-plan.
+```
+
+If any step was skipped or failed, note it clearly with suggested remediation.
+
+## Guidelines
+
+**Be incremental**: Re-running the skill should be safe — each step skips if already done.
+
+**Fail fast**: If a critical step fails, stop and report rather than continuing with a broken setup.
+
+**Minimal prompting**: Only ask questions when the answer cannot be inferred from the environment.
+
+**Respect existing work**: Never overwrite AGENTS.md, CLAUDE.md, or thoughts/ without explicit user confirmation.