thought-cabinet 0.1.13 → 0.2.0

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.0",
   "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/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,10 @@ 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. Identify the testable behaviors the phase introduces or changes
+3. Apply the `test-driven-development` RED-GREEN-REFACTOR cycle for each behavior
+4. Only after all TDD cycles are complete, proceed to the completion checklist below
 
 ## 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/test-driven-development/SKILL.md

@@ -198,4 +198,9 @@ When working within a plan phase:
 
 The phase's automated verification is the final gate. TDD cycles happen within that gate, not instead of it.
 
-**When the plan says tests aren't needed**: Evaluate independently — apply TDD unless genuinely untestable (pure wiring, no behavioral logic). Document any skip with a reason in the phase completion message.
+**When the plan says tests aren't needed**: Evaluate independently — the plan may be wrong. Read existing test files first. Apply TDD unless the code meets ALL of these criteria:
+1. Zero conditional logic (no if/else, switches, ternaries, or loops with conditions)
+2. Zero data transformation (no mapping, filtering, formatting, restructuring)
+3. The function is a pure pass-through calling already-tested functions with static arguments
+
+"Wiring", "integration-level", "mostly delegation", and "would require too many mocks" are NOT valid skip reasons. Document any skip with the specific criterion (1-3) that applies.

package/src/agent-assets/skills/writing-skill/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: writing-skill
+description: Create, revise, or distill workflows into skills following best practices. Use when user asks to create a new skill, iterate on an existing skill, distill a session workflow into a reusable skill, or improve skill quality.
+---
+
+# Writing Skills
+
+Create new skills, revise existing ones, or distill workflows into reusable skills. Follow [best practices](best-practices.md) and use [skill-template](skill-template.md).
+
+## Workflow Context
+
+This meta-skill produces skills. Common skill patterns:
+- **Complex workflow** — Multiple phases, planning/implementation/validation
+- **Research/synthesis** — Discovery, analysis, pattern extraction
+- **Simple imperative** — Single task, straightforward execution
+- **Integration-focused** — Modifies/enhances other workflows
+
+**Skills are saved to your Thought Cabinet skills directory**:
+- `~/.thought-cabinet/skills/` (new)
+- `~/.config/thought-cabinet/skills/` (legacy, if config exists there)
+
+## Determine the Mode
+
+Infer from user query:
+- "create", "new", "write" → Step 1
+- "revise", "update", "fix", "improve", "modify" → Step 2  
+- "distill", "extract", "turn into skill" → Step 3
+
+Only ask if ambiguous.
+
+---
+
+## Step 1: Create New Skill
+
+### 1a. Requirements
+
+Only ask what user hasn't provided:
+- Task automated/guided
+- Trigger contexts (words/situations)
+- Inputs needed and outputs produced
+- Relation to existing skills
+
+### 1b. Resolve Skills Directory
+
+```bash
+# Check for existing config
+if [ -f ~/.thought-cabinet/config.json ]; then
+  export THC_SKILLS_DIR=~/.thought-cabinet/skills
+elif [ -f ~/.config/thought-cabinet/config.json ]; then
+  export THC_SKILLS_DIR=~/.config/thought-cabinet/skills
+else
+  export THC_SKILLS_DIR=~/.thought-cabinet/skills
+fi
+
+mkdir -p "$THC_SKILLS_DIR"
+```
+
+Save to `$THC_SKILLS_DIR/[skill-name]/`.
+
+### 1c. Research Patterns
+
+Spawn parallel sub-agents to searche for analog skills in skill directories:
+- `$THC_SKILLS_DIR`
+- agent skill directories, e.g. `~/.claude/skills/` and `.claude/skills/` for Claude Code
+
+**Choose analog** based on characteristics:
+- Multi-phase workflow → find complex workflow skills
+- Simple imperative → find single-task skills
+- Research/synthesis → find discovery/analysis skills
+- Integration-focused → find skills that modify/enhance other workflows
+
+### 1d. Design Present
+
+```
+**Name**: kebab-case-name
+**Description**: Third-person, specific, includes triggers
+**Modeled after**: [skill pattern] + rationale
+**Save to**: $THC_SKILLS_DIR/[skill-name]
+
+**Workflow**:
+1. Step - action
+2. Step - action
+
+**Integration**: how it connects
+
+**Files**: SKILL.md, [supplements + rationale]
+
+Confirm before writing?
+```
+
+### 1e. Write
+
+1. Create `$THC_SKILLS_DIR/[skill-name]/`
+2. Write SKILL.md following template
+3. Add supplementary files
+4. Verify against analog skill
+
+### 1f. Quality Check
+
+Run the checklist from best-practices.md:
+- [ ] Description specific with triggers
+- [ ] Under 500 lines
+- [ ] Concise (no unnecessary explanations)
+- [ ] Consistent terminology
+- [ ] One-level references
+- [ ] Clear workflow steps
+- [ ] Integrates naturally
+
+```
+Created: $THC_SKILLS_DIR/[name]/SKILL.md
+Key decisions: [rationales]
+Quality: [x] passes checklist
+```
+
+### 1g. Install Skill
+
+Make the skill available:
+
+```bash
+thc skill install --target [agent-name] --force
+```
+
+---
+
+## Step 2: Revise Existing Skill
+
+### 2a. Locate Skills Directory
+
+Resolve directory (Step 1b), then list available skills:
+```bash
+ls -la "$THC_SKILLS_DIR"
+```
+
+### 2b. Audit
+
+Read SKILL.md and best-practices.md.
+
+```
+**Strengths**: [what works]
+**Issues**: [specific problems from checklist]
+**Changes**: 1. [change] 2. [change]
+
+Which changes?
+```
+
+### 2c. Apply
+
+Make surgical edits to `$THC_SKILLS_DIR/[skill-name]/`. Maintain structure unless changing it.
+
+```
+Updated [skill-name]:
+- [change 1]
+- [change 2]
+Quality check passed. Further?
+```
+
+---
+
+## Step 3: Distill Session Workflow
+
+### 3a. Extract
+
+```
+**Task pattern**: what we did
+**Steps**: 1. [step] 2. [step]
+**Context needed**: what helps future runs
+**Proposed name**: kebab-case-name
+Save to: $THC_SKILLS_DIR/[name]/
+Create?
+```
+
+### 3b. Generalize
+
+Replace specifics with patterns, frameworks. Remove session artifacts.
+
+### 3c. Write
+
+Resolve directory (Step 1b), then follow Step 1e-1g.
+
+---
+
+## Sync to Source (thought-cabinet repo only)
+
+After creating, revising, or distilling a skill, check if you're working inside the `thought-cabinet` repository:
+
+```bash
+# Check if src/agent-assets/skills/ exists in the repo root
+if [ -d "$(git rev-parse --show-toplevel 2>/dev/null)/src/agent-assets/skills" ]; then
+  REPO_ROOT="$(git rev-parse --show-toplevel)"
+  # Copy the skill directory into the bundled assets
+  cp -r "$THC_SKILLS_DIR/[skill-name]" "$REPO_ROOT/src/agent-assets/skills/[skill-name]"
+fi
+```
+
+This ensures new or updated skills are tracked in `src/agent-assets/skills/` for packaging and distribution. The copy goes into the repo's working tree — it is NOT committed automatically.
+
+---
+
+## Guidelines
+
+**Conciseness**: Challenge every paragraph — does it justify its token cost?
+
+**Integration**: Reference related skills in Workflow Context. Match tone/structure to analog.
+
+**Iterate**: Ship minimal working skill, refine from usage.
+
+**Config Compatibility**: Check `~/.thought-cabinet/` (new) and `~/.config/thought-cabinet/` (legacy). Use existing location; default to new.