anima-core 0.3.0 → 1.0.0

data/workflows/create_note.md

@@ -0,0 +1,82 @@
+---
+name: create_note
+description: "Capture findings or context as a persistent note in the thoughts system."
+---
+
+# Create Note
+
+You are tasked with capturing content as a persistent note in the thoughts system. This could be findings from a research specialist, insights from the current session, or any content worth preserving for future reference.
+
+## Process
+
+### 1. Gather Metadata
+
+Run `spec-metadata` (in the PATH) to get date, time, git commit, branch, and repository name.
+
+### 2. Filepath & Naming
+
+Create your file under `./thoughts/shared/notes/YYYY-MM-DD/description.md`, where:
+- YYYY-MM-DD is today's date
+- description is a brief kebab-case description of the content
+
+Examples:
+- `2026-02-23/rails-8-turbo-stream-patterns.md`
+- `2026-02-23/sidekiq-retry-best-practices.md`
+- `2026-02-23/authentication-library-comparison.md`
+
+### 3. Note Writing
+
+Using the above conventions, write your document with the following YAML frontmatter pattern. Use the metadata gathered in step 1:
+
+```markdown
+---
+date: [Current date and time with timezone in ISO format]
+author: [Author name from spec-metadata]
+git_commit: [Current commit hash]
+branch: [Current branch name]
+repository: [Repository name]
+topic: "[Brief topic description]"
+tags: [note, relevant-keywords]
+status: complete
+last_updated: [Current date in YYYY-MM-DD format]
+last_updated_by: [Author name]
+---
+
+# [Topic]
+
+## Context
+
+[What prompted this note - the question, task, or goal]
+
+## Content
+
+[The actual content - preserved exactly as provided without summarization or transformation]
+
+## Sources
+
+[Links, file paths, or references - if applicable, omit section if none]
+
+## Related
+
+[Links to related notes, research, or plans in thoughts/ - if applicable, omit section if none]
+```
+
+### 4. Sync and Present
+
+Run `thoughts-sync` to save the document.
+
+Once complete, respond with:
+
+```
+Note captured at: ./thoughts/shared/notes/YYYY-MM-DD/description.md
+
+You can reference this in future sessions or as input to other workflows.
+```
+
+## Additional Notes & Instructions
+
+- **Preserve content exactly**: The value of this note is capturing content losslessly. Do not summarize, synthesize, or transform the content unless explicitly asked.
+- **Include all links**: If content came from web research, documentation lookups, or file analysis, preserve all URLs and file:line references.
+- **Topic from context**: Derive the topic from the content being captured. Only ask the user if genuinely ambiguous.
+- **Sections are flexible**: The Content section is required. Sources and Related sections should be included when applicable, omitted when not.
+- **Follow-up notes**: If adding to an existing topic, consider updating the existing note rather than creating a duplicate. Update `last_updated` and `last_updated_by` fields.

data/workflows/create_plan.md

