thought-cabinet 0.1.8 → 0.1.10

package/README.md

@@ -1,6 +1,6 @@
 # Thought Cabinet
 
-A CLI tool that integrates AI coding agents into structured development workflows through filesystem-based memory and context management.
+A CLI tool that gives AI coding agents persistent, structured memory through filesystem-based notes and version-controlled knowledge sharing.
 
 ## Why Thought Cabinet?
 
@@ -18,75 +18,58 @@ Thought Cabinet solves these by providing:
 - **Structured workflows**: Slash commands guide agents through research → plan → implement → validate
 - **Team sharing**: Thoughts sync via git, enabling knowledge sharing
 
-## Core Concepts
-
-### Thoughts as Memory
-
-The `thoughts/` directory is a filesystem-based memory system for AI agents:
-
-```
-thoughts/
-├── {user}/           → Personal notes (your learnings, scratchpad)
-├── shared/           → Team-shared knowledge
-│   ├── research/     → Codebase research documents
-│   └── plans/        → Implementation plans
-└── global/           → Cross-repository thoughts
-```
-
-All thoughts are version-controlled via a dedicated git repository, separate from your code.
-
-### Structured Workflows
-
-Instead of asking an AI to "implement feature X" directly, Thought Cabinet encourages a disciplined workflow:
-
-1. **Research** → Understand the codebase deeply
-2. **Plan** → Design the implementation with explicit phases
-3. **Implement** → Execute the plan systematically
-4. **Validate** → Verify against success criteria
+## Quick Start
 
-### Worktree Isolation
+```bash
+cd your-project
 
-Each feature gets its own git worktree with a dedicated tmux session, enabling:
+# 1. Install
+npm install -g thought-cabinet
 
-- Parallel development on multiple features
-- Clean separation between research (main branch) and implementation (worktree)
-- Easy cleanup and merge when done
+# 2. Initialize thoughts in your project
+thc init
 
-## Installation
+# 3. Install skills to your AI agent
+thc agent init
 
-```bash
-npm install -g thought-cabinet
+# 4. Use skills in your agent session (e.g. Claude Code)
+> /researching-codebase How does the authentication system work?
+> /creating-plan Add OAuth2 support based on the research
+> /implementing-plan thoughts/shared/plans/add-oauth.md
+> /validating-plan thoughts/shared/plans/add-oauth.md
 ```
 
-## Claude Code Integration
-
-Thought Cabinet provides slash commands, agents, and skills that integrate with Claude Code. Install them via `thc agent init`.
+## Skills
 
-### Installing Agent Configuration
+Skills are installed by `thc agent init` and invoked as slash commands in your agent session:
 
-```bash
-cd your-project
-thc agent init
-```
+| Skill                   | Description                                                           |
+| ----------------------- | --------------------------------------------------------------------- |
+| `/researching-codebase` | Deep-dive into codebase, save findings to `thoughts/shared/research/` |
+| `/creating-plan`        | Create implementation plan with phases and success criteria           |
+| `/iterating-plan`       | Refine existing plans based on feedback                               |
+| `/implementing-plan`    | Execute plan phase-by-phase with verification                         |
+| `/validating-plan`      | Verify implementation against plan's success criteria                 |
+| `/commit`               | Create git commits with clear, descriptive messages                   |
 
-This interactively discovers and installs assets to your agent's config directory (e.g. `.claude/`):
+**Typical workflow**: research the codebase to build understanding, create a plan, iterate until the plan is solid, implement it, then validate the result.
 
-- **Agents** - Specialized sub-agents for code analysis and research
-- **Skills** - Extended capabilities like structured workflows and document generation
+## Core Concepts
 
-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.
+### Thoughts as Memory
 
-### Slash Commands
+The `thoughts/` directory is a filesystem-based memory system for AI agents:
 
-These commands guide the AI through each phase of development:
+```
+thoughts/
+├── {user}/           → Personal notes (your learnings, scratchpad)
+├── shared/           → Team-shared knowledge
+│   ├── research/     → Codebase research documents
+│   └── plans/        → Implementation plans
+└── global/           → Cross-repository thoughts
+```
 
-| Command              | Purpose                                                               |
-| -------------------- | --------------------------------------------------------------------- |
-| `/research_codebase` | Deep-dive into codebase, save findings to `thoughts/shared/research/` |
-| `/create_plan`       | Create implementation plan with phases and success criteria           |
-| `/iterate_plan`      | Refine existing plans based on feedback                               |
-| `/implement_plan`    | Execute plan phase-by-phase with verification                         |
-| `/validate_plan`     | Verify implementation against plan's success criteria                 |
+All thoughts are version-controlled via a dedicated git repository, separate from your code. Sync with `thc sync`.
 
 ### Context Offloading
 
@@ -102,270 +85,24 @@ AI agents have limited context windows. Thought Cabinet offloads context to the
 └─────────────────┘     └─────────────────────────────┘
 ```
 
