anima-core 0.3.0 → 1.0.0

data/workflows/feature.md

@@ -0,0 +1,91 @@
+---
+name: feature
+description: "Implement a GitHub issue end-to-end: branch, research, code, test, commit, PR, self-review."
+---
+
+## Context
+
+Create and complete a new feature or chore from branch creation to PR readiness.
+
+Read the GitHub issue to understand requirements. If no issue exists, create one via `gh issue create`.
+
+## Workflow
+
+### Step 1: Setup
+
+Pull latest base branch (usually `main` or `master`)
+Create feature branch: `<type>/<issue-number>-<short-description>` (e.g., `feature/42-add-api-endpoint`)
+Assign GitHub issue to self via `gh issue edit <number> --add-assignee @me`
+
+### Step 2: Gather Historical Context
+
+Spawn the `thoughts-analyzer` specialist with ticket reference, title, description, acceptance criteria, and any additional instructions from user input.
+
+DO NOT proceed to Step 3 until this specialist returns. Its output is required input for Step 3.
+
+### Step 3: Research Codebase
+
+After Step 2 completes, spawn research specialists in parallel, passing ticket info and historical context output from Step 2:
+
+`codebase-pattern-finder` — find similar implementations to model after
+`codebase-analyzer` — analyze the area being modified
+
+Wait for both specialists to complete before proceeding.
+
+### Step 4: Implementation
+
+Follow project conventions (CLAUDE.md) and best practices.
+Keep code clean, DRY, well-documented.
+When modifying code: fix lurking bugs, refactor, add missing tests and regression tests.
+Ensure solid test coverage with well-documented business logic (viewable with `--format documentation`).
+Review changes for completeness.
+
+### Step 5: Testing & Quality
+
+Run specs for changed/affected files only (never full suite locally): `bundle exec rspec spec/path/to/changed_spec.rb`
+`bundle exec reek` – Code smell detection
+`bundle exec standardrb --fix`
+`npx @herb-tools/linter --fix app/views/**/*.erb` (if views changed)
+Fix all issues, even flaky tests.
+
+### Step 6: Translations (i18n)
+
+`bundle exec i18n-tasks missing` – Check for missing translations
+`bundle exec i18n-tasks normalize` – Normalize locale files
+Add missing translations (manually or via OpenAI)
+
+### Step 7: Pull Request
+
+Push branch.
+`gh pr create --draft`
+Title: `#<issue-number> feat: <description>` or `#<issue-number> chore: <description>` or `#<issue-number> fix: <description>`
+Description: summary, test plan, breaking changes. Link to GitHub issue.
+
+### Step 8: CI Monitoring
+
+Monitor checks until all pass.
+If tests fail, investigate root cause vs flakiness.
+Fix flaky tests – don't just retry; stabilize the test.
+
+### Step 9: Finalization
+
+Update PR title/description if needed.
+
+## Requirements
+
+No direct pushes to `master`.
+Always branch per task.
+All tests must pass.
+All i18n translations must be present and normalized.
+Flaky tests must be fixed, not ignored.
+
+## Conventions (Beautiful Code)
+
+Boy Scout Rule: Leave the code cleaner than you found it.
+Favor Plain Old Ruby Objects (POROs) and service objects; keep controllers and models thin.
+Avoid N+1 queries by using includes (and consider Bullet for detection).
+Use clear, explicit naming; avoid magic values.
+Document all public APIs.
+Use squash merges to keep commit history clean.
+Write small, focused commits using Conventional Commits (feat:, chore:, fix:)
+

data/workflows/implement_plan.md

