thought-cabinet 0.0.2

package/src/agent-assets/commands/iterate_plan.md

@@ -0,0 +1,254 @@
+---
+description: Iterate on existing implementation plans with thorough research and updates
+model: opus
+---
+
+# Iterate Implementation Plan
+
+You are tasked with updating existing implementation plans based on user feedback. You should be skeptical, thorough, and ensure changes are grounded in actual codebase reality.
+
+## Initial Response
+
+When this command is invoked:
+
+1. **Parse the input to identify**:
+   - Plan file path (e.g., `thoughts/shared/plans/2025-10-16-feature.md`)
+   - Requested changes/feedback
+
+2. **Handle different input scenarios**:
+
+   **If NO plan file provided**:
+
+   ```
+   I'll help you iterate on an existing implementation plan.
+
+   Which plan would you like to update? Please provide the path to the plan file (e.g., `thoughts/shared/plans/2025-10-16-feature.md`).
+
+   Tip: You can list recent plans with `ls -lt thoughts/shared/plans/ | head`
+   ```
+
+   Wait for user input, then re-check for feedback.
+
+   **If plan file provided but NO feedback**:
+
+   ```
+   I've found the plan at [path]. What changes would you like to make?
+
+   For example:
+   - "Add a phase for migration handling"
+   - "Update the success criteria to include performance tests"
+   - "Adjust the scope to exclude feature X"
+   - "Split Phase 2 into two separate phases"
+   ```
+
+   Wait for user input.
+
+   **If BOTH plan file AND feedback provided**:
+   - Proceed immediately to Step 1
+   - No preliminary questions needed
+
+## Process Steps
+
+### Step 1: Read and Understand Current Plan
+
+1. **Read the existing plan file COMPLETELY**:
+   - Use the Read tool WITHOUT limit/offset parameters
+   - Understand the current structure, phases, and scope
+   - Note the success criteria and implementation approach
+
+2. **Understand the requested changes**:
+   - Parse what the user wants to add/modify/remove
+   - Identify if changes require codebase research
+   - Determine scope of the update
+
+### Step 2: Research If Needed
+
+**Only spawn research tasks if the changes require new technical understanding.**
+
+If the user's feedback requires understanding new code patterns or validating assumptions:
+
+1. **Create a research todo list** using TodoWrite
+
+2. **Spawn parallel sub-tasks for research**:
+   Use the right agent for each type of research:
+
+   **For code investigation:**
+   - **codebase-locator** - To find relevant files
+   - **codebase-analyzer** - To understand implementation details
+   - **codebase-pattern-finder** - To find similar patterns
+
+   **For historical context:**
+   - **thoughts-locator** - To find related research or decisions
+   - **thoughts-analyzer** - To extract insights from documents
+
+   **Be EXTREMELY specific about directories**:
+   - Include full path context in prompts
+
+3. **Read any new files identified by research**:
+   - Read them FULLY into the main context
+   - Cross-reference with the plan requirements
+
+4. **Wait for ALL sub-tasks to complete** before proceeding
+
+### Step 3: Present Understanding and Approach
+
+Before making changes, confirm your understanding:
+
+```
+Based on your feedback, I understand you want to:
+- [Change 1 with specific detail]
+- [Change 2 with specific detail]
+
+My research found:
+- [Relevant code pattern or constraint]
+- [Important discovery that affects the change]
+
+I plan to update the plan by:
+1. [Specific modification to make]
+2. [Another modification]
+
+Does this align with your intent?
+```
+
+Get user confirmation before proceeding.
+
+### Step 4: Update the Plan
+
+1. **Make focused, precise edits** to the existing plan:
+   - Use the Edit tool for surgical changes
+   - Maintain the existing structure unless explicitly changing it
+   - Keep all file:line references accurate
+   - Update success criteria if needed
+
+2. **Ensure consistency**:
+   - If adding a new phase, ensure it follows the existing pattern
+   - If modifying scope, update "What We're NOT Doing" section
+   - If changing approach, update "Implementation Approach" section
+   - Maintain the distinction between automated vs manual success criteria
+
+3. **Preserve quality standards**:
+   - Include specific file paths and line numbers for new content
+   - Write measurable success criteria
+   - Use `make` commands for automated verification
+   - Keep language clear and actionable
+
+### Step 5: Sync and Review
+
+1. **Sync the updated plan**:
+   - Run `thoughtcabinet sync`
+   - This ensures changes are properly indexed
+
+2. **Present the changes made**:
+
+   ```
+   I've updated the plan at `thoughts/shared/plans/[filename].md`
+
+   Changes made:
+   - [Specific change 1]
+   - [Specific change 2]
+
+   The updated plan now:
+   - [Key improvement]
+   - [Another improvement]
+
+   Would you like any further adjustments?
+   ```
+
+3. **Be ready to iterate further** based on feedback
+
+## Important Guidelines
+
+1. **Be Skeptical**:
+   - Don't blindly accept change requests that seem problematic
+   - Question vague feedback - ask for clarification
+   - Verify technical feasibility with code research
+   - Point out potential conflicts with existing plan phases
+
+2. **Be Surgical**:
+   - Make precise edits, not wholesale rewrites
+   - Preserve good content that doesn't need changing
+   - Only research what's necessary for the specific changes
+   - Don't over-engineer the updates
+
+3. **Be Thorough**:
+   - Read the entire existing plan before making changes
+   - Research code patterns if changes require new technical understanding
+   - Ensure updated sections maintain quality standards
+   - Verify success criteria are still measurable
+
+4. **Be Interactive**:
+   - Confirm understanding before making changes
+   - Show what you plan to change before doing it
+   - Allow course corrections
+   - Don't disappear into research without communicating
+
+5. **Track Progress**:
+   - Use TodoWrite to track update tasks if complex
+   - Update todos as you complete research
+   - Mark tasks complete when done
+
+6. **No Open Questions**:
+   - If the requested change raises questions, ASK
+   - Research or get clarification immediately
+   - Do NOT update the plan with unresolved questions
+   - Every change must be complete and actionable
+
+## Success Criteria Guidelines
+
+When updating success criteria, always maintain the two-category structure:
+
+1. **Automated Verification** (can be run by execution agents):
+   - Commands that can be run: `make test`, `npm run lint`, etc.
+   - Specific files that should exist
+   - Code compilation/type checking
+
+2. **Manual Verification** (requires human testing):
+   - UI/UX functionality
+   - Performance under real conditions
+   - Edge cases that are hard to automate
+   - User acceptance criteria
+
+## Sub-task Spawning Best Practices
+
+When spawning research sub-tasks:
+
+1. **Only spawn if truly needed** - don't research for simple changes
+2. **Spawn multiple tasks in parallel** for efficiency
+3. **Each task should be focused** on a specific area
+4. **Provide detailed instructions** including:
+   - Exactly what to search for
+   - Which directories to focus on
+   - What information to extract
+   - Expected output format
+5. **Request specific file:line references** in responses
+6. **Wait for all tasks to complete** before synthesizing
+7. **Verify sub-task results** - if something seems off, spawn follow-up tasks
+
+## Example Interaction Flows
+
+**Scenario 1: User provides everything upfront**
+
+```
+User: /iterate_plan thoughts/shared/plans/2025-10-16-feature.md - add phase for error handling
+Assistant: [Reads plan, researches error handling patterns, updates plan]
+```
+
+**Scenario 2: User provides just plan file**
+
+```
+User: /iterate_plan thoughts/shared/plans/2025-10-16-feature.md
+Assistant: I've found the plan. What changes would you like to make?
+User: Split Phase 2 into two phases - one for backend, one for frontend
+Assistant: [Proceeds with update]
+```
+
+**Scenario 3: User provides no arguments**
+
+```
+User: /iterate_plan
+Assistant: Which plan would you like to update? Please provide the path...
+User: thoughts/shared/plans/2025-10-16-feature.md
+Assistant: I've found the plan. What changes would you like to make?
+User: Add more specific success criteria
+Assistant: [Proceeds with update]
+```

