anima-core 0.3.0 → 1.0.0

data/workflows/resume_handoff.md

@@ -0,0 +1,217 @@
+---
+name: resume_handoff
+description: "Resume work from a handoff document with context analysis and validation."
+---
+
+# Resume work from a handoff document
+
+You are tasked with resuming work from a handoff document through an interactive process. These handoffs contain critical context, learnings, and next steps from previous work sessions that need to be understood and continued.
+
+## Initial Response
+
+When this command is invoked:
+
+1. **If the path to a handoff document was provided**:
+   - If a handoff document path was provided as a parameter, skip the default message
+   - Immediately read the handoff document FULLY
+   - Immediately read any research or plan documents that it links to under `./thoughts/shared/plans` or `./thoughts/shared/research`. do NOT use a sub-agent to read these critical files.
+   - Begin the analysis process by ingesting relevant context from the handoff document, reading additional files it mentions
+   - Then propose a course of action to the user and confirm, or ask for clarification on direction.
+
+2. **If a GitHub issue number was provided**:
+   - run `thoughts-sync` to ensure your `./thoughts/` directory is up to date.
+   - locate the most recent handoff document for the issue. Handoffs are located in `./thoughts/shared/handoffs/<issue-number>/`. e.g. for issue #170 the handoffs would be in `./thoughts/shared/handoffs/170/`. **List this directory's contents recursively** (handoffs are in date subdirectories like `YYYY-MM-DD/`).
+   - There may be zero, one or multiple files across the date subdirectories.
+   - **If there are zero files, or the directory does not exist**: tell the user: "I'm sorry, I can't seem to find that handoff document. Can you please provide me with a path to it?"
+   - **If there is only one file**: proceed with that handoff
+   - **If there are multiple files**: using the date from the subdirectory name (`YYYY-MM-DD`) and time from the filename (`HH-MM-SS`), proceed with the _most recent_ handoff document.
+   - Immediately read the handoff document FULLY
+   - Immediately read any research or plan documents that it links to under `./thoughts/shared/plans` or `./thoughts/shared/research`; do NOT use a sub-agent to read these critical files.
+   - Begin the analysis process by ingesting relevant context from the handoff document, reading additional files it mentions
+   - Then propose a course of action to the user and confirm, or ask for clarification on direction.
+
+3. **If no parameters provided**, respond with:
+```
+I'll help you resume work from a handoff document. Let me find the available handoffs.
+
+Which handoff would you like to resume from?
+
+Provide a handoff path (e.g., `./thoughts/shared/handoffs/170/2026-03-15/13-44-55_170_description.md`)
+or a GitHub issue number to resume from the most recent handoff for that issue.
+```
+
+Then wait for the user's input.
+
+## Process Steps
+
+### Step 1: Read and Analyze Handoff
+
+1. **Read handoff document completely**:
+   - Use the Read tool WITHOUT limit/offset parameters
+   - Extract all sections:
+     - Task(s) and their statuses
+     - Recent changes
+     - Learnings
+     - Artifacts
+     - Action items and next steps
+     - Other notes
+
+2. **Spawn focused research tasks**:
+   Based on the handoff content, spawn parallel research tasks to verify current state:
+
+   ```
+   Task 1 - Gather artifact context:
+   Read all artifacts mentioned in the handoff.
+   1. Read feature documents listed in "Artifacts"
+   2. Read implementation plans referenced
+   3. Read any research documents mentioned
+   4. Extract key requirements and decisions
+   Use tools: Read
+   Return: Summary of artifact contents and key decisions
+   ```
+
+3. **Wait for ALL sub-tasks to complete** before proceeding
+
+4. **Read critical files identified**:
+   - Read files from "Learnings" section completely
+   - Read files from "Recent changes" to understand modifications
+   - Read any new related files discovered during research
+
+### Step 2: Synthesize and Present Analysis
+
+1. **Present comprehensive analysis**:
+   ```
+   I've analyzed the handoff from [date] by [researcher]. Here's the current situation:
+
+   **Original Tasks:**
+   - [Task 1]: [Status from handoff] → [Current verification]
+   - [Task 2]: [Status from handoff] → [Current verification]
+
+   **Key Learnings Validated:**
+   - [Learning with file:line reference] - [Still valid/Changed]
+   - [Pattern discovered] - [Still applicable/Modified]
+
+   **Recent Changes Status:**
+   - [Change 1] - [Verified present/Missing/Modified]
+   - [Change 2] - [Verified present/Missing/Modified]
+
+   **Artifacts Reviewed:**
+   - [Document 1]: [Key takeaway]
+   - [Document 2]: [Key takeaway]
+
+   **Recommended Next Actions:**
+   Based on the handoff's action items and current state:
+   1. [Most logical next step based on handoff]
+   2. [Second priority action]
+   3. [Additional tasks discovered]
+
+   **Potential Issues Identified:**
+   - [Any conflicts or regressions found]
+   - [Missing dependencies or broken code]
+
+   Shall I proceed with [recommended action 1], or would you like to adjust the approach?
+   ```
+
+2. **Get confirmation** before proceeding
+
+### Step 3: Create Action Plan
+
+1. **Create task list**:
+   - Convert action items from handoff into todos
+   - Add any new tasks discovered during analysis
+   - Prioritize based on dependencies and handoff guidance
+
+2. **Present the plan**:
+   ```
+   I've created a task list based on the handoff and current analysis:
+
+   [Show todo list]
+
+   Ready to begin with the first task: [task description]?
+   ```
+
+### Step 4: Begin Implementation
+
+1. **Start with the first approved task**
+2. **Reference learnings from handoff** throughout implementation
+3. **Apply patterns and approaches documented** in the handoff
+4. **Update progress** as tasks are completed
+
+## Guidelines
+
+1. **Be Thorough in Analysis**:
+   - Read the entire handoff document first
+   - Verify ALL mentioned changes still exist
+   - Check for any regressions or conflicts
+   - Read all referenced artifacts
+
+2. **Be Interactive**:
+   - Present findings before starting work
+   - Get buy-in on the approach
+   - Allow for course corrections
+   - Adapt based on current state vs handoff state
+
+3. **Leverage Handoff Wisdom**:
+   - Pay special attention to "Learnings" section
+   - Apply documented patterns and approaches
+   - Avoid repeating mistakes mentioned
+   - Build on discovered solutions
+
+4. **Track Continuity**:
+   - Maintain task continuity
+   - Reference the handoff document in commits
+   - Document any deviations from original plan
+   - Consider creating a new handoff when done
+
+5. **Validate Before Acting**:
+   - Never assume handoff state matches current state
+   - Verify all file references still exist
+   - Check for breaking changes since handoff
+   - Confirm patterns are still valid
+
+## Common Scenarios
+
+### Scenario 1: Clean Continuation
+- All changes from handoff are present
+- No conflicts or regressions
+- Clear next steps in action items
+- Proceed with recommended actions
+
+### Scenario 2: Diverged Codebase
+- Some changes missing or modified
+- New related code added since handoff
+- Need to reconcile differences
+- Adapt plan based on current state
+
+### Scenario 3: Incomplete Handoff Work
+- Tasks marked as "in_progress" in handoff
+- Need to complete unfinished work first
+- May need to re-understand partial implementations
+- Focus on completing before new work
+
+### Scenario 4: Stale Handoff
+- Significant time has passed
+- Major refactoring has occurred
+- Original approach may no longer apply
+- Need to re-evaluate strategy
+
+## Example Interaction Flow
+
+```
+User: resume_handoff specification/feature/handoffs/handoff-0.md
+Assistant: Let me read and analyze that handoff document...
+
+[Reads handoff completely]
+[Spawns research tasks]
+[Waits for completion]
+[Reads identified files]
+
+I've analyzed the handoff from [date]. Here's the current situation...
+
+[Presents analysis]
+
+Shall I proceed with implementing the webhook validation fix, or would you like to adjust the approach?
+
+User: Yes, proceed with the webhook validation
+Assistant: [Creates todo list and begins implementation]
+```