@@ -0,0 +1,87 @@
+---
+name: implement_plan
+description: "Implement an approved technical plan phase by phase with verification."
+---
+
+# Implement Plan
+
+You are tasked with implementing an approved technical plan from `./thoughts/shared/plans/`. These plans contain phases with specific changes and success criteria.
+
+## Getting Started
+
+When given a plan path:
+- Read the plan completely and check for any existing checkmarks (- [x])
+- Read the original ticket and all files mentioned in the plan
+- **Read files fully** - never use limit/offset parameters, you need complete context
+- Think deeply about how the pieces fit together
+- Create a todo list to track your progress
+- Start implementing if you understand what needs to be done
+
+If no plan path provided, ask for one.
+
+## Implementation Philosophy
+
+Plans are carefully designed, but reality can be messy. Your job is to:
+- Follow the plan's intent while adapting to what you find
+- Implement each phase fully before moving to the next
+- Verify your work makes sense in the broader codebase context
+- Update checkboxes in the plan as you complete sections
+
+When things don't match the plan exactly, think about why and communicate clearly. The plan is your guide, but your judgment matters too.
+
+If you encounter a mismatch:
+- STOP and think deeply about why the plan can't be followed
+- Present the issue clearly:
+  ```
+  Issue in Phase [N]:
+  Expected: [what the plan says]
+  Found: [actual situation]
+  Why this matters: [explanation]
+
+  How should I proceed?
+  ```
+
+## Verification Approach
+
+After implementing a phase:
+- Run the success criteria checks (usually `make check test` covers everything)
+- Fix any issues before proceeding
+- Update your progress in both the plan and your todos
+- Check off completed items in the plan file itself using Edit
+- **Pause for human verification**: After completing all automated verification for a phase, pause and inform the human that the phase is ready for manual testing. Use this format:
+  ```
+  Phase [N] Complete - Ready for Manual Verification
+
+  Automated verification passed:
+  - [List automated checks that passed]
+
+  Please perform the manual verification steps listed in the plan:
+  - [List manual verification items from the plan]
+
+  Let me know when manual testing is complete so I can proceed to Phase [N+1].
+  ```
+
+If instructed to execute multiple phases consecutively, skip the pause until the last phase. Otherwise, assume you are just doing one phase.
+
+do not check off items in the manual testing steps until confirmed by the user.
+
+
+## If You Get Stuck
+
+When something isn't working as expected:
+- First, make sure you've read and understood all the relevant code
+- Consider if the codebase has evolved since the plan was written
+- Present the mismatch clearly and ask for guidance
+
+Use sub-tasks sparingly - mainly for targeted debugging or exploring unfamiliar territory.
+
+## Resuming Work
+
+If no existing checkmarks, create feature branch from updated main. **Make sure you're on a feature branch before implementing!**
+
+If the plan has existing checkmarks:
+- Trust that completed work is done
+- Pick up from the first unchecked item
+- Verify previous work only if something seems off
+
+Remember: You're implementing a solution, not just checking boxes. Keep the end goal in mind and maintain forward momentum.

data/workflows/iterate_plan.md

@@ -0,0 +1,247 @@
+---
+name: iterate_plan
+description: "Iterate on existing implementation plans with research and targeted updates."
+---
+
+# 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**
+
+2. **Spawn parallel sub-tasks for research**:
+   Use the right agent for each type of research:
+
+   **For code investigation:**
+   - **codebase-analyzer** — find and understand implementation details
+   - **codebase-pattern-finder** — find similar patterns
+
+   **For historical context:**
+   - **thoughts-analyzer** — discover and extract insights from documents
+
+   **Be EXTREMELY specific about directories**:
+   - If the change involves "WUI", specify `humanlayer-wui/` directory
+   - If it involves "daemon", specify `hld/` directory
+   - 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 `thoughts-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**:
+   - 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.
+   - Prefer `make` commands: `make -C humanlayer-wui check` instead of `cd humanlayer-wui && bun run fmt`
+   - 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]
+```

data/workflows/research_codebase.md