package/src/agent-assets/commands/research_codebase.md

@@ -0,0 +1,107 @@
+---
+description: Document codebase as-is with thoughts directory for historical context
+model: opus
+---
+
+# Research Codebase
+
+You are tasked with conducting comprehensive research across the codebase to answer user questions by spawning parallel sub-agents and synthesizing their findings.
+
+## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY
+
+- DO NOT suggest improvements or changes unless the user explicitly asks for them
+- DO NOT perform root cause analysis unless the user explicitly asks for them
+- DO NOT propose future enhancements unless the user explicitly asks for them
+- DO NOT critique the implementation or identify problems
+- DO NOT recommend refactoring, optimization, or architectural changes
+- ONLY describe what exists, where it exists, how it works, and how components interact
+- You are creating a technical map/documentation of the existing system
+
+## Initial Setup:
+
+When this command is invoked, respond with:
+
+```
+I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.
+```
+
+Then wait for the user's research query.
+
+## Steps to follow after receiving the research query:
+
+1. **Read any directly mentioned files first:**
+   - If the user mentions specific files (codes, docs, JSON), read them FULLY first
+   - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
+   - **CRITICAL**: Read these files yourself in the main context before spawning any sub-tasks
+   - This ensures you have full context before decomposing the research
+
+2. **Analyze and decompose the research question:**
+   - Break down the user's query into composable research areas
+   - Take time to ultrathink about the underlying patterns, connections, and architectural implications the user might be seeking
+   - Identify specific components, patterns, or concepts to investigate
+   - Create a research plan using TodoWrite to track all subtasks
+   - Consider which directories, files, or architectural patterns are relevant
+
+3. **Spawn parallel sub-agent tasks for comprehensive research:**
+   - Create multiple Task agents to research different aspects concurrently
+   - We now have specialized agents that know how to do specific research tasks:
+
+   **For codebase research:**
+   - Use the **codebase-locator** agent to find WHERE files and components live
+   - Use the **codebase-analyzer** agent to understand HOW specific code works (without critiquing it)
+   - Use the **codebase-pattern-finder** agent to find examples of existing patterns (without evaluating them)
+
+   **IMPORTANT**: All agents are documentarians, not critics. They will describe what exists without suggesting improvements or identifying issues.
+
+   **For thoughts directory:**
+   - Use the **thoughts-locator** agent to discover what documents exist about the topic
+   - Use the **thoughts-analyzer** agent to extract key insights from specific documents (only the most relevant ones)
+
+   **For web research (only if user explicitly asks):**
+   - Use the **web-search-researcher** agent for external documentation and resources
+   - IF you use web-research agents, instruct them to return LINKS with their findings, and please INCLUDE those links in your final report
+
+   The key is to use these agents intelligently:
+   - Start with locator agents to find what exists
+   - Then use analyzer agents on the most promising findings to document how they work
+   - Run multiple agents in parallel when they're searching for different things
+   - Each agent knows its job - just tell it what you're looking for
+   - Don't write detailed prompts about HOW to search - the agents already know
+   - Remind agents they are documenting, not evaluating or improving
+
+4. **Wait for all sub-agents to complete and synthesize findings:**
+   - IMPORTANT: Wait for ALL sub-agent tasks to complete before proceeding
+   - Compile all sub-agent results (both codebase and thoughts findings)
+   - Prioritize live codebase findings as primary source of truth
+   - Use thoughts/ findings as supplementary historical context
+   - Connect findings across different components
+   - Include specific file paths and line numbers for reference
+   - Verify all thoughts/ paths are correct (e.g., thoughts/allison/ not thoughts/shared/ for personal files)
+   - Highlight patterns, connections, and architectural decisions
+   - Answer the user's specific questions with concrete evidence
+
+5. **Generate research document:**
+   - Use the **generating-research-document** skill to generate a research document or handle follow-up questions
+
+## Important notes:
+
+- Always use parallel Task agents to maximize efficiency and minimize context usage
+- Always run fresh codebase research - never rely solely on existing research documents
+- The thoughts/ directory provides historical context to supplement live findings
+- Focus on finding concrete file paths and line numbers for developer reference
+- Research documents should be self-contained with all necessary context
+- Each sub-agent prompt should be specific and focused on read-only documentation operations
+- Document cross-component connections and how systems interact
+- Include temporal context (when the research was conducted)
+- Link to GitHub when possible for permanent references
+- Keep the main agent focused on synthesis, not deep file reading
+- Have sub-agents document examples and usage patterns as they exist
+- Explore all of thoughts/ directory, not just research subdirectory
+- **CRITICAL**: You and all sub-agents are documentarians, not evaluators
+- **NO RECOMMENDATIONS**: Only describe the current state of the codebase
+- **File reading**: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks
+- **Critical ordering**: Follow the numbered steps exactly
+  - ALWAYS read mentioned files first before spawning sub-tasks (step 1)
+  - ALWAYS wait for all sub-agents to complete before synthesizing (step 4)
+  - ALWAYS gather metadata before writing the document (step 5 before step 6)
+  - NEVER write the research document with placeholder values

