thought-cabinet 0.2.0 → 0.2.1

package/package.json

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

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

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

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

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

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

@@ -90,9 +90,36 @@ How should I proceed?
 Before writing any production code for a phase:
 
 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
+2. For each change block in the phase, read only the **Testable Behaviors** section — do NOT read the Reference Implementation yet
+3. For each testable behavior bullet, execute one RED-GREEN-REFACTOR cycle:
+   - **RED**: Write one failing test for that behavior. Run it. Confirm it fails for the right reason.
+   - **GREEN**: Write the minimal production code to pass it. Run it. Confirm it passes.
+   - **REFACTOR**: Clean up. Run tests. Stay green.
+4. Only after all behavior bullets have passing tests, read the Reference Implementation and reconcile — adjust your implementation if it diverges from the plan's intent, but do not delete passing tests.
+5. Proceed to the phase completion checklist.
+
+### How to Extract Work Items from a Plan Change Block
+
+A change block looks like:
+
+```
+##### Testable Behaviors (RED tests)
+- `cutoff empty` → `isEnvCreatedAfterCutoff` returns `true`
+- `createTime after cutoff` → returns `true`
+- `createTime before cutoff` → returns `false`
+- `createTime null + cutoff set` → returns `false` (safe fallback)
+
+##### Reference Implementation
+[code]
+```
+
+Map this to a work queue:
+1. `def "isEnvCreatedAfterCutoff: cutoff empty returns true"()` → RED → GREEN
+2. `def "isEnvCreatedAfterCutoff: createTime after cutoff returns true"()` → RED → GREEN
+3. `def "isEnvCreatedAfterCutoff: createTime before cutoff returns false"()` → RED → GREEN
+4. `def "isEnvCreatedAfterCutoff: null createTime with cutoff set returns false"()` → RED → GREEN
+
+Each bullet is one test. Complete all cycles for this change block before moving to the next.
 
 ## Phase Completion Checklist
 

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

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

package/src/agent-assets/skills/onboard/onboard.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# onboard.sh — Pre-flight checks, thoughts init, and verification for the onboard skill.
+#
+# Usage: bash onboard.sh [--force] [--verify-only]
+#   --force        Re-initialize thoughts even if already set up
+#   --verify-only  Skip init, only run verification
+#
+# Exit codes:
+#   0  Success (init completed or already set up)
+#   1  Fatal error (not a git repo, thc missing, init failed)
+#   2  Thoughts already initialized, AGENTS.md not found (agent memory needed)
+#   3  Thoughts already initialized, AGENTS.md exists (fully onboarded)
+
+FORCE=false
+VERIFY_ONLY=false
+for arg in "$@"; do
+  case "$arg" in
+    --force) FORCE=true ;;
+    --verify-only) VERIFY_ONLY=true ;;
+  esac
+done
+
+# --- Helpers ---
+
+resolve_thc() {
+  if command -v thc > /dev/null 2>&1; then
+    echo "thc"
+  elif command -v thoughtcabinet > /dev/null 2>&1; then
+    echo "thoughtcabinet"
+  else
+    echo ""
+  fi
+}
+
+check_status() {
+  [ -L thoughts/shared ] && THOUGHTS=true || THOUGHTS=false
+  [ -f AGENTS.md ] && MEMORY=true || MEMORY=false
+
+  echo "thoughts: $([ "$THOUGHTS" = true ] && echo initialized || echo 'not initialized')"
+  echo "memory: $([ "$MEMORY" = true ] && echo exists || echo 'not found')"
+}
+
+verify() {
+  echo "=== Onboarding Status ==="
+  local issues=0
+
+  if [ -L thoughts/shared ] && [ -L thoughts/global ]; then
+    echo "[OK] thoughts/ initialized"
+  else
+    echo "[FAIL] thoughts/ not initialized"
+    issues=$((issues + 1))
+  fi
+
+  [ -f AGENTS.md ] && echo "[OK] AGENTS.md created" || echo "[SKIP] AGENTS.md not created"
+
+  if [ -L CLAUDE.md ]; then echo "[OK] CLAUDE.md symlink"
+  elif [ -f CLAUDE.md ]; then echo "[OK] CLAUDE.md exists"
+  else echo "[SKIP] CLAUDE.md not created"; fi
+
+  local git_dir
+  git_dir=$(git rev-parse --git-common-dir 2>/dev/null)
+  [ -f "$git_dir/hooks/pre-commit" ] && echo "[OK] pre-commit hook" || echo "[WARN] no pre-commit hook"
+  [ -f "$git_dir/hooks/post-commit" ] && echo "[OK] post-commit hook" || echo "[WARN] no post-commit hook"
+
+  echo "=== Done ==="
+  return "$issues"
+}
+
+# --- Main ---
+
+# Pre-flight: git repo
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+  echo "FATAL: Not a git repository. Run 'git init' first."
+  exit 1
+fi
+
+# Pre-flight: thc availability
+THC_CMD=$(resolve_thc)
+if [ -z "$THC_CMD" ]; then
+  echo "FATAL: thc is not installed or not in PATH."
+  exit 1
+fi
+
+# Verify-only mode
+if [ "$VERIFY_ONLY" = true ]; then
+  verify
+  exit $?
+fi
+
+# Status check
+check_status
+
+# Initialize thoughts
+if [ "$THOUGHTS" = true ] && [ "$FORCE" = false ]; then
+  echo "SKIP: thoughts/ already initialized."
+  if [ "$MEMORY" = true ]; then
+    exit 3
+  else
+    exit 2
+  fi
+fi
+
+INIT_FLAGS="--directory $(basename "$(pwd)")"
+[ "$FORCE" = true ] && INIT_FLAGS="$INIT_FLAGS --force"
+$THC_CMD init $INIT_FLAGS
+
+# Verify init succeeded
+if [ -L thoughts/shared ] && [ -L thoughts/global ]; then
+  echo "OK: thoughts/ initialized."
+else
+  echo "FATAL: thoughts/ init failed — symlinks not created."
+  exit 1
+fi
+
+# Return based on memory status
+[ -f AGENTS.md ] && exit 3 || exit 2