@@ -0,0 +1,210 @@
+---
+name: research_codebase
+description: "Comprehensive codebase research by spawning parallel specialists and synthesizing findings."
+---
+
+# 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 (tickets, 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 to track all subtasks
+   - Consider which directories, files, or architectural patterns are relevant
+
+3. **Spawn parallel sub-agent tasks for comprehensive research:**
+   - Create multiple subagents to research different aspects concurrently
+   - We now have specialized agents that know how to do specific research tasks:
+
+   **For codebase research:**
+   - Use the **codebase-analyzer** specialist to find and understand HOW specific code works (without critiquing it)
+   - Use the **codebase-pattern-finder** specialist 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-analyzer** specialist to discover and extract key insights from documents (only the most relevant ones)
+
+   **For web research (only if user explicitly asks):**
+   - Use the **web-search-researcher** specialist 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
+
+   **For GitHub issues (if relevant):**
+   - Read issue details via `gh issue view <number>`
+   - Search related issues via `gh issue list --search "keyword"`
+
+   The key is to use these agents intelligently:
+   - Use analyzer agents to find relevant files and 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/username/ not ./thoughts/shared/ for personal files)
+   - Highlight patterns, connections, and architectural decisions
+   - Answer the user's specific questions with concrete evidence
+
+5. **Gather metadata for the research document:**
+   - Run `spec-metadata` (in the PATH) to generate all relevant metadata
+   - Filename: `./thoughts/shared/research/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 of the research topic
+     - Examples:
+       - With issue: `2026-03-15/170-import-workflows.md`
+       - Without issue: `2026-03-15/authentication-flow.md`
+
+6. **Generate research document:**
+   - Use the metadata gathered in step 4
+   - Structure the document with YAML frontmatter followed by content:
+     ```markdown
+     ---
+     date: [Current date and time with timezone in ISO format]
+     researcher: [Researcher name from thoughts status]
+     git_commit: [Current commit hash]
+     branch: [Current branch name]
+     repository: [Repository name]
+     topic: "[User's Question/Topic]"
+     tags: [research, codebase, relevant-component-names]
+     status: complete
+     last_updated: [Current date in YYYY-MM-DD format]
+     last_updated_by: [Researcher name]
+     ---
+
+     # Research: [User's Question/Topic]
+
+     **Date**: [Current date and time with timezone from step 4]
+     **Researcher**: [Researcher name from thoughts status]
+     **Git Commit**: [Current commit hash from step 4]
+     **Branch**: [Current branch name from step 4]
+     **Repository**: [Repository name]
+
+     ## Research Question
+     [Original user query]
+
+     ## Summary
+     [High-level documentation of what was found, 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 in the codebase]
+
+     ## 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
+     [Any areas that need further investigation]
+     ```
+
+7. **Add GitHub permalinks (if applicable):**
+   - Check if on main branch or if commit is pushed: `git branch --show-current` and `git status`
+   - If on main/master or pushed, generate GitHub permalinks:
+     - Get repo info: `gh repo view --json owner,name`
+     - Create permalinks: `https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}`
+   - Replace local file references with permalinks in the document
+
+8. **Sync and present findings:**
+   - Run `thoughts-sync` to sync the thoughts directory
+   - Present a concise summary of findings to the user
+   - Include key file references for easy navigation
+   - Ask if they have follow-up questions or need clarification
+
+9. **Handle follow-up questions:**
+   - If the user has follow-up questions, append to the same research document
+   - Update the frontmatter fields `last_updated` and `last_updated_by` to reflect the update
+   - Add `last_updated_note: "Added follow-up research for [brief description]"` to frontmatter
+   - Add a new section: `## Follow-up Research [timestamp]`
+   - Spawn new sub-agents as needed for additional investigation
+   - Continue updating the document and syncing
+
+## Important notes:
+- Always use parallel subagents 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
+- **REMEMBER**: Document what IS, not what SHOULD BE
+- **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
+- **Path handling**: The ./thoughts/searchable/ directory contains hard links for searching
+  - Always document paths by removing ONLY "searchable/" - preserve all other subdirectories
+  - Examples of correct transformations:
+    - `./thoughts/searchable/username/old_stuff/notes.md` → `./thoughts/username/old_stuff/notes.md`
+    - `./thoughts/searchable/shared/prs/123.md` → `./thoughts/shared/prs/123.md`
+    - `./thoughts/searchable/global/shared/templates.md` → `./thoughts/global/shared/templates.md`
+  - NEVER change username/ to shared/ or vice versa - preserve the exact directory structure
+  - This ensures paths are correct for editing and navigation
+- **Frontmatter consistency**:
+  - Always include frontmatter at the beginning of research documents
+  - Keep frontmatter fields consistent across all research documents
+  - Update frontmatter when adding follow-up research
+  - Use snake_case for multi-word field names (e.g., `last_updated`, `git_commit`)
+  - Tags should be relevant to the research topic and components studied