package/src/agent-assets/commands/validate_plan.md

@@ -0,0 +1,178 @@
+---
+description: Validate implementation against plan, verify success criteria, identify issues
+---
+
+# Validate Plan
+
+You are tasked with validating that an implementation plan was correctly executed, verifying all success criteria and identifying any deviations or issues.
+
+## Initial Setup
+
+When invoked:
+
+1. **Determine context** - Are you in an existing conversation or starting fresh?
+   - If existing: Review what was implemented in this session
+   - If fresh: Need to discover what was done through git and codebase analysis
+
+2. **Locate the plan**:
+   - If plan path provided, use it
+   - Otherwise, search recent commits for plan references or ask user
+
+3. **Gather implementation evidence**:
+
+   ```bash
+   # Check recent commits
+   git log --oneline -n 20
+   git diff HEAD~N..HEAD  # Where N covers implementation commits
+
+   # Run comprehensive checks
+   cd $(git rev-parse --show-toplevel) && make check test
+   ```
+
+## Validation Process
+
+### Step 1: Context Discovery
+
+If starting fresh or need more context:
+
+1. **Read the implementation plan** completely
+2. **Identify what should have changed**:
+   - List all files that should be modified
+   - Note all success criteria (automated and manual)
+   - Identify key functionality to verify
+
+3. **Spawn parallel research tasks** to discover implementation:
+
+   ```
+   Task 1 - Verify database changes:
+   Research if migration [N] was added and schema changes match plan.
+   Check: migration files, schema version, table structure
+   Return: What was implemented vs what plan specified
+
+   Task 2 - Verify code changes:
+   Find all modified files related to [feature].
+   Compare actual changes to plan specifications.
+   Return: File-by-file comparison of planned vs actual
+
+   Task 3 - Verify test coverage:
+   Check if tests were added/modified as specified.
+   Run test commands and capture results.
+   Return: Test status and any missing coverage
+   ```
+
+### Step 2: Systematic Validation
+
+For each phase in the plan:
+
+1. **Check completion status**:
+   - Look for checkmarks in the plan (- [x])
+   - Verify the actual code matches claimed completion
+
+2. **Run automated verification**:
+   - Execute each command from "Automated Verification"
+   - Document pass/fail status
+   - If failures, investigate root cause
+
+3. **Assess manual criteria**:
+   - List what needs manual testing
+   - Provide clear steps for user verification
+
+4. **Think deeply about edge cases**:
+   - Were error conditions handled?
+   - Are there missing validations?
+   - Could the implementation break existing functionality?
+
+### Step 3: Generate Validation Report
+
+Create comprehensive validation summary:
+
+```markdown
+## Validation Report: [Plan Name]
+
+### Implementation Status
+
+✓ Phase 1: [Name] - Fully implemented
+✓ Phase 2: [Name] - Fully implemented
+⚠️ Phase 3: [Name] - Partially implemented (see issues)
+
+### Automated Verification Results
+
+✓ Build passes: `make build`
+✓ Tests pass: `make test`
+✗ Linting issues: `make lint` (3 warnings)
+
+### Code Review Findings
+
+#### Matches Plan:
+
+- Database migration correctly adds [table]
+- API endpoints implement specified methods
+- Error handling follows plan
+
+#### Deviations from Plan:
+
+- Used different variable names in [file:line]
+- Added extra validation in [file:line] (improvement)
+
+#### Potential Issues:
+
+- Missing index on foreign key could impact performance
+- No rollback handling in migration
+
+### Manual Testing Required:
+
+1. UI functionality:
+   - [ ] Verify [feature] appears correctly
+   - [ ] Test error states with invalid input
+
+2. Integration:
+   - [ ] Confirm works with existing [component]
+   - [ ] Check performance with large datasets
+
+### Recommendations:
+
+- Address linting warnings before merge
+- Consider adding integration test for [scenario]
+- Document new API endpoints
+```
+
+## Working with Existing Context
+
+If you were part of the implementation:
+
+- Review the conversation history
+- Check your todo list for what was completed
+- Focus validation on work done in this session
+- Be honest about any shortcuts or incomplete items
+
+## Important Guidelines
+
+1. **Be thorough but practical** - Focus on what matters
+2. **Run all automated checks** - Don't skip verification commands
+3. **Document everything** - Both successes and issues
+4. **Think critically** - Question if the implementation truly solves the problem
+5. **Consider maintenance** - Will this be maintainable long-term?
+
+## Validation Checklist
+
+Always verify:
+
+- [ ] All phases marked complete are actually done
+- [ ] Automated tests pass
+- [ ] Code follows existing patterns
+- [ ] No regressions introduced
+- [ ] Error handling is robust
+- [ ] Documentation updated if needed
+- [ ] Manual test steps are clear
+
+## Relationship to Other Commands
+
+Recommended workflow:
+
+1. `/implement_plan` - Execute the implementation
+2. `/commit` - Create atomic commits for changes
+3. `/validate_plan` - Verify implementation correctness
+
+The validation works best after commits are made, as it can analyze the git history to understand what was implemented.
+
+Remember: Good validation catches issues before they reach production. Be constructive but thorough in identifying gaps or improvements.