data/workflows/review_pr.md

@@ -0,0 +1,320 @@
+---
+name: review_pr
+description: "Multi-agent PR review with three modes: review, re-review, self-review."
+---
+
+## Modes
+
+- **review** (default): Full review, present findings for approval before posting
+- **re-review**: Also load existing review feedback; verify previously requested changes were addressed
+- **self-review**: Fix findings directly in code instead of posting a review
+
+## Process
+
+### Step 1: Gather PR Metadata
+
+```bash
+gh pr view <PR_NUMBER> --json number,title,body,url,headRefName,baseRefName
+```
+
+Extract from PR body:
+- **Issue reference** (e.g., #123) — if found, fetch full issue details for requirements and acceptance criteria via `gh issue view`
+- **Business context** — why this change is needed
+
+If re-review mode is activated, also save all existing review feedback to `/tmp/` without reading them:
+```bash
+# Review verdicts and bodies (APPROVED, CHANGES_REQUESTED, COMMENTED)
+gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/reviews | tee /tmp/pr_<NUMBER>_reviews.json | jq length
+
+# Inline review comments on specific diff lines
+gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments | tee /tmp/pr_<NUMBER>_inline_comments.json | jq length
+
+# Conversation-level comments
+gh api repos/<OWNER>/<REPO>/issues/<PR_NUMBER>/comments | tee /tmp/pr_<NUMBER>_conversation.json | jq length
+```
+
+### Step 2: Fetch and Save Diff
+
+Checkout the PR branch locally and generate the diff. Save it to `/tmp/` — only subagents will read it.
+
+```bash
+git fetch origin
+git checkout <branch>
+
+# Use merge-base for a clean diff (handles diverged base branch)
+BASE=$(git merge-base origin/<baseRefName> HEAD)
+git diff $BASE -- . > /tmp/pr_<NUMBER>_diff.txt
+```
+
+If the user provided file exclusion or inclusion patterns in additional instructions, apply them using git's pathspec syntax:
+
+```bash
+# Exclude specific paths
+git diff $BASE -- . ':(exclude)path/to/noisy/dir' ':(exclude)*.ext' > /tmp/pr_<NUMBER>_diff.txt
+
+# Include only specific directories
+git diff $BASE -- path/to/dir1/ path/to/dir2/ > /tmp/pr_<NUMBER>_diff.txt
+
+# Combine inclusion with exclusion
+git diff $BASE -- path/to/dir/ ':(exclude)path/to/dir/subdir' > /tmp/pr_<NUMBER>_diff.txt
+```
+
+Verify the diff is non-empty: `wc -l < /tmp/pr_<NUMBER>_diff.txt`
+
+### Step 3: Gather Historical Context
+
+Spawn the **thoughts-analyzer** specialist to find historical knowledge about affected features.
+
+```
+specialist: thoughts-analyzer
+
+Prompt: "What do we know about <ticket reference and title from Step 1>? What decisions, constraints, and trade-offs should reviewers be aware of?"
+```
+
+**Wait for this specialist to complete before proceeding.**
+
+### Step 4: Spawn Review Subagents
+
+Spawn all five review subagents **in parallel** using `spawn_subagent`. Each receives:
+- Path to the diff file in `/tmp/`
+- Ticket context (from Step 1)
+- Historical context (from Step 3)
+- Their specific review focus
+- Any additional instructions from the user's input
+
+If re-review mode is activated, each subagent also receives the paths to `/tmp/pr_<NUMBER>_reviews.json`, `/tmp/pr_<NUMBER>_inline_comments.json`, and `/tmp/pr_<NUMBER>_conversation.json` with this modified instruction: "Primary goal: verify that previously requested changes were addressed. Secondary goal: check for new problems introduced."
+
+**Critical:** Spawn all five subagents in parallel to ensure concurrent execution.
+
+#### Subagent 1: RailsGuru
+
+```
+Prompt: "Review PR #<number> for Rails conventions and architecture.
+
+Read the diff from: /tmp/pr_<number>_diff.txt
+
+*Critical:* Activate the `activerecord` skill for AR patterns reference.
+
+## Ticket Context
+<ticket title, acceptance criteria, business context>
+
+## Historical Context
+<output from thoughts-analyzer>
+
+<any additional instructions from user input>
+
+## Focus Areas
+- MVC boundary violations (fat controllers, logic in views)
+- Rails idioms (proper use of scopes, callbacks, concerns)
+- REST conventions and route design
+- ActiveRecord patterns (associations, validations placement)
+- Service object patterns and naming
+
+Output: List findings tagged [major], [minor], or [nit] with file:line references."
+```
+
+#### Subagent 2: SecurityHawk
+
+```
+Prompt: "Review PR #<number> for security vulnerabilities.
+
+Read the diff from: /tmp/pr_<number>_diff.txt
+
+*Critical:* Activate the `activerecord` skill for SQL injection prevention patterns.
+
+## Ticket Context
+<ticket title, acceptance criteria, business context>
+
+## Historical Context
+<output from thoughts-analyzer>
+
+<any additional instructions from user input>
+
+## Focus Areas
+- SQL injection (raw queries, interpolation in where clauses)
+- XSS vulnerabilities (unescaped output, html_safe misuse)
+- CSRF protection gaps
+- Mass assignment vulnerabilities (permit params)
+- Authentication/authorization bypasses
+- Secrets or credentials in code
+- Insecure direct object references
+
+Output: List findings tagged [major], [minor], or [nit] with file:line references."
+```
+
+#### Subagent 3: PerfPro
+
+```
+Prompt: "Review PR #<number> for performance issues.
+
+Read the diff from: /tmp/pr_<number>_diff.txt
+
+*Critical:* Activate the `activerecord` skill for N+1 and query optimization patterns.
+
+## Ticket Context
+<ticket title, acceptance criteria, business context>
+
+## Historical Context
+<output from thoughts-analyzer>
+
+<any additional instructions from user input>
+
+## Focus Areas
+- N+1 query patterns (missing includes/preload/eager_load)
+- Expensive queries in loops
+- Missing database indexes for new queries
+- Inefficient ActiveRecord usage (pluck vs select, find_each vs each)
+- Memory bloat (loading large datasets)
+- Missing caching opportunities
+- Background job considerations (should this be async?)
+
+Output: List findings tagged [major], [minor], or [nit] with file:line references."
+```
+
+#### Subagent 4: TestCoach
+
+```
+Prompt: "Review PR #<number> for test quality and coverage.
+
+Read the diff from: /tmp/pr_<number>_diff.txt
+
+*Critical:* Activate the `rspec` skill for RSpec best practices reference.
+
+## Ticket Context
+<ticket title, acceptance criteria, business context>
+
+## Historical Context
+<output from thoughts-analyzer>
+
+<any additional instructions from user input>
+
+## Focus Areas
+- Missing test coverage for new code paths
+- Flaky test patterns (time-dependent, order-dependent)
+- Factory usage (proper traits, avoiding create when build suffices)
+- Test isolation issues (shared state, missing cleanup)
+- Assertion quality (testing behavior vs implementation)
+- Missing edge case coverage
+
+Output: List findings tagged [major], [minor], or [nit] with file:line references."
+```
+
+#### Subagent 5: DocScribe
+
+```
+Prompt: "Review PR #<number> for documentation and clarity.
+
+Read the diff from: /tmp/pr_<number>_diff.txt
+
+## Ticket Context
+<ticket title, acceptance criteria, business context>
+
+## Historical Context
+<output from thoughts-analyzer>
+
+<any additional instructions from user input>
+
+## Focus Areas
+- Method and class naming clarity
+- Missing YARD documentation on public interfaces
+- Complex logic lacking explanatory comments
+- Changelog updates for notable changes
+- Misleading or outdated comments
+- Magic numbers or strings needing constants
+
+Output: List findings tagged [major], [minor], or [nit] with file:line references."
+```
+
+### Step 5: Merge Results
+
+After all subagents complete, compile findings into a unified review.
+
+**Critical: Subagents are pattern matchers. You are the judgment layer.** Subagents are designed to be paranoid and thorough — they flag everything that matches their heuristics. Your job is to filter their output, not rubber-stamp it. A [major] from a subagent can become a [nit] or be dropped entirely after applying judgment.
+
+For each finding, evaluate:
+- **Real-world probability** — Can this actually happen in practice, or is it purely theoretical? A race condition that requires two users to open a personal link within the same millisecond is not a real issue.
+- **Cost-benefit** — Does the fix add more complexity than the problem warrants? If the "fix" makes the code harder to read without solving a problem a human would encounter, drop it.
+- **Scope** — Review fixes should improve code you're touching, not introduce new artifacts. Clean up, don't build out.
+
+Then compile:
+
+1. **Group by severity** — [major] first, then [minor], then [nit]
+2. **Remove duplicates** — Multiple agents may flag the same issue
+3. **Add actionable suggestions** — Include code snippets where helpful
+4. **Preserve file:line references** — Format as `app/models/user.rb:42`
+
+Determine verdict:
+- **REQUEST_CHANGES** — If any [major] or multiple [minor] issues survive the judgment filter
+- **APPROVE** — If no significant issues remain after filtering
+
+### Step 6: Finalize
+
+If self-review mode is activated, skip to **Self-review** below.
+
+#### Present and Post (review / re-review)
+
+Present the merged review to the user, including:
+- PR reference and ticket (if found)
+- Determined verdict
+- All findings grouped by severity
+
+Ask the user to confirm: "Shall I post this review to the PR? [Yes/Edit/Cancel]"
+- **Yes** — post the review
+- **Edit** — let the user modify the review, then ask again
+- **Cancel** — discard
+
+Once confirmed, post the review:
+
+```bash
+gh pr review <PR_NUMBER> --approve --body "<review body>"
+# or
+gh pr review <PR_NUMBER> --request-changes --body "<review body>"
+```
+
+#### Self-review
+
+Instead of presenting and posting, act on the findings:
+
+1. **Fix findings** — Address [major] and [minor] issues directly in code. Apply [nit]s at own discretion.
+2. **Commit and push** — Commit the fixes with a descriptive message and push to the PR branch.
+3. **Assign reviewer** — Assign the user and request review from anyone mentioned in additional instructions.
+4. **Wait for CI** — Monitor CI status. Once green, mark the PR as ready for review.
+
+```bash
+gh pr edit <PR_NUMBER> --add-assignee <user> --add-reviewer <reviewer>
+# once CI is green:
+gh pr ready <PR_NUMBER>
+```
+
+## Posted Review Format
+
+```markdown
+## PR Review Summary
+
+**Verdict: REQUEST_CHANGES**
+
+### Major Issues
+- `app/models/user.rb:42` - SQL injection via string interpolation in where clause
+  ```ruby
+  # Instead of:
+  User.where("name = '#{params[:name]}'")
+  # Use:
+  User.where(name: params[:name])
+  ```
+
+### Minor Issues
+- `app/controllers/users_controller.rb:15` - Business logic belongs in model or service
+
+### Suggestions
+- `app/services/user_service.rb:8` - Consider more descriptive method name
+
+---
+*Review generated with multi-agent analysis*
+```
+
+## Guidelines
+
+- Focus only on changed lines, not surrounding unchanged code
+- Provide concrete fix suggestions for [major] issues
+- The main agent must never read the diff file — only subagents read it
+- Pass additional instructions from user input through to all subagents

data/workflows/thoughts_init.md

@@ -0,0 +1,71 @@
+---
+name: thoughts_init
+description: "Initialize the thoughts system for the current repository."
+---
+
+# Initialize Thoughts System
+
+Initialize the thoughts system for the current repository.
+
+## Process
+
+### Step 1: Diagnostic Checks
+
+Run these checks and collect results:
+
+1. `~/thoughts` exists: `test -d "$HOME/thoughts"`
+2. `~/thoughts` is git repo: `test -d "$HOME/thoughts/.git"`
+3. `~/thoughts/global` structure exists: `test -d "$HOME/thoughts/global"`
+4. Scripts exist: `test -x "$HOME/thoughts/bin/thoughts-sync"`
+5. Scripts in PATH: `command -v thoughts-sync >/dev/null 2>&1`
+6. Current dir is git repo: `test -d ".git"`
+7. `./thoughts/shared` symlinked correctly: `test -L "./thoughts/shared" && readlink "./thoughts/shared" | grep -q "thoughts/repos/"`
+
+### Step 2: Report or Fix
+
+**If all checks pass:**
+```
+Thoughts system ready. Workflow commands will now work correctly.
+
+- ~/thoughts: OK (with global/ structure)
+- Scripts: OK (in PATH)
+- Repository: OK (thoughts/shared → ~/thoughts/repos/{repo}/shared)
+```
+
+**If any check fails:**
+Build todo list of what needs fixing, present to user, wait for authorization.
+
+### Step 3: Execute Fixes (after authorization)
+
+**If ~/thoughts missing:**
+```bash
+mkdir -p "$HOME/thoughts/bin"
+mkdir -p "$HOME/thoughts/global/$(whoami)"
+mkdir -p "$HOME/thoughts/global/shared"
+mkdir -p "$HOME/thoughts/repos"
+git -C "$HOME/thoughts" init
+# Copy thoughts bin scripts from the thoughts repository if available
+chmod +x "$HOME/thoughts/bin/"*
+```
+
+**If PATH not configured:**
+```bash
+RC_FILE="$HOME/.bashrc"
+[[ "$SHELL" == *"zsh"* ]] && RC_FILE="$HOME/.zshrc"
+echo 'export PATH="$HOME/thoughts/bin:$PATH"' >> "$RC_FILE"
+```
+Tell user to run `source ~/.zshrc` or restart terminal.
+
+**If current repo not initialized:**
+```bash
+"$HOME/thoughts/bin/thoughts-init-repo"
+```
+
+### Step 4: Verify and Report
+
+After fixes, re-run checks and report final status.
+
+## Important
+
+- Never make changes without user authorization
+- If current directory is not a git repo, report error and stop