thought-cabinet 0.1.11 → 0.1.12

package/README.md

@@ -24,7 +24,7 @@ Thought Cabinet solves these by providing:
 cd your-project
 
 # 1. Install
-npm install -g thought-cabinet
+pnpm install -g thought-cabinet
 
 # 2. Initialize thoughts in your project
 thc init
@@ -33,7 +33,7 @@ thc init
 thc agent init
 
 # 4. Use skills in your agent session (e.g. Claude Code)
-> /researching-codebase How does the authentication system work?
+> /research-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
@@ -43,14 +43,14 @@ thc agent init
 
 Skills are installed by `thc agent init` and invoked as slash commands in your agent session:
 
-| 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                   |
+| Skill                | Description                                                           |
+| -------------------- | --------------------------------------------------------------------- |
+| `/research-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                   |
 
 **Typical workflow**: research the codebase to build understanding, create a plan, iterate until the plan is solid, implement it, then validate the result.
 

package/docs/CLI.md

@@ -104,14 +104,14 @@ thc agent init --force                  # Overwrite existing installations
 
 #### Installed Skills
 
-| Skill                | Slash Command           | Description                                                           |
-| -------------------- | ----------------------- | --------------------------------------------------------------------- |
-| researching-codebase | `/researching-codebase` | Deep-dive into codebase, save findings to `thoughts/shared/research/` |
-| creating-plan        | `/creating-plan`        | Create implementation plan with phases and success criteria           |
-| iterating-plan       | `/iterating-plan`       | Refine existing plans based on feedback                               |
-| implementing-plan    | `/implementing-plan`    | Execute plan phase-by-phase with verification                         |
-| validating-plan      | `/validating-plan`      | Verify implementation against plan's success criteria                 |
-| commit               | `/commit`               | Create git commits with clear, descriptive messages                   |
+| Skill             | Slash Command        | Description                                                           |
+| ----------------- | -------------------- | --------------------------------------------------------------------- |
+| research-codebase | `/research-codebase` | Deep-dive into codebase, save findings to `thoughts/shared/research/` |
+| creating-plan     | `/creating-plan`     | Create implementation plan with phases and success criteria           |
+| iterating-plan    | `/iterating-plan`    | Refine existing plans based on feedback                               |
+| implementing-plan | `/implementing-plan` | Execute plan phase-by-phase with verification                         |
+| validating-plan   | `/validating-plan`   | Verify implementation against plan's success criteria                 |
+| commit            | `/commit`            | Create git commits with clear, descriptive messages                   |
 
 #### Installed Agents
 

package/docs/WORKTREES.md

@@ -16,7 +16,7 @@ cd your-project
 claude
 
 # Research the codebase
-> /researching-codebase
+> /research-codebase
 > How does the authentication system work?
 
 # Create an implementation plan
@@ -75,7 +75,7 @@ thc worktree merge add-oauth
 ```
 Main Branch                    Worktree (parallel)
     │
-    ├── /researching-codebase
+    ├── /research-codebase
     │   └── writes to thoughts/shared/research/
     │
     ├── /creating-plan

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thought-cabinet",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Thought Cabinet (thc) — CLI for structured AI coding workflows with filesystem-based memory and context management.",
   "type": "module",
   "main": "dist/index.js",
@@ -21,9 +21,9 @@
     "lint": "eslint . --format stylish",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "prepublishOnly": "npm run clean && npm run build",
+    "prepublishOnly": "pnpm run clean && pnpm run build",
     "test": "vitest run --passWithNoTests",