package/src/agent-assets/settings.template.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": []
+  },
+  "enableAllProjectMcpServers": false,
+  "env": {}
+}

package/src/agent-assets/skills/generating-research-document/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: generating-research-document
+description: Generate structured research documentation. Use when (1) creating research documents after codebase exploration, (2) documenting findings from code analysis, (3) writing technical research reports to thoughts/shared/research/. Triggers on requests like "how does the authentication flow work?"
+---
+
+# Generate Research Document
+
+Generate research documentation for the thoughts/ directory with proper metadata and structure.
+
+## Workflow
+
+1. **Gather metadata**
+
+   ```bash
+   thoughtcabinet metadata
+   ```
+
+   Captures: researcher name, git commit, branch, repository, timestamp
+
+2. **Determine filename**
+   - Path: `thoughts/shared/research/YYYY-MM-DD-description.md`
+   - Description: kebab-case summary of topic
+   - Example: `2025-01-08-authentication-flow.md`
+
+3. **Generate document**
+   - Use template from [document_template.md](document_template.md)
+   - Fill metadata from step 1
+   - Structure findings into appropriate sections
+   - Include file:line references for all code mentions
+
+4. **Sync**
+   ```bash
+   thoughtcabinet sync
+   ```
+
+## Key Rules
+
+- **Document what IS, not what SHOULD BE** - no recommendations or critiques
+- **Path handling**: Remove only "searchable/" from thoughts paths (e.g., `thoughts/searchable/allison/` → `thoughts/allison/`)
+- **Frontmatter**: Always include, use snake_case for multi-word fields
+- **Code references**: Format as `path/to/file.ext:line` with descriptions

