thought-cabinet 0.0.4 → 0.1.1

package/.thought-cabinet/hooks.example.json

@@ -0,0 +1,34 @@
+{
+  "hooks": {
+    "PostWorktreeAdd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Worktree @ $THC_WORKTREE_PATH successfully added'"
+          }
+        ]
+      }
+    ],
+    "PostWorktreeMerge": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Worktree merged successfully'"
+          }
+        ]
+      }
+    ],
+    "PostThoughtsSync": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Thoughts synced at $(date)' >> .thought-cabinet/sync.log"
+          }
+        ]
+      }
+    ]
+  }
+}

package/LICENSE

@@ -1,6 +1,192 @@
-Apache Software License 2.0
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
 
-Copyright (c) 2025, Thought Cabinet Authors
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "[]"
+replaced with your own identifying information. (Don't include
+the brackets!)  The text should be enclosed in the appropriate
+comment syntax for the file format. We also recommend that a
+file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier
+identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

package/README.md

@@ -1,18 +1,56 @@
 # Thought Cabinet
 
-A CLI tool for managing developer thoughts and notes across multiple repositories.
+A CLI tool that integrates AI coding agents into structured development workflows through filesystem-based memory and context management.
 
-## Overview
+## Why Thought Cabinet?
 
-Thought Cabinet provides a systematic way to organize and version-control your development notes, decisions, and ideas. It synchronizes thoughts across a dedicated git repository while keeping them separate from your code repositories.
+AI coding agents like Claude Code are powerful but face key challenges:
 
-## Features
+- **Context limits**: Large codebases exceed model context windows
+- **No persistent memory**: Agents forget learnings between sessions
+- **Unstructured work**: Complex tasks benefit from planning before implementation
+- **Isolation**: AI-generated knowledge isn't easily shared with teams
 
-- **Multi-repository support**: Manage thoughts for multiple projects from a single thoughts repository
-- **Profile support**: Use different thoughts repositories for different contexts (e.g., work, personal)
-- **Git integration**: Automatic git hooks prevent accidental commits and auto-sync thoughts
-- **Searchable index**: Hard links enable fast searching across all thoughts
-- **User separation**: Personal and shared thought spaces for team collaboration
+Thought Cabinet solves these by providing:
+
+- **Context offloading**: Research and plans are saved to disk, freeing model context
+- **Filesystem memory**: Version-controlled thoughts persist across sessions
+- **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
+
+### Worktree Isolation
+
+Each feature gets its own git worktree with a dedicated tmux session, enabling:
+
+- Parallel development on multiple features
+- Clean separation between research (main branch) and implementation (worktree)
+- Easy cleanup and merge when done
 
 ## Installation
 
@@ -20,126 +58,320 @@ Thought Cabinet provides a systematic way to organize and version-control your d
 npm install -g thought-cabinet
 ```
 
-## Quick Start
+## Claude Code Integration
 
-### Initialize thoughts for a repository
+Thought Cabinet provides slash commands, agents, and skills that integrate with Claude Code. Install them via `thc agent init`.
+
+### Installing Agent Configuration
 
 ```bash
 cd your-project
-thoughtcabinet init
+thc agent init
+```
+
+This interactively installs to `.claude/`:
+- **Commands** - Slash commands for workflow phases (`/research_codebase`, `/create_plan`, etc.)
+- **Agents** - Specialized sub-agents for code analysis and research
+- **Skills** - Extended capabilities like document generation
+- **Settings** - Project permissions and configuration
+
+Options:
+```bash
+thc agent init --all              # Copy all files without prompting
+thc agent init --force            # Overwrite existing .claude directory
+thc agent init --name codebuddy   # Use alternative agent (codebuddy)
+```
+
+### Slash Commands
+
+These commands guide the AI through each phase of development:
+
+| 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 |
+
+### Context Offloading
+
+AI agents have limited context windows. Thought Cabinet offloads context to the filesystem:
+
+```
+┌─────────────────┐     ┌─────────────────────────────┐
+│  Model Context  │     │  filesystem (thoughts/)     │
+├─────────────────┤     ├─────────────────────────────┤
+│ Current task    │ ←── │ research/auth-system.md     │
+│ Active code     │     │ plans/add-oauth.md          │
+│ Recent changes  │     │ previous session learnings  │
+└─────────────────┘     └─────────────────────────────┘
 ```
 
-This will:
+- `/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
 
-1. Set up a global thoughts repository (default: `~/thoughts`)
-2. Create directory structure for this project
-3. Install git hooks for protection and auto-sync
-4. Create symlinks in `thoughts/` directory
+### Filesystem-Based Memory
 
-### Sync thoughts manually
+Unlike conversation history that disappears, thoughts persist:
 
 ```bash
-thoughtcabinet sync
+# 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
 ```
 