package/src/agent-assets/skills/test-skill-e2e/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: test-skill-e2e
+description: End-to-end smoke test a ThoughtCabinet skill by deploying it to a target agent, running the agent non-interactively against a test project, capturing output, and evaluating results. Use when you want to verify a skill works correctly before shipping.
+---
+
+# End-to-End Skill Testing
+
+Smoke test a ThoughtCabinet skill by deploying it to a target agent CLI, invoking the agent non-interactively against a real project, capturing all output, and evaluating results.
+
+## Workflow Overview
+
+1. **Gather inputs** - Determine which skill, which agent, and which project to test against
+2. **Deploy skills** - Copy all bundled skills into the agent's project-level skill directory
+3. **Prepare test environment** - Clean up artifacts from prior runs
+4. **Execute agent** - Run the agent CLI non-interactively with the skill prompt
+5. **Evaluate results** - Read captured output and generate a pass/fail summary
+
+## Step 1: Gather Inputs
+
+Determine three things from the user or surrounding context:
+
+| Input | Example |
+|-------|---------|
+| Skill to test | `onboard`, or path like `src/agent-assets/skills/onboard/SKILL.md` |
+| Agent CLI | `codex`, `claude` |
+
+Once identified, read the target skill's SKILL.md to understand:
+- What the skill does (description, workflow steps)
+- What artifacts it creates (files, directories, symlinks)
+- What verification checks it performs (look for `[OK]`/`[FAIL]` markers)
+
+```bash
+# Example: read the skill under test
+cat src/agent-assets/skills/<skill-name>/SKILL.md
+```
+
+This understanding is essential for Steps 3 and 5.
+
+## Step 2: Deploy Skills
+
+Copy **all** bundled skills from the ThoughtCabinet source tree into the agent's project-level skill directory. Include all skills (not just the one under test) because skills may reference each other.
+
+Agent skill directory conventions:
+
+| Agent | Directory |
+|-------|-----------|
+| Codex | `<project>/.codex/skills/<skill-name>/` |
+| Claude Code | `<project>/.claude/skills/<skill-name>/` |
+| Cline | `<project>/.cline/skills/<skill-name>/` |
+
+```bash
+# Example: deploy all skills for Codex
+THC_SRC="/path/to/thought-cabinet/src/agent-assets/skills"
+PROJECT="/path/to/test-project"
+AGENT_SKILLS="$PROJECT/.codex/skills"
+
+for skill_dir in "$THC_SRC"/*/; do
+  skill_name=$(basename "$skill_dir")
+  mkdir -p "$AGENT_SKILLS/$skill_name"
+  cp "$skill_dir"SKILL.md "$AGENT_SKILLS/$skill_name/SKILL.md"
+done
+```
+
+Verify deployment:
+
+```bash
+ls -la "$AGENT_SKILLS"
+```
+
+## Step 3: Prepare Test Environment
+
+Clean up artifacts from prior runs so the test starts from a known state. Use the skill's SKILL.md (read in Step 1) to determine what to remove.
+
+Common cleanup actions by skill type:
+
+```bash
+cd "$PROJECT"
+
+# For onboard skill
+thc destroy --force 2>/dev/null || true
+rm -f AGENTS.md
+rm -f CLAUDE.md
+rm -rf docs/architectural-patterns.md
+
+# For init-agent-memory skill
+rm -f AGENTS.md
+rm -f CLAUDE.md
+rm -rf docs/architectural-patterns.md
+
+# Generic: remove thoughts artifacts
+rm -rf thoughts/
+```
+
+Verify the starting state is clean:
+
+```bash
+echo "=== Pre-test state ==="
+[ ! -d thoughts ] && echo "[OK] no thoughts/" || echo "[WARN] thoughts/ still exists"
+[ ! -f AGENTS.md ] && echo "[OK] no AGENTS.md" || echo "[WARN] AGENTS.md still exists"
+[ ! -f CLAUDE.md ] && echo "[OK] no CLAUDE.md" || echo "[WARN] CLAUDE.md still exists"
+```
+
+All checks should show `[OK]` before proceeding.
+
+## Step 4: Execute Agent
+
+Run the agent CLI non-interactively with full permissions, instructing it to invoke the skill. Stream all output to a timestamped log file via `tee`.
+
+### Build the prompt
+
+The prompt should instruct the agent to invoke the target skill:
+
+```
+Invoke the <skill-name> skill to <summary of what the skill does>.
+```
+
+### Agent invocation patterns
+
+| Agent | Command |
+|-------|---------|
+| Codex | `codex exec --dangerously-bypass-approvals-and-sandbox "<prompt>"` |
+| Claude Code | `claude -p "<prompt>" --dangerously-skip-permissions` |
+
+### Run with output capture
+
+```bash
+LOGFILE="test-$(date +%Y%m%d-%H%M%S)-<skill-name>.log"
+
+# Codex example
+codex exec --dangerously-bypass-approvals-and-sandbox \
+  "Invoke the onboard skill to initialize ThoughtCabinet and bootstrap agent memory." \
+  2>&1 | tee "$LOGFILE"
+
+# Claude Code example
+claude -p \
+  "Invoke the onboard skill to initialize ThoughtCabinet and bootstrap agent memory." \
+  --dangerously-skip-permissions \
+  2>&1 | tee "$LOGFILE"
+```
+
+Wait for the agent to complete. Do not interrupt it.
+
+## Step 5: Evaluate Results
+
+Read the log file end-to-end and assess:
+
+```bash
+cat "$LOGFILE"
+```
+
+### Evaluation checklist
+
+| Check | What to look for |
+|-------|-----------------|
+| Skill discovery | Agent found and read the SKILL.md |
+| Step execution | Each numbered workflow step was attempted |
+| No errors | No stack traces, permission blocks, or sandbox violations |
+| Artifact creation | Expected files/directories exist on disk |
+| Verification markers | `[OK]` markers in output; no `[FAIL]` markers |
+
+### Verify artifacts on disk
+
+```bash
+echo "=== Post-test verification ==="
+# Adapt these checks to the skill under test
+
+# For onboard skill
+[ -L thoughts/shared ] && echo "[OK] thoughts/shared symlink" || echo "[FAIL] thoughts/shared missing"
+[ -L thoughts/global ] && echo "[OK] thoughts/global symlink" || echo "[FAIL] thoughts/global missing"
+[ -f AGENTS.md ] && echo "[OK] AGENTS.md exists" || echo "[FAIL] AGENTS.md missing"
+[ -e CLAUDE.md ] && echo "[OK] CLAUDE.md exists" || echo "[FAIL] CLAUDE.md missing"
+```
+
+### Generate summary
+
+Produce a clear pass/fail report:
+
+```
+=== Test Results: <skill-name> ===
+Agent: <agent-name>
+Project: <project-path>
+Log: <logfile-path>
+
+Step 1 (Pre-flight):     PASS
+Step 2 (Init thoughts):  PASS
+Step 3 (Bootstrap memory): PASS
+Step 4 (Verify):         PASS
+
+Overall: PASS (4/4 steps)
+Notes: <any observations>
+```
+
+If any step failed, include the relevant log excerpt and suggested remediation.
+
+## Guidelines
+
+**Idempotent cleanup**: The prepare step (Step 3) should make the test fully repeatable. Running the test twice in a row should produce the same result.
+
+**Log everything**: Always capture output to a file. Agent output in terminals can scroll away or be lost.
+
+**Read the skill first**: Understanding expected outcomes (Step 1) is essential for meaningful evaluation (Step 5). Do not skip this.
+
+**One skill per run**: Test skills individually for clear signal. If you need to test multiple skills, run this workflow once per skill.
+
+**Adapt checks to the skill**: The cleanup and verification examples above are for the `onboard` skill. For other skills, derive the appropriate checks from the skill's SKILL.md.