package/src/agent-assets/skills/generating-research-document/document_template.md

@@ -0,0 +1,97 @@
+# Research Document Template
+
+## YAML Frontmatter
+
+```yaml
+---
+date: [ISO 8601 datetime with timezone, e.g., 2025-01-08T14:30:00+08:00]
+researcher: [From `thoughtcabinet metadata` output]
+git_commit: [Current commit hash from metadata]
+branch: [Current branch name from metadata]
+repository: [Repository name from metadata]
+topic: "[User's Research Question/Topic]"
+tags: [research, codebase, relevant-component-names]
+status: complete
+last_updated: [YYYY-MM-DD format]
+last_updated_by: [Researcher name]
+---
+```
+
+## Document Structure
+
+```markdown
+# Research: [User's Question/Topic]
+
+**Date**: [datetime with timezone]
+**Researcher**: [name]
+**Git Commit**: [hash]
+**Branch**: [branch]
+**Repository**: [repo]
+
+## Research Question
+
+[Original user query verbatim]
+
+## Summary
+
+[High-level documentation answering the user's question by describing what exists]
+
+## Detailed Findings
+
+### [Component/Area 1]
+
+- Description of what exists ([file.ext:line](link))
+- How it connects to other components
+- Current implementation details (without evaluation)
+
+### [Component/Area 2]
+
+...
+
+## Code References
+
+- `path/to/file.py:123` - Description of what's there
+- `another/file.ts:45-67` - Description of the code block
+
+## Architecture Documentation
+
+[Current patterns, conventions, and design implementations found]
+
+## Historical Context (from thoughts/)
+
+[Relevant insights from thoughts/ directory with references]
+
+- `thoughts/shared/something.md` - Historical decision about X
+- `thoughts/local/notes.md` - Past exploration of Y
+  Note: Paths exclude "searchable/" even if found there
+
+## Related Research
+
+[Links to other research documents in thoughts/shared/research/]
+
+## Open Questions
+
+[Areas that need further investigation]
+```
+
+## Follow-up Research Section
+
+When adding follow-up research, append:
+
+```markdown
+## Follow-up Research [timestamp]
+
+### Follow-up Question
+
+[The follow-up question]
+
+### Additional Findings
+
+[New findings from additional investigation]
+```
+
+Also update frontmatter:
+
+- `last_updated`: Current date
+- `last_updated_by`: Researcher name
+- Add `last_updated_note: "Added follow-up research for [brief description]"`