-### Check status
+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
-thoughtcabinet status
+# 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
 ```
 
-## Directory Structure
+### Phase 2: Create Worktree
 
-After initialization, your repository will have:
+```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
 ```
-your-project/
-└── thoughts/
-    ├── yourusername/    → Your personal notes for this project
-    ├── shared/          → Team-shared notes for this project
-    ├── global/          → Cross-project thoughts
-    │   ├── yourusername/ - Your personal cross-repo notes
-    │   └── shared/      - Team cross-repo notes
-    └── searchable/      → Hard links for searching
+
+### 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
 ```
 
-## Commands
+**Parallel work**: While implementation runs, you can continue other work in the main branch. Multiple worktrees can run simultaneously.
 
-### Basic Commands
+### Phase 4: Merge & Cleanup
 
-- `thoughtcabinet init` - Initialize thoughts for current repository
-- `thoughtcabinet sync` - Manually sync thoughts to repository
-- `thoughtcabinet status` - Show status of thoughts repository
-- `thoughtcabinet config` - View or edit configuration
-- `thoughtcabinet destroy` - Remove thoughts setup from current repository
+```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
+```
 
-### Profile Commands
+### Workflow Diagram
 
-Profiles allow you to use different thoughts repositories for different contexts:
+```
+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 ←───────────────┘
+    │
+    ▼
+```
 
-- `thoughtcabinet profile create <name>` - Create a new profile
-- `thoughtcabinet profile list` - List all profiles
-- `thoughtcabinet profile show <name>` - Show profile details
-- `thoughtcabinet profile delete <name>` - Delete a profile
+## Quick Start
 
-Use a profile with:
+### Initialize Thoughts
 
 ```bash
-thoughtcabinet init --profile work
+cd your-project
+thc init
 ```
 
-## Configuration
+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
 
-Configuration is stored in `~/.config/thought-cabinet/config.json`.
+### Basic Usage
 
-View configuration:
+```bash
+# Edit thoughts directly
+vim thoughts/yourusername/notes.md
+
+# Sync changes
+thc sync
+
+# Check status
+thc status
+```
+
+### Worktree Commands
 
 ```bash
-thoughtcabinet config
+# Create worktree with tmux session
+thc worktree add feature-name
+
+# List active worktrees
+thc worktree list
+
+# Merge and cleanup
+thc worktree merge feature-name
 ```
 
-Edit configuration:
+## CLI Commands
+
+### Agent Configuration
 
 ```bash
-thoughtcabinet config --edit
+thc agent init            # Install Claude Code slash commands, agents, and skills
+thc agent init --all      # Install all without prompting
+thc agent init --force    # Overwrite existing configuration
 ```
 
-## Git Hooks
+### Thoughts Management
 
-Thought Cabinet installs two git hooks:
+```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
+```
 
-1. **pre-commit**: Prevents accidental commits of the `thoughts/` directory
-2. **post-commit**: Auto-syncs thoughts after each code commit
+### Worktree Management
 
-## Searching Thoughts
+```bash
+thc worktree add <name>     # Create worktree + tmux session
+thc worktree list           # List worktrees and sessions
+thc worktree merge <name>   # Merge and cleanup worktree
+```
 
-The `thoughts/searchable/` directory contains hard links to all accessible thought files. This allows search tools to find content without following symlinks:
+### Profiles
+
+Use different thoughts repositories for different contexts (work, personal):
 
 ```bash
-cd your-project
-grep -r "TODO" thoughts/searchable/
+thc profile create <name>   # Create a new profile
+thc profile list            # List all profiles
+thc init --profile work     # Initialize with specific profile
 ```
 
-**Important**: Always reference files by their canonical path (e.g., `thoughts/yourusername/todo.md`) rather than the searchable path.
+### Configuration
 
-## Best Practices
+```bash
+thc config           # View configuration
+thc config --edit    # Edit configuration
+```
+
+Configuration is stored in `~/.config/thought-cabinet/config.json`.
+
+## Hooks
 
-1. Use `yourusername/` for personal, repository-specific notes
-2. Use `shared/` for team documentation that should be version-controlled
-3. Use `global/yourusername/` for cross-repository personal notes
-4. Use `global/shared/` for cross-repository team documentation
-5. Run `thoughtcabinet sync` before sharing important updates
-6. Never commit the `thoughts/` directory to your code repository
+### Custom Hooks
 
-## Migration from hlyr
+Configure hooks in `.thought-cabinet/hooks.json` to run commands on events:
 
-If you're migrating from the hlyr thoughts system:
+```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
 
-1. The configuration format is compatible
-2. Your existing thoughts repository will work as-is
-3. Run `thoughtcabinet init` in your repositories
-4. Old git hooks will be automatically updated
+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
+```
+
+## Best Practices
+
+**For AI-assisted development:**
+- 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
+
+**General tips:**
+- Run `thc sync` frequently to share knowledge
+- Use `thc prune` to clean up stale mappings
 
 ## License
 
 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)