-- `/research_codebase` writes comprehensive analysis to disk, then only the relevant sections are read when needed
-- `/create_plan` produces detailed plans that persist across sessions
-- The AI can reference previous research without re-exploring the entire codebase
-
-### Filesystem-Based Memory
-
-Unlike conversation history that disappears, thoughts persist:
-
-```bash
-# Research from last week is still available
-cat thoughts/shared/research/2024-01-05-payment-system.md
-
-# Plans from past features inform new ones
-ls thoughts/shared/plans/
-
-# Personal learnings accumulate
-cat thoughts/yourusername/gotchas.md
-```
-
-All thoughts are git-tracked, so you can:
-
-- Share knowledge with team members via `thc sync`
-- See how understanding evolved over time
-- Recover context even after months
-
-## The Worktree + tmux + Parallel Workflow
-
-For complex features, Thought Cabinet enables a powerful parallel workflow:
-
-### Phase 1: Research & Planning (Main Branch)
-
-```bash
-# In your main branch, start Claude Code
-cd your-project
-claude
-
-# Research the codebase
-> /research_codebase
-> How does the authentication system work?
-
-# Create an implementation plan
-> /create_plan
-> Add OAuth2 support based on the research
-
-# Iterate until the plan is solid
-> /iterate_plan thoughts/shared/plans/add-oauth.md
-```
-
-### Phase 2: Create Worktree
-
-```bash
-# Create isolated worktree with tmux session
-thc worktree add add-oauth
-
-# This creates:
-# - New git worktree at ../your-project-add-oauth/
-# - Dedicated tmux session (thc-add-oauth)
-# - Thoughts initialized and synced in worktree
-```
-
-### Phase 3: Parallel Implementation (Worktree)
-
-In the worktree's tmux session:
-
-```bash
-# Start Claude Code in the worktree
-claude
-
-# Implement the plan (the plan persists from main branch!)
-> /implement_plan thoughts/shared/plans/add-oauth.md
-
-# Validate against success criteria
-> /validate_plan thoughts/shared/plans/add-oauth.md
-```
-
-**Parallel work**: While implementation runs, you can continue other work in the main branch. Multiple worktrees can run simultaneously.
-
-### Phase 4: Merge & Cleanup
-
-```bash
-# Back in main branch
-thc worktree merge add-oauth
-
-# This:
-# - Rebases the feature branch
-# - Fast-forward merges to target
-# - Cleans up worktree and tmux session
-# - Syncs thoughts
-```
-
-### Workflow Diagram
-
-```
-Main Branch                    Worktree (parallel)
-    │
-    ├── /research_codebase
-    │   └── writes to thoughts/shared/research/
-    │
-    ├── /create_plan
-    │   └── writes to thoughts/shared/plans/
-    │
-    ├── /iterate_plan (until ready)
-    │
-    ├── thc worktree add ──────────────────┐
-    │                                      │
-    │   (continue other work here)         ├── /implement_plan
-    │                                      │   └── reads plan, writes code
-    │                                      │
-    │                                      ├── /validate_plan
-    │                                      │   └── verifies success criteria
-    │                                      │
-    ├── thc worktree merge ←───────────────┘
-    │
-    ▼
-```
-
-## Quick Start
-
-### Initialize Thoughts
-
-```bash
-cd your-project
-thc init
-```
-
-This sets up:
-
-- A global thoughts repository (default: `~/thoughts`)
-- Directory structure for this project
-- Git hooks for protection and auto-sync
-- Symlinks in `thoughts/` directory
-
-### Basic Usage
-
-```bash
-# Edit thoughts directly
-vim thoughts/yourusername/notes.md
-
-# Sync changes
-thc sync
-
-# Check status
-thc status
-```
-
-### Worktree Commands
-
-```bash
-# Create worktree with tmux session
-thc worktree add feature-name
-
-# List active worktrees
-thc worktree list
-
-# Merge and cleanup
-thc worktree merge feature-name
-```
-
-## CLI Commands
-
-### Agent Configuration
-
-```bash
-thc agent init                    # Interactively install agents and skills
-thc agent init --all              # Install all without prompting (symlink mode)
-thc agent init --force            # Overwrite existing installations
-thc agent init --agent cursor     # Install for a specific agent
-thc agent init --global           # Install to global scope
-```
-
-### Thoughts Management
-
-```bash
-thc init              # Initialize thoughts for current repository
-thc sync              # Sync thoughts to repository
-thc status            # Show status of thoughts repository
-thc destroy           # Remove thoughts setup from repository
-thc prune             # Clean up stale repository mappings
-```
-
-### Worktree Management
-
-```bash
-thc worktree add <name>     # Create worktree + tmux session
-thc worktree list           # List worktrees and sessions
-thc worktree merge <name>   # Merge and cleanup worktree
-```
-
-### Profiles
-
-Use different thoughts repositories for different contexts (work, personal):
-
-```bash
-thc profile create <name>   # Create a new profile
-thc profile list            # List all profiles
-thc init --profile work     # Initialize with specific profile
-```
-
-### Configuration
-
-```bash
-thc config           # View configuration
-thc config --edit    # Edit configuration
-```
-
-Configuration is stored in `~/.config/thought-cabinet/config.json`.
-
-## Hooks
-
-### Custom Hooks
-
-Configure hooks in `.thought-cabinet/hooks.json` to run commands on events:
-
-```json
-{
-  "hooks": {
-    "PostWorktreeAdd": [
-      {
-        "hooks": [{ "type": "command", "command": "npm install", "timeout": 300 }]
-      }
-    ]
-  }
-}
-```
-
-**Available events:**
-
-- `PreWorktreeAdd`, `PostWorktreeAdd` - Worktree creation
-- `PreWorktreeMerge`, `PostWorktreeMerge` - Worktree merge
-- `PostThoughtsInit`, `PostThoughtsDestroy`, `PostThoughtsSync` - Thoughts lifecycle
-
-### Git Hooks
-
-Automatically installed git hooks:
-
-- **pre-commit**: Prevents accidental commits of `thoughts/` directory
-- **post-commit**: Auto-syncs thoughts after each commit
-
-## Directory Structure
-
-```
-your-project/
-└── thoughts/
-    ├── yourusername/    → Personal notes for this project
-    ├── shared/          → Team-shared notes
-    │   ├── research/    → Codebase research documents
-    │   └── plans/       → Implementation plans
-    ├── global/          → Cross-project thoughts
-    └── searchable/      → Hard links for grep/ripgrep
-```
+Research and plans are written to disk. The agent reads back only what it needs, freeing context for active work.
 