-    "check": "npm run format:check && npm run lint && npm run test && npm run build",
+    "check": "pnpm run format:check && pnpm run lint && pnpm run test && pnpm run build",
     "clean": "rm -rf dist/"
   },
   "dependencies": {
@@ -31,7 +31,8 @@
     "chalk": "^5.4.1",
     "commander": "^14.0.0",
     "dotenv": "^16.5.0",
-    "tabtab": "^3.0.2"
+    "tabtab": "^3.0.2",
+    "thought-cabinet": "link:"
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
@@ -50,15 +51,11 @@
   "engines": {
     "node": "^20.0.0 || >=22.0.0"
   },
-  "overrides": {
-    "tabtab": {
-      "inquirer": "^10.0.0"
-    },
-    "external-editor": {
-      "tmp": "^0.2.4"
-    },
-    "@typescript-eslint/typescript-estree": {
-      "minimatch": "^10.2.1"
+  "pnpm": {
+    "overrides": {
+      "tabtab>inquirer": "^10.0.0",
+      "external-editor>tmp": "^0.2.4",
+      "@typescript-eslint/typescript-estree>minimatch": "^10.2.1"
     }
   },
   "keywords": [
@@ -75,5 +72,6 @@
     "type": "git",
     "url": "https://github.com/sanbaiw/thought-cabinet"
   },
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "packageManager": "pnpm@10.30.1"
 }

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

@@ -1,22 +1,31 @@
 ---
 name: creating-plan
-description: Create detailed implementation plans through interactive research and iteration. Use when planning new features or changes, or creating technical specifications.
+description: Create detailed implementation plans through interactive research and iteration. Use when planning new features, designing changes, writing technical specs.
 ---
 
 # Creating Implementation Plans
 
 Create detailed implementation plans through an interactive, iterative process. Be skeptical, thorough, and work collaboratively to produce high-quality technical specifications.
 
+## Workflow Context
+
+This skill produces the plan document consumed by downstream skills:
+
+1. **creating-plan** (this skill) — Research, design, write the plan
+2. `implementing-plan` — Execute the plan phase-by-phase, running build/lint/test after each phase
+3. `validating-plan` — Audit the implementation against the plan
+
+The plan file at `thoughts/shared/plans/YYYY-MM-DD-description.md` is the contract between these skills. Write success criteria knowing that `implementing-plan` will run the automated verification commands literally.
+
 ## Workflow Overview
 
-1. **Gather context** - Read provided files, research codebase
-2. **Ask clarifying questions** - Only what research couldn't answer
-3. **Discover and propose options** - Present design choices with tradeoffs
-4. **Structure the plan** - Get approval on phases before detailing
-5. **Write the plan**
-6. **Iterate** - Refine until user is satisfied
+1. **Gather context & clarify** - Research codebase, present understanding, ask only what research couldn't answer
+2. **Research & propose options** - Deeper investigation based on user input, present design choices with tradeoffs
+3. **Structure the plan** - Get approval on phases before detailing
+4. **Write the plan** - Detailed, actionable plan following the template
+5. **Iterate** - Refine until user is satisfied
 
-## Step 1: Context Gathering
+## Step 1: Gather Context & Clarify
 
 ### If Parameters Provided
 
@@ -56,14 +65,19 @@ Questions that my research couldn't answer:
 
 Only ask questions you genuinely cannot answer through code investigation.
 
-## Step 2: Research & Discovery
+## Step 2: Research & Propose Options
 
-If the user corrects any misunderstanding:
+After the user responds to Step 1 (whether confirming understanding, answering questions, or correcting misunderstandings):
+
+**If the user corrects any misunderstanding:**
 1. DO NOT just accept the correction
 2. Spawn new research tasks to verify
 3. Read the specific files/directories mentioned
 4. Only proceed once verified
 
+**If the user confirms understanding or provides answers:**
+Spawn deeper research tasks informed by the user's input to explore the solution space.
+
 ### Spawn Parallel Research Tasks
 
 Use the right agent for each type:
@@ -77,7 +91,7 @@ Use the right agent for each type:
 - `thoughts-locator` - Find research, plans, or decisions
 - `thoughts-analyzer` - Extract insights from relevant documents
 
-Wait for ALL sub-tasks to complete before proceeding.
+Wait for ALL tasks to complete before proceeding.
 
 ### Present Findings
 
@@ -101,7 +115,7 @@ Which approach aligns best with your vision?
 
 ## Step 3: Plan Structure
 
-Once aligned on approach:
+Once aligned on approach, propose the phase structure. Each phase MUST be independently verifiable — see [Phase Independence](#phase-independence) below.
 
 ```
 Here's my proposed plan structure:
@@ -126,6 +140,7 @@ After structure approval:
 1. **Determine file path**: `thoughts/shared/plans/YYYY-MM-DD-description.md`
    - YYYY-MM-DD: today's date
    - description: brief kebab-case summary
+   - If a file already exists at this path, append a numeric suffix (e.g. `-2`) or ask the user
 
 2. **Write plan** using [plan-template.md](plan-template.md)
    - **MUST** Read the template and follow the structure exactly.
@@ -135,7 +150,7 @@ After structure approval:
    thoughtcabinet sync -m "Plan: <description>"
    ```
 
-## Step 5: Review & Iterate
+## Step 5: Iterate
 
 Present the draft location:
 
@@ -152,35 +167,9 @@ Please review it and let me know:
 
 Iterate until the user is satisfied.
 
-## Guidelines
-
-### Be Skeptical
-- Question vague requirements
-- Identify potential issues early
-- Ask "why" and "what about"
-- Don't assume - verify with code
-
-### Be Interactive
-- Don't write the full plan in one shot
-- Get buy-in at each major step
-- Allow course corrections
-- Work collaboratively
-
-### Be Thorough
-- Read all context files COMPLETELY
-- Research actual code patterns using parallel sub-tasks
-- Include specific file paths and line numbers
-- Write measurable success criteria
-
-### Be Practical
-- Focus on incremental, testable changes
-- Consider migration and rollback
-- Think about edge cases
-- Include "what we're NOT doing"
-
-### Phase Independence
+## Phase Independence
 
-Each phase must be independently verifiable. The implementing-plan workflow runs build/lint/test and pauses for manual verification after each phase, so phases cannot have circular dependencies.
+Each phase MUST be independently verifiable. `implementing-plan` runs build/lint/test and pauses for manual verification after each phase, so phases cannot have circular dependencies.
 
 **Requirements:**
 - Code must compile/build after completing each phase alone
@@ -188,14 +177,14 @@ Each phase must be independently verifiable. The implementing-plan workflow runs
 - Success criteria should be testable without implementing later phases
 - Ask: "Can I run build/lint/test and pause for manual verification after this phase alone?"
 
-**Example of a BAD phase structure:**
+**BAD phase structure:**
 ```
 Phase 1: Create command that imports handler
 Phase 2: Create handler module
 ```
 Problem: Phase 1 won't compile until Phase 2 is done.
 
-**Example of a GOOD phase structure:**
+**GOOD phase structure:**
 ```
 Phase 1: Create handler module with core logic
 Phase 2: Create command that imports and uses handler
@@ -209,14 +198,40 @@ Phase 2: Implement handler logic
 ```
 Both phases compile; Phase 1 has minimal but working functionality.
 
+## Guidelines
+
+### Be Skeptical
+- Question vague requirements
+- Identify potential issues early
+- Ask "why" and "what about"
+- Don't assume - verify with code
+
+### Be Interactive
+- Don't write the full plan in one shot
+- Get buy-in at each major step
+- Allow course corrections
+- Work collaboratively
+
+### Be Thorough
+- Read all context files COMPLETELY
+- Research actual code patterns using parallel tasks
+- Include specific file paths and line numbers
+- Write measurable success criteria
+
+### Be Practical
+- Focus on incremental, testable changes
+- Consider migration and rollback
+- Think about edge cases
+- Include "what we're NOT doing"
+
 ### No Open Questions in Final Plan
 - If you encounter open questions, STOP
 - Research or ask for clarification immediately
 - The implementation plan must be complete and actionable
 
-## Sub-task Best Practices
+## Research Task Best Practices
 
-When spawning research sub-tasks:
+When spawning research tasks:
 
 1. **Spawn multiple tasks in parallel** for efficiency
 2. **Each task should be focused** on a specific area

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

@@ -50,6 +50,7 @@
 
 **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]
 
 ```[language]
 // Specific code to add/modify

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

@@ -1,12 +1,37 @@
 ---
 name: implementing-plan
-description: Implement technical plans from thoughts/shared/plans with verification. Use when executing approved implementation plans, or resuming work on partially completed plans.
+description: Implement technical plans from thoughts/shared/plans with verification. Use when executing approved implementation plans, resuming partially completed plans, or when the user mentions execute plan or resume plan.
 ---
 
 # Implementing Plans
 
 Execute approved technical plans from `thoughts/shared/plans/` with verification at each phase.
 
+## Workflow Context
+
+This skill executes plans produced by `creating-plan`:
+
+1. `creating-plan` — Research, design, write the plan
+2. **implementing-plan** (this skill) — Execute phase-by-phase with verification
+3. `validating-plan` — Audit the implementation against the plan
+
+The plan file at `thoughts/shared/plans/` is the contract. Success criteria in the plan are executed literally — automated verification commands are run as written.
+
+### Test-Driven Implementation
+
+**MANDATORY**: Apply the `test-driven-development` skill's RED-GREEN-REFACTOR cycle for every unit of production code written within a phase.
+
+The procedure for each unit of work:
+
+1. Write a failing test (RED)
+2. Write minimal code to pass (GREEN)
+3. Refactor while keeping tests green
+4. Repeat for the next behavior
+
+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.
+
 ## Getting Started
 
 When given a plan path:
@@ -52,14 +77,22 @@ Why this matters: [explanation]
 How should I proceed?
 ```
 
+## Phase Implementation Workflow
+
+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
+
 ## Phase Completion Checklist
 
-After implementing a phase, follow this checklist **in order**:
+After implementing a phase (all TDD cycles done), follow this checklist **in order**:
 
 1. Run automated success criteria checks (compile, tests, etc.)
 2. Fix any issues found
 3. Update checkboxes in the plan file for completed automated verification items
-4. Update progress in todos (TodoWrite)
+4. Update progress in todo list
 5. **STOP** and present the verification message (see below)
 6. **WAIT** for user confirmation before starting next phase
 
@@ -102,7 +135,7 @@ When something isn't working as expected:
 2. Consider if the codebase evolved since the plan was written
 3. Present the mismatch clearly and ask for guidance
 
-Use sub-tasks sparingly - mainly for targeted debugging or exploring unfamiliar territory.
+Use tasks sparingly - mainly for targeted debugging or exploring unfamiliar territory.
 
 ## Guidelines
 

package/src/agent-assets/skills/{researching-codebase → research-codebase}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: researching-codebase
-description: Document codebase as-is with thoughts directory for historical context. Use when exploring how codebase features work, or understanding component interactions, or creating technical documentation of existing systems.
+name: research-codebase
+description: Research and understand how the codebase works, then document findings in thoughts directory. Use when investigating specific code flows or workflows, exploring how features are implemented, understanding component interactions, tracing initialization or lifecycle processes, or answering "how does X work" questions about the codebase.
 ---
 
 # Research Codebase

package/src/agent-assets/skills/test-driven-development/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: test-driven-development
+description: Write tests before implementation code using red-green-refactor. Use when implementing features, fixing bugs, or when the user mentions TDD, test-first, or test-driven.
+---
+
+# Test-Driven Development
+
+Write the test first. Watch it fail. Write minimal code to pass.
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+## Workflow Context
+
+This skill integrates with the plan-based workflow:
+
+- `implementing-plan` executes phases that include success criteria with test commands
+- **test-driven-development** (this skill) governs **how** code within each phase gets written: test-first
+
+When implementing a plan phase, apply TDD to each unit of work within that phase. The phase's automated verification commands are the final check, not a substitute for test-first development.
+
+## Workflow Overview
+
+1. **Discover test infrastructure** - Find test runner, patterns, conventions
+2. **RED** - Write one failing test
+3. **Verify RED** - Run it, confirm correct failure
+4. **GREEN** - Write minimal code to pass
+5. **Verify GREEN** - Run it, confirm all tests pass
+6. **REFACTOR** - Clean up, keep tests green
+7. **Repeat** - Next behavior, next failing test
+
+## Step 1: Discover Test Infrastructure
+
+Before writing any test, research the project's testing setup:
+
+```
+Tasks to spawn concurrently:
+- codebase-locator: Find test files near the code being changed
+- codebase-pattern-finder: Find test patterns (describe/it, test runner config, assertion style)
+```
+
+Identify:
+- Test runner and command (e.g. `npm test`, `pytest`, `make test`)
+- File naming convention (e.g. `*.test.ts`, `*_test.go`, `test_*.py`)
+- Assertion style and test structure used in existing tests
+- Any test utilities or fixtures in the project
+
+Follow existing conventions exactly. Do not introduce new test libraries or patterns unless user explicitly asks for it.
+
+## Step 2: RED - Write Failing Test
+
+Write one minimal test for one behavior.
+
+<Good>
+```typescript
+test('rejects empty email', async () => {
+  const result = await submitForm({ email: '' });
+  expect(result.error).toBe('Email required');
+});
+```
+Clear name describing behavior, tests one thing, uses real code.
+</Good>
+
+<Bad>
+```typescript
+test('works', async () => {
+  const mock = jest.fn().mockResolvedValueOnce('ok');
+  await submitForm(mock);
+  expect(mock).toHaveBeenCalledTimes(1);
+});
+```
+Vague name, tests mock not behavior.
+</Bad>
+
+**Requirements:**
+- One behavior per test
+- Name describes the expected behavior
+- Use real code paths (mocks only when unavoidable — external APIs, databases)
+
+## Step 3: Verify RED - Watch It Fail
+
+**MANDATORY. Never skip.**
+
+Run the test and confirm:
+- Test **fails** (not errors from syntax/import issues)
+- Failure message matches what you expect
+- Fails because the feature is missing, not because of a typo
+
+**Test passes immediately?** You're testing existing behavior. Rewrite the test.
+
+**Test errors instead of failing?** Fix the error first, re-run until it fails correctly.
+
+## Step 4: GREEN - Minimal Code
+
+Write the simplest code that makes the test pass.
+
+<Good>
+```typescript
+async function retryOperation<T>(fn: () => T | Promise<T>): Promise<T> {
+  for (let i = 0; i < 3; i++) {
+    try { return await fn(); }
+    catch (e) { if (i === 2) throw e; }
+  }
+  throw new Error('unreachable');
+}
+```
+Just enough to pass.
+</Good>
+
+<Bad>
+```typescript
+async function retryOperation<T>(
+  fn: () => T | Promise<T>,
+  options?: { maxRetries?: number; backoff?: 'linear' | 'exponential'; onRetry?: (n: number) => void }
+): Promise<T> { /* ... */ }
+```
+Over-engineered beyond what the test requires.
+</Bad>
+
+Do not add features, refactor surrounding code, or "improve" beyond the test.
+
+## Step 5: Verify GREEN - Watch It Pass
+
+**MANDATORY.**
+
+Run the test and confirm:
+- The new test passes
+- All existing tests still pass
+- No errors or warnings in output
+
+**New test fails?** Fix the implementation, not the test.
+
+**Other tests break?** Fix them now before proceeding.
+
+## Step 6: REFACTOR - Clean Up
+
+Only after green:
+- Remove duplication
+- Improve names
+- Extract helpers if warranted
+
+Run tests after each refactoring change. Stay green throughout.
+
+Do not add new behavior during refactoring.
+
+## Step 7: Repeat
+
+Return to Step 2 for the next behavior. Each cycle adds one tested behavior.
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Wrote code before the test? Delete it. Start over from Step 2.
+
+- Do not keep it as "reference"
+- Do not "adapt" it while writing tests
+- Delete means delete
+
+## Good Tests
+
+| Quality | Good | Bad |
+|---------|------|-----|
+| **Minimal** | One behavior | `test('validates email and domain and length')` |
+| **Clear** | Name describes expected behavior | `test('test1')` |
+| **Real** | Tests actual code paths | Tests mock return values |
+| **Focused** | Asserts on outcome | Asserts on internal implementation |
+
+## Red Flags - STOP and Start Over
+
+- Wrote production code before a test
+- Test passes immediately on first run
+- Can't explain why the test failed
+- Rationalizing "just this once"
+- "I already manually tested it"
+- Keeping pre-written code as "reference"
+
+All of these mean: delete the code, start over with a failing test.
+
+## When Stuck
+
+| Problem | Solution |
+|---------|----------|
+| Don't know how to test | Write the API you wish existed. Write the assertion first. Ask the user. |
+| Test too complicated | Design too complicated. Simplify the interface. |
+| Must mock everything | Code too coupled. Use dependency injection. |
+| Test setup huge | Extract helpers. Still complex? Simplify design. |
+
+## Integration with Plan Phases
+
+When working within a plan phase:
+
+1. Read the phase's success criteria
+2. For each unit of work in the phase, apply the RED-GREEN-REFACTOR cycle
+3. After all units are complete, run the phase's automated verification commands
+4. Follow `implementing-plan`'s Phase Completion Checklist: update checkboxes, present the verification message, wait for user confirmation
+
+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.