@@ -0,0 +1,457 @@
+---
+name: create_plan
+description: "Create detailed implementation plans through interactive research and iteration."
+---
+
+# Implementation Plan
+
+You are tasked with creating detailed implementation plans through an interactive, iterative process. You should be skeptical, thorough, and work collaboratively with the user to produce high-quality technical specifications.
+
+## Initial Response
+
+When this command is invoked:
+
+1. **Check if parameters were provided**:
+   - If a file path or ticket reference was provided as a parameter, skip the default message
+   - Immediately read any provided files FULLY
+   - Begin the research process
+
+2. **If no parameters provided**, respond with:
+```
+I'll help you create a detailed implementation plan. Let me start by understanding what we're building.
+
+Please provide:
+1. The task/ticket description (or reference to a ticket file)
+2. Any relevant context, constraints, or specific requirements
+3. Links to related research or previous implementations
+
+I'll analyze this information and work with you to create a comprehensive plan.
+
+Provide a GitHub issue reference or a description of what needs to be planned.
+```
+
+Then wait for the user's input.
+
+## Process Steps
+
+### Step 1: Context Gathering & Initial Analysis
+
+1. **Read all mentioned files (if any) immediately and FULLY**:
+   - GitHub issue details (via `gh issue view`)
+   - Research documents
+   - Related implementation plans
+   - Any JSON/data files mentioned
+   - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
+   - **CRITICAL**: If files mentioned, DO NOT spawn sub-tasks before reading these files yourself in the main context
+   - **NEVER** read files partially - if a file is mentioned, read it completely
+
+2. **Gather Historical Context**:
+   Spawn the `thoughts-analyzer` specialist with ticket reference, title, description, and acceptance criteria.
+
+   DO NOT proceed to step 3 until this specialist returns. Its output is required input for step 3.
+
+3. **Spawn codebase research tasks**:
+   After step 2 completes, spawn research specialists in parallel, passing ticket info and historical context output from step 2:
+
+   - Use the **codebase-analyzer** specialist to find and understand how the current implementation works
+   - If a GitHub issue is mentioned, read full details via `gh issue view`
+
+   These agents will:
+   - Find relevant source files, configs, and tests
+   - Identify the specific directories to focus on (e.g., if WUI is mentioned, they'll focus on humanlayer-wui/)
+   - Trace data flow and key functions
+   - Return detailed explanations with file:line references
+
+4. **Read all files identified by research tasks**:
+   - After research tasks complete, read ALL files they identified as relevant
+   - Read them FULLY into the main context
+   - This ensures you have complete understanding before proceeding
+
+5. **Analyze and verify understanding**:
+   - Cross-reference the ticket requirements with actual code
+   - Identify any discrepancies or misunderstandings
+   - Note assumptions that need verification
+   - Determine true scope based on codebase reality
+
+6. **Present informed understanding and focused questions**:
+   ```
+   Based on the ticket and my research of the codebase, I understand we need to [accurate summary].
+
+   I've found that:
+   - [Current implementation detail with file:line reference]
+   - [Relevant pattern or constraint discovered]
+   - [Potential complexity or edge case identified]
+
+   Questions that my research couldn't answer:
+   - [Specific technical question that requires human judgment]
+   - [Business logic clarification]
+   - [Design preference that affects implementation]
+   ```
+
+   Only ask questions that you genuinely cannot answer through code investigation.
+
+### Step 2: Research & Discovery
+
+After getting initial clarifications:
+
+1. **If the user corrects any misunderstanding**:
+   - DO NOT just accept the correction
+   - Spawn new research tasks to verify the correct information
+   - Read the specific files/directories they mention
+   - Only proceed once you've verified the facts yourself
+
+2. **Create a research todo list** to track exploration tasks
+
+3. **Spawn parallel sub-tasks for comprehensive research**:
+   - Create multiple subagents to research different aspects concurrently
+   - Use the right agent for each type of research:
+
+   **For codebase research:**
+   - **codebase-analyzer** — find and understand implementation details (e.g., "analyze how [system] works")
+   - **codebase-pattern-finder** — find similar features we can model after
+
+   **For related issues:**
+   - Search GitHub issues via `gh issue list --search "keyword"`
+
+   Each agent knows how to:
+   - Find the right files and code patterns
+   - Identify conventions and patterns to follow
+   - Look for integration points and dependencies
+   - Return specific file:line references
+   - Find tests and examples
+
+4. **Wait for ALL sub-tasks to complete** before proceeding
+
+5. **Present findings and design options**:
+   ```
+   Based on my research, here's what I found:
+
+   **Current State:**
+   - [Key discovery about existing code]
+   - [Pattern or convention to follow]
+
+   **Design Options:**
+   1. [Option A] - [pros/cons]
+   2. [Option B] - [pros/cons]
+
+   **Open Questions:**
+   - [Technical uncertainty]
+   - [Design decision needed]
+
+   Which approach aligns best with your vision?
+   ```
+
+### Step 3: Plan Structure Development
+
+Once aligned on approach:
+
+**Phase = Commit**
+
+Each phase represents one atomic commit - the smallest meaningful change that leaves the codebase working.
+
+**Atomicity test**: If your phase description needs "and", split it. If specs are in another Phase, merge into one.
+
+**For testable code**, follow RGRC: Red → Green → Refactor → Commit. Your phases should mirror your test cases.
+
+1. **Create initial plan outline**:
+   ```
+   Here's my proposed plan structure:
+
+   ## Overview
+   [1-2 sentence summary]
+
+   ## Implementation Phases:
+   1. [Phase name] - [what it accomplishes]
+   2. [Phase name] - [what it accomplishes]
+   3. [Phase name] - [what it accomplishes]
+
+   Does this phasing make sense? Should I adjust the order or granularity?
+   ```
+
+2. **Get feedback on structure** before writing details
+
+### Step 4: Detailed Plan Writing
+
+After structure approval:
+
+1. **Write the plan** to `./thoughts/shared/plans/YYYY-MM-DD/<issue-number>-description.md`
+   - Format: `YYYY-MM-DD/<issue-number>-description.md` where:
+     - YYYY-MM-DD is today's date
+     - issue-number is the GitHub issue number (omit if no issue)
+     - description is a brief kebab-case description
+   - Examples:
+     - With issue: `2026-03-15/170-import-workflows.md`
+     - Without issue: `2026-03-15/improve-error-handling.md`
+2. **Use this template structure**:
+
+````markdown
+# [Feature/Task Name] Implementation Plan
+
+## Overview
+
+[Brief description of what we're implementing and why]
+
+## Current State Analysis
+
+[What exists now, what's missing, key constraints discovered]
+
+## Desired End State
+
+[A Specification of the desired end state after this plan is complete, and how to verify it]
+
+### Key Discoveries:
+- [Important finding with file:line reference]
+- [Pattern to follow]
+- [Constraint to work within]
+
+## What We're NOT Doing
+
+[Explicitly list out-of-scope items to prevent scope creep]
+
+## Implementation Approach
+
+[High-level strategy and reasoning]
+
+## Phase 1: [Descriptive Name]
+
+### Commit
+`<ticket||type>: <imperative summary>`
+
+### Overview
+[What this phase accomplishes]
+
+### Changes Required:
+
+#### 1. [Component/File Group]
+**File**: `path/to/file.ext`
+**Changes**: [Summary of changes]
+
+```[language]
+// Specific code to add/modify
+```
+
+### Success Criteria:
+
+#### Automated Verification:
+- [ ] Migration applies cleanly: `make migrate`
+- [ ] Unit tests pass: `make test-component`
+- [ ] Type checking passes: `npm run typecheck`
+- [ ] Linting passes: `make lint`
+- [ ] Integration tests pass: `make test-integration`
+
+#### Manual Verification:
+- [ ] Feature works as expected when tested via UI
+- [ ] Performance is acceptable under load
+- [ ] Edge case handling verified manually
+- [ ] No regressions in related features
+
+**Implementation Note**: After completing this phase and all automated verification passes, pause here for manual confirmation from the human that the manual testing was successful before proceeding to the next phase.
+
+---
+
+## Phase 2: [Descriptive Name]
+
+[Similar structure with both automated and manual success criteria...]
+
+---
+
+## Testing Strategy
+
+### Unit Tests:
+- [What to test]
+- [Key edge cases]
+
+### Integration Tests:
+- [End-to-end scenarios]
+
+### Manual Testing Steps:
+1. [Specific step to verify feature]
+2. [Another verification step]
+3. [Edge case to test manually]
+
+## Performance Considerations
+
+[Any performance implications or optimizations needed]
+
+## Migration Notes
+
+[If applicable, how to handle existing data/systems]
+
+## References
+
+- Original issue: GitHub issue #NNN
+- Related research: `./thoughts/shared/research/[relevant].md`
+- Similar implementation: `[file:line]`
+````
+
+### Step 5: Sync and Review
+
+1. **Sync the thoughts directory**:
+   - Run `thoughts-sync` to sync the newly created plan
+   - This ensures the plan is properly indexed and available
+
+2. **Present the draft plan location**:
+   ```
+   I've created the initial implementation plan at:
+   `./thoughts/shared/plans/YYYY-MM-DD/<issue-number>-description.md`
+
+   Please review it and let me know:
+   - Are the phases properly scoped?
+   - Are the success criteria specific enough?
+   - Any technical details that need adjustment?
+   - Missing edge cases or considerations?
+   ```
+
+3. **Iterate based on feedback** - be ready to:
+   - Add missing phases
+   - Adjust technical approach
+   - Clarify success criteria (both automated and manual)
+   - Add/remove scope items
+   - After making changes, run `thoughts-sync` again
+
+4. **Continue refining** until the user is satisfied
+
+## Important Guidelines
+
+1. **Be Skeptical**:
+   - Question vague requirements
+   - Identify potential issues early
+   - Ask "why" and "what about"
+   - Don't assume - verify with code
+
+2. **Be Interactive**:
+   - Don't write the full plan in one shot
+   - Get buy-in at each major step
+   - Allow course corrections
+   - Work collaboratively
+
+3. **Be Thorough**:
+   - Read all context files COMPLETELY before planning
+   - Research actual code patterns using parallel sub-tasks
+   - Include specific file paths and line numbers
+   - Write measurable success criteria with clear automated vs manual distinction
+   - automated steps should use `make` whenever possible - for example `make -C humanlayer-wui check` instead of `cd humanlayer-wui && bun run fmt`
+
+4. **Be Practical**:
+   - Focus on incremental, testable changes
+   - Consider migration and rollback
+   - Think about edge cases
+   - Include "what we're NOT doing"
+
+5. **Track Progress**:
+   - Track planning tasks as you go
+   - Update todos as you complete research
+   - Mark planning tasks complete when done
+
+6. **No Open Questions in Final Plan**:
+   - If you encounter open questions during planning, STOP
+   - Research or ask for clarification immediately
+   - Do NOT write the plan with unresolved questions
+   - The implementation plan must be complete and actionable
+   - Every decision must be made before finalizing the plan
+
+## Success Criteria Guidelines
+
+**Always separate success criteria into two categories:**
+
+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
+   - Automated test suites
+
+2. **Manual Verification** (requires human testing):
+   - UI/UX functionality
+   - Performance under real conditions
+   - Edge cases that are hard to automate
+   - User acceptance criteria
+
+**Format example:**
+```markdown
+### Success Criteria:
+
+#### Automated Verification:
+- [ ] Database migration runs successfully: `make migrate`
+- [ ] All unit tests pass: `go test ./...`
+- [ ] No linting errors: `golangci-lint run`
+- [ ] API endpoint returns 200: `curl localhost:8080/api/new-endpoint`
+
+#### Manual Verification:
+- [ ] New feature appears correctly in the UI
+- [ ] Performance is acceptable with 1000+ items
+- [ ] Error messages are user-friendly
+- [ ] Feature works correctly on mobile devices
+```
+
+## Common Patterns
+
+### For Database Changes:
+- Start with schema/migration
+- Add store methods
+- Update business logic
+- Expose via API
+- Update clients
+
+### For New Features:
+- Research existing patterns first
+- Start with data model
+- Build backend logic
+- Add API endpoints
+- Implement UI last
+
+### For Refactoring:
+- Document current behavior
+- Plan incremental changes
+- Maintain backwards compatibility
+- Include migration strategy
+
+## Sub-task Spawning Best Practices
+
+When spawning research sub-tasks:
+
+1. **Spawn multiple tasks in parallel** for efficiency
+2. **Each task should be focused** on a specific area
+3. **Provide detailed instructions** including:
+   - Exactly what to search for
+   - Which directories to focus on
+   - What information to extract
+   - Expected output format
+4. **Be EXTREMELY specific about directories**:
+   - If the ticket mentions "WUI", specify `humanlayer-wui/` directory
+   - If it mentions "daemon", specify `hld/` directory
+   - Never use generic terms like "UI" when you mean "WUI"
+   - Include the full path context in your prompts
+5. **Specify read-only tools** to use
+6. **Request specific file:line references** in responses
+7. **Wait for all tasks to complete** before synthesizing
+8. **Verify sub-task results**:
+   - If a sub-task returns unexpected results, spawn follow-up tasks
+   - Cross-check findings against the actual codebase
+   - Don't accept results that seem incorrect
+
+Example of spawning multiple tasks:
+```python
+# Spawn these tasks concurrently:
+tasks = [
+    Task("Research database schema", db_research_prompt),
+    Task("Find API patterns", api_research_prompt),
+    Task("Investigate UI components", ui_research_prompt),
+    Task("Check test patterns", test_research_prompt)
+]
+```
+
+## Example Interaction Flow
+
+```
+User: /implementation_plan
+Assistant: I'll help you create a detailed implementation plan...
+
+User: We need to add parent-child tracking for Claude sub-tasks. See ./thoughts/username/tickets/ENG-1234.md
+Assistant: Let me read that ticket file completely first...
+
+[Reads file fully]
+
+Based on the ticket, I understand we need to track parent-child relationships for Claude sub-task events in the hld daemon. Before I start planning, I have some questions...
+
+[Interactive process continues...]
+```

data/workflows/decompose_ticket.md

@@ -0,0 +1,109 @@
+---
+name: decompose_ticket
+description: "Decompose a feature ticket into vertical slices — testable, deliverable units ordered by dependency."
+---
+
+# Decompose Ticket
+
+Break a feature ticket into vertical slices. Each slice is a testable, deliverable unit that can be implemented, reviewed, and merged independently.
+
+## The Principle
+
+**Never decompose by layer. Always decompose by function.**
+
+Horizontal (wrong):
+- Task 1: Routes
+- Task 2: Model
+- Task 3: Controller
+- Task 4: Views
+
+Each piece is untestable in isolation. Nothing is deliverable until everything is done.
+
+Vertical (correct):
+- Slice 1: Model + index action + seeds → immediately visible
+- Slice 2: Show action → testable independently
+- Slice 3: Edit/update actions → independently deliverable
+- Slice 4: Delete action → independently deliverable
+
+Each slice = working functionality that can be tested and reviewed on its own.
+
+## Process
+
+### Step 1: Understand the Ticket
+
+Read the GitHub issue thoroughly. Identify:
+- What is the desired end state?
+- What are the acceptance criteria?
+- What components are involved (models, controllers, views, services, jobs)?
+
+Spawn the `thoughts-analyzer` specialist to find historical context about the feature area.
+
+### Step 2: Identify the Minimum Viable Slice
+
+The first slice must be the smallest unit that produces something visible/testable:
+
+**For Rails features:**
+- Model + migration + seeds + one controller action + route + minimal view
+- This is the "can I see something working?" threshold
+
+**For API features:**
+- Model + migration + one endpoint + request spec
+- This is the "can I call it and get a response?" threshold
+
+**For library/gem features:**
+- Core class + public method + unit spec
+- This is the "can I use it from a console?" threshold
+
+### Step 3: Slice by Function
+
+After the minimum slice, decompose remaining work by function:
+
+1. **Read-only first**: index, show, list, get — safe, easy to verify
+2. **Mutations second**: create, update, delete — each independently
+3. **Edge cases last**: error handling, validations, authorization — after happy path works
+
+Each slice must:
+- Build on previous slices (no orphaned dependencies)
+- Be independently testable
+- Have clear acceptance criteria
+- Be small enough for a single PR
+
+### Step 4: Create Sub-Issues
+
+For each slice, create a GitHub sub-issue:
+- Title: `Slice N: <what it delivers>`
+- Body: What's included, what's NOT included, acceptance criteria, dependencies
+- Link as sub-issue to the parent ticket
+
+```bash
+# Create sub-issue
+gh issue create --title "Slice 1: Model + index" --body "..."
+
+# Link as sub-issue to parent
+ISSUE_ID=$(gh api repos/{owner}/{repo}/issues/{new_number} --jq '.id')
+gh api repos/{owner}/{repo}/issues/{parent_number}/sub_issues -X POST -F sub_issue_id=$ISSUE_ID
+```
+
+### Step 5: Order and Verify
+
+Review the full sequence:
+- Does each slice build on the previous?
+- Is the first slice the smallest possible visible unit?
+- Can each slice be tested without the ones after it?
+- Are there any horizontal slices disguised as vertical? (e.g., "all migrations" is horizontal)
+
+Present the decomposition for review before creating issues.
+
+## Anti-Patterns
+
+- **"Set up the database first"** — horizontal. Include only the migration needed for slice 1.
+- **"Add all routes"** — horizontal. Add routes as each action is implemented.
+- **"Write all tests at the end"** — horizontal. Tests live with their slice.
+- **"Refactor before building"** — unless blocking, refactoring is its own slice.
+
+## Guidelines
+
+- Fewer, larger slices are better than many tiny ones — each slice has PR overhead
+- The first slice should be demonstrable within hours, not days
+- When in doubt about order: read before write, simple before complex, core before edge
+- Each slice should leave the codebase in a working state (green tests)