-## Best Practices
+## CLI Overview
 
-**For AI-assisted development:**
+| Command          | Description                                       |
+| ---------------- | ------------------------------------------------- |
+| `thc init`       | Initialize thoughts for current repository        |
+| `thc sync`       | Sync thoughts to git repository                   |
+| `thc status`     | Show thoughts repository status                   |
+| `thc agent init` | Install skills and agents to your AI coding agent |
+| `thc config`     | View or edit configuration                        |
 
-- Always run `/research_codebase` before planning complex features
-- Use `/create_plan` to make implementation explicit and verifiable
-- Implement in worktrees for maximum throughput
-- Run `/validate_plan` before merging to catch deviations
+See [docs/CLI.md](docs/CLI.md) for the full command reference with all flags and options.
 
-**General tips:**
+## Advanced Topics
 
-- Run `thc sync` frequently to share knowledge
-- Use `thc prune` to clean up stale mappings
+- **[Worktrees](docs/WORKTREES.md)** — Parallel development with git worktrees and tmux sessions
+- **[Hooks](docs/HOOKS.md)** — Custom hooks that run on thought and worktree lifecycle events
 
 ## License
 
@@ -373,5 +110,5 @@ Apache-2.0
 
 ## Credits
 
-- the name "Thought Cabinet" is from CRPG [Disco Elysium](https://en.wikipedia.org/wiki/Disco_Elysium) created by Robert Kurvitz, Aleksander Rostov, Helen Hindpere and others
-- the thoughts system is based on [humanlayer](https://github.com/humanlayer/humanlayer)
+- The name "Thought Cabinet" is from CRPG [Disco Elysium](https://en.wikipedia.org/wiki/Disco_Elysium) created by Robert Kurvitz, Aleksander Rostov, Helen Hindpere and others
+- The thoughts system is based on [humanlayer](https://github.com/humanlayer/humanlayer)

package/dist/index.js

@@ -2797,8 +2797,8 @@ async function agentInitCommand(options) {
 // src/commands/agent.ts
 function agentCommand(program) {
   const agent = program.command("agent").description("Manage coding agent configuration");
-  agent.command("init").description("Initialize coding agent configuration in current directory").option("--agent <agents...>", "Target agents (e.g., claude-code codebuddy cursor)").option("-g, --global", "Install to global scope").option("--mode <mode>", "Installation mode: symlink or copy (default: symlink)").option("--source <path>", "Source directory for assets").option("--force", "Force overwrite of existing installations").option("--all", "Install all assets without prompting").action(async (options) => {
-    const agentTypes = options.agent?.map((a) => {
+  agent.command("init").description("Initialize coding agent configuration in current directory").option("--target <agents...>", "Target agents (e.g., claude-code codebuddy cursor)").option("-g, --global", "Install to global scope").option("--mode <mode>", "Installation mode: symlink or copy (default: symlink)").option("--source <path>", "Source directory for assets").option("--force", "Force overwrite of existing installations").option("--all", "Install all assets without prompting").action(async (options) => {
+    const agentTypes = options.target?.map((a) => {
       if (!isValidAgentType(a)) {
         console.error(`Unknown agent: ${a}`);
         process.exit(1);
@@ -3562,11 +3562,11 @@ function hooksCommand(program) {
 function completionCommand(program) {
   const completion = program.command("completion").description("Manage shell completion for thoughtcabinet CLI");
   completion.command("install").description("Install shell completion scripts").action(async () => {
-    const { install } = await import("./installer-LJ3SJXPW.js");
+    const { install } = await import("./installer-RE5BSCVX.js");
     await install();
   });
   completion.command("uninstall").description("Remove shell completion scripts").action(async () => {
-    const { uninstall } = await import("./installer-LJ3SJXPW.js");
+    const { uninstall } = await import("./installer-RE5BSCVX.js");
     await uninstall();
   });
 }
@@ -3656,7 +3656,7 @@ var OPTIONS = {
   "worktree list": ["--all"],
   "worktree merge": ["--into", "--force", "--keep-session", "--keep-worktree", "--keep-branch"],
   "worktree remove": ["--force"],
-  "agent init": ["--force", "--all", "--agent", "--global", "--mode", "--source"]
+  "agent init": ["--force", "--all", "--target", "--global", "--mode", "--source"]
 };
 var DYNAMIC_ARGS = {
   "profile show": getProfileNames,
@@ -3669,7 +3669,7 @@ var DYNAMIC_OPTIONS = {
   "--branch": getBranchNames,
   "--base": getBranchNames,
   "--into": getBranchNames,
-  "--agent": getAgentNames,
+  "--target": getAgentNames,
   "--mode": () => ["symlink", "copy"]
 };
 async function handleCompletion() {