thought-cabinet 0.1.13 → 0.2.1

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-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/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.

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.