ag-cortex 0.1.0

package/.agent/workflows/deepen-plan-synthesis.md

@@ -0,0 +1,182 @@
+---
+Description: Internal sub-workflow for the Deepen Plan synthesis phase. Updates the plan file and enforces safety constraints.
+---
+
+# Deepen Plan - Phase 3: Synthesis Execution
+
+## Context
+Target Plan: <plan_path> #$ARGUMENTS </plan_path>
+
+## Main Tasks
+
+### 6. Wait for ALL Agents and Synthesize Everything
+
+<thinking>
+Wait for ALL parallel agents to complete - skills, research agents, review agents, everything. Then synthesize all findings into a comprehensive enhancement.
+</thinking>
+
+**Collect outputs from ALL sources:**
+
+1. **Skill-based sub-agents** - Each skill's full output (code examples, patterns, recommendations)
+2. **Learnings/Solutions sub-agents** - Relevant documented learnings from /compound
+3. **Research agents** - Best practices, documentation, real-world examples
+4. **Review agents** - All feedback from every reviewer (architecture, security, performance, simplicity, etc.)
+5. **Context7 queries** - Framework documentation and patterns
+6. **Web searches** - Current best practices and articles
+
+**For each agent's findings, extract:**
+- [ ] Concrete recommendations (actionable items)
+- [ ] Code patterns and examples (copy-paste ready)
+- [ ] Anti-patterns to avoid (warnings)
+- [ ] Performance considerations (metrics, benchmarks)
+- [ ] Security considerations (vulnerabilities, mitigations)
+- [ ] Edge cases discovered (handling strategies)
+- [ ] Documentation links (references)
+- [ ] Skill-specific patterns (from matched skills)
+- [ ] Relevant learnings (past solutions that apply - prevent repeating mistakes)
+
+**Deduplicate and prioritize:**
+- Merge similar recommendations from multiple agents
+- Prioritize by impact (high-value improvements first)
+- Flag conflicting advice for human review
+- Group by plan section
+
+### 7. Enhance Plan Sections
+
+<thinking>
+Merge research findings back into the plan, adding depth without changing the original structure.
+</thinking>
+
+**Enhancement format for each section:**
+
+```markdown
+## [Original Section Title]
+
+[Original content preserved]
+
+### Research Insights
+
+**Best Practices:**
+- [Concrete recommendation 1]
+- [Concrete recommendation 2]
+
+**Performance Considerations:**
+- [Optimization opportunity]
+- [Benchmark or metric to target]
+
+**Implementation Details:**
+```[language]
+// Concrete code example from research
+```
+
+**Edge Cases:**
+- [Edge case 1 and how to handle]
+- [Edge case 2 and how to handle]
+
+**References:**
+- [Documentation URL 1]
+- [Documentation URL 2]
+```
+
+### 8. Add Enhancement Summary
+
+At the top of the plan, add a summary section:
+
+```markdown
+## Enhancement Summary
+
+**Deepened on:** [Date]
+**Sections enhanced:** [Count]
+**Research agents used:** [List]
+
+### Key Improvements
+1. [Major improvement 1]
+2. [Major improvement 2]
+3. [Major improvement 3]
+
+### New Considerations Discovered
+- [Important finding 1]
+- [Important finding 2]
+```
+
+### 9. Update Plan File
+
+**Write the enhanced plan:**
+- Preserve original filename
+- Add `-deepened` suffix if user prefers a new file
+- Update any timestamps or metadata
+
+## Output Format
+ 
+**Update the plan:**
+ 
+- If modifying an **Artifact**: Use `multi_replace_file_content` or `replace_file_content` on the artifact path. Ensure `ArtifactMetadata` is updated.
+- If modifying a **Local File**: Update the file in place.
+
+## Quality Checks
+
+Before finalizing:
+- [ ] All original content preserved
+- [ ] Research insights clearly marked and attributed
+- [ ] Code examples are syntactically correct
+- [ ] Links are valid and relevant
+- [ ] No contradictions between sections
+- [ ] Enhancement summary accurately reflects changes
+
+## Example Enhancement
+
+**Before (from /plan):**
+```markdown
+## Technical Approach
+
+Use React Query for data fetching with optimistic updates.
+```
+
+**After (from /deepen-plan):**
+```markdown
+## Technical Approach
+
+Use React Query for data fetching with optimistic updates.
+
+### Research Insights
+
+**Best Practices:**
+- Configure `staleTime` and `cacheTime` based on data freshness requirements
+- Use `queryKey` factories for consistent cache invalidation
+- Implement error boundaries around query-dependent components
+
+**Performance Considerations:**
+- Enable `refetchOnWindowFocus: false` for stable data to reduce unnecessary requests
+- Use `select` option to transform and memoize data at query level
+- Consider `placeholderData` for instant perceived loading
+
+**Implementation Details:**
+
+    // Recommended query configuration
+    const queryClient = new QueryClient({
+    defaultOptions: {
+        queries: {
+        staleTime: 5 * 60 * 1000, // 5 minutes
+        retry: 2,
+        refetchOnWindowFocus: false,
+        },
+    },
+    });
+
+
+**Edge Cases:**
+- Handle race conditions with `cancelQueries` on component unmount
+- Implement retry logic for transient network failures
+- Consider offline support with `persistQueryClient`
+
+**References:**
+- https://tanstack.com/query/latest/docs/react/guides/optimistic-updates
+- https://tkdodo.eu/blog/practical-react-query
+```
+
+**NEVER CODE!**
+
+Your job is to **research** and **enhance the plan**, not to implement the plan.
+- Do not write implementation files.
+- Do not modify source code.
+- ONLY modify the markdown plan file.

package/.agent/workflows/deepen-plan.md

@@ -0,0 +1,79 @@
+---
+Description: Enhance a plan with parallel research agents for each section to add depth, best practices, and implementation details
+---
+
+# Deepen Plan - Power Enhancement Mode
+
+## Introduction
+
+**Note: The current year is 2026.** Use this when searching for recent documentation and best practices.
+
+This command takes an existing plan (from `/plan`) and enhances each section with parallel research agents. Each major element gets its own dedicated research sub-agent to find:
+- Best practices and industry patterns
+- Performance optimizations
+- UI/UX improvements (if applicable)
+- Quality enhancements and edge cases
+- Real-world implementation examples
+
+The result is a deeply grounded, production-ready plan with concrete implementation details.
+
+## Phase 1: Setup
+
+<plan_path> #$ARGUMENTS </plan_path>
+
+**Validation Step:**
+1. **Analyze Input:**
+    - If `<plan_path>` is provided, check if it points to a file OR if the user is referring to the current artifact.
+    - If `<plan_path>` is EMPTY, perform a sequential check:
+
+        **A. Check Active Context (Priority):**
+        - Check your conversation metadata for an active `implementation_plan` artifact.
+        - If found, **extract its ABSOLUTE FILE PATH** (from your system metadata/reminders) and use that specifically as the `<plan_path>`.
+        - **IMPORTANT:** If using an artifact, you may proceed without explicit file paths in typical arguments, as long as tools know where to look.
+       
+        **B. Search Local Files:**
+        - If no active artifact is found, run: `find . -maxdepth 3 -name "*plan*.md" -not -path "*/.*"`
+
+2. **User Interaction:**
+    - If you are using an **Active Plan Artifact**, log this action in your internal thought process or Task Status, but **DO NOT stop to notify the user**. Proceed immediately to Phase 2.
+    - If you found local files, list them and ask: "Which of these plans would you like to deepen?"
+    - If nothing is found, ask for the plan content or path manually.
+
+3. **Critical Check:**
+    - Ensure you have a valid path (artifact path or local file path) to read the plan from.
+
+## Phase 2: Research Execution
+
+### Execute Research Phase
+
+Call `/deepen-plan-research` with the argument `<plan_path>`.
+
+*Wait for the research phase to complete.*
+
+## Phase 3: Synthesis Execution
+
+### Execute Synthesis Phase
+
+Call `/deepen-plan-synthesis` with the argument `<plan_path>`.
+
+*Wait for the synthesis phase to complete.*
+
+## Phase 4: Post-Enhancement Options
+
+After writing the enhanced plan, use the **workflows:ask-user-question** to present these options:
+
+**Question:** "Plan deepened at `[plan_path]`. What would you like to do next?"
+
+**Options:**
+1. **View diff** - Show what was added/changed
+2. **Run `/plan-review`** - Get feedback from reviewers on enhanced plan
+3. **Start `/work`** - Begin implementing this enhanced plan
+4. **Deepen further** - Run another round of research on specific sections
+5. **Revert** - Restore original plan (if backup exists)
+
+Based on selection:
+- **View diff** → Run `git diff [plan_path]` or show before/after
+- **`/plan-review`** → Call the /plan-review command with the plan file path
+- **`/work`** → Call the /work command with the plan file path
+- **Deepen further** → Ask which sections need more research, then re-run those agents
+- **Revert** → Restore from git or backup

package/.agent/workflows/feature-video.md

@@ -0,0 +1,342 @@
+---
+name: feature-video
+description: Record a video walkthrough of a feature and add it to the PR description
+argument-hint: "[PR number or 'current'] [optional: base URL, default localhost:3000]"
+---
+
+# Feature Video Walkthrough
+
+<command_purpose>Record a video walkthrough demonstrating a feature, upload it, and add it to the PR description.</command_purpose>
+
+## Introduction
+
+<role>Developer Relations Engineer creating feature demo videos</role>
+
+This command creates professional video walkthroughs of features for PR documentation:
+- Records browser interactions using agent-browser CLI
+- Demonstrates the complete user flow
+- Uploads the video for easy sharing
+- Updates the PR description with an embedded video
+
+## Prerequisites
+
+<requirements>
+- Local development server running (e.g., `bin/dev`, `rails server`)
+- agent-browser CLI installed
+- Git repository with a PR to document
+- `ffmpeg` installed (for video conversion)
+- `rclone` configured (optional, for cloud upload - see rclone skill)
+</requirements>
+
+## Setup
+
+**Check installation:**
+```bash
+command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"
+```
+
+**Install if needed:**
+```bash
+npm install -g agent-browser && agent-browser install
+```
+
+See the `agent-browser` skill for detailed usage.
+
+## Main Tasks
+
+### 1. Parse Arguments
+
+<parse_args>
+
+**Arguments:** $ARGUMENTS
+
+Parse the input:
+- First argument: PR number or "current" (defaults to current branch's PR)
+- Second argument: Base URL (defaults to `http://localhost:3000`)
+
+```bash
+# Get PR number for current branch if needed
+gh pr view --json number -q '.number'
+```
+
+</parse_args>
+
+### 2. Gather Feature Context
+
+<gather_context>
+
+**Get PR details:**
+```bash
+gh pr view [number] --json title,body,files,headRefName -q '.'
+```
+
+**Get changed files:**
+```bash
+gh pr view [number] --json files -q '.files[].path'
+```
+
+**Map files to testable routes** (same as test-browser):
+
+| File Pattern | Route(s) |
+|-------------|----------|
+| `app/views/users/*` | `/users`, `/users/:id`, `/users/new` |
+| `app/controllers/settings_controller.rb` | `/settings` |
+| `app/javascript/controllers/*_controller.js` | Pages using that Stimulus controller |
+| `app/components/*_component.rb` | Pages rendering that component |
+
+</gather_context>
+
+### 3. Plan the Video Flow
+
+<plan_flow>
+
+Before recording, create a shot list:
+
+1. **Opening shot**: Homepage or starting point (2-3 seconds)
+2. **Navigation**: How user gets to the feature
+3. **Feature demonstration**: Core functionality (main focus)
+4. **Edge cases**: Error states, validation, etc. (if applicable)
+5. **Success state**: Completed action/result
+
+Ask user to confirm or adjust the flow:
+
+```markdown
+**Proposed Video Flow**
+
+Based on PR #[number]: [title]
+
+1. Start at: /[starting-route]
+2. Navigate to: /[feature-route]
+3. Demonstrate:
+   - [Action 1]
+   - [Action 2]
+   - [Action 3]
+4. Show result: [success state]
+
+Estimated duration: ~[X] seconds
+
+Does this look right?
+1. Yes, start recording
+2. Modify the flow (describe changes)
+3. Add specific interactions to demonstrate
+```
+
+</plan_flow>
+
+### 4. Setup Video Recording
+
+<setup_recording>
+
+**Create videos directory:**
+```bash
+mkdir -p tmp/videos
+```
+
+**Recording approach: Use browser screenshots as frames**
+
+agent-browser captures screenshots at key moments, then combine into video using ffmpeg:
+
+```bash
+ffmpeg -framerate 2 -pattern_type glob -i 'tmp/screenshots/*.png' -vf "scale=1280:-1" tmp/videos/feature-demo.gif
+```
+
+</setup_recording>
+
+### 5. Record the Walkthrough
+
+<record_walkthrough>
+
+Execute the planned flow, capturing each step:
+
+**Step 1: Navigate to starting point**
+```bash
+agent-browser open "[base-url]/[start-route]"
+agent-browser wait 2000
+agent-browser screenshot tmp/screenshots/01-start.png
+```
+
+**Step 2: Perform navigation/interactions**
+```bash
+agent-browser snapshot -i  # Get refs
+agent-browser click @e1    # Click navigation element
+agent-browser wait 1000
+agent-browser screenshot tmp/screenshots/02-navigate.png
+```
+
+**Step 3: Demonstrate feature**
+```bash
+agent-browser snapshot -i  # Get refs for feature elements
+agent-browser click @e2    # Click feature element
+agent-browser wait 1000
+agent-browser screenshot tmp/screenshots/03-feature.png
+```
+
+**Step 4: Capture result**
+```bash
+agent-browser wait 2000
+agent-browser screenshot tmp/screenshots/04-result.png
+```
+
+**Create video/GIF from screenshots:**
+
+```bash
+# Create directories
+mkdir -p tmp/videos tmp/screenshots
+
+# Create MP4 video (RECOMMENDED - better quality, smaller size)
+# -framerate 0.5 = 2 seconds per frame (slower playback)
+# -framerate 1 = 1 second per frame
+ffmpeg -y -framerate 0.5 -pattern_type glob -i 'tmp/screenshots/*.png' \
+  -c:v libx264 -pix_fmt yuv420p -vf "scale=1280:-2" \
+  tmp/videos/feature-demo.mp4
+
+# Create low-quality GIF for preview (small file, for GitHub embed)
+ffmpeg -y -framerate 0.5 -pattern_type glob -i 'tmp/screenshots/*.png' \
+  -vf "scale=640:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=128[p];[s1][p]paletteuse" \
+  -loop 0 tmp/videos/feature-demo-preview.gif
+```
+
+**Note:**
+- The `-2` in MP4 scale ensures height is divisible by 2 (required for H.264)
+- Preview GIF uses 640px width and 128 colors to keep file size small (~100-200KB)
+
+</record_walkthrough>
+
+### 6. Upload the Video
+
+<upload_video>
+
+**Upload with rclone:**
+
+```bash
+# Check rclone is configured
+rclone listremotes
+
+# Upload video, preview GIF, and screenshots to cloud storage
+# Use --s3-no-check-bucket to avoid permission errors
+rclone copy tmp/videos/ r2:kieran-claude/pr-videos/pr-[number]/ --s3-no-check-bucket --progress
+rclone copy tmp/screenshots/ r2:kieran-claude/pr-videos/pr-[number]/screenshots/ --s3-no-check-bucket --progress
+
+# List uploaded files
+rclone ls r2:kieran-claude/pr-videos/pr-[number]/
+```
+
+Public URLs (R2 with public access):
+```
+Video: https://pub-4047722ebb1b4b09853f24d3b61467f1.r2.dev/pr-videos/pr-[number]/feature-demo.mp4
+Preview: https://pub-4047722ebb1b4b09853f24d3b61467f1.r2.dev/pr-videos/pr-[number]/feature-demo-preview.gif
+```
+
+</upload_video>
+
+### 7. Update PR Description
+
+<update_pr>
+
+**Get current PR body:**
+```bash
+gh pr view [number] --json body -q '.body'
+```
+
+**Add video section to PR description:**
+
+If the PR already has a video section, replace it. Otherwise, append:
+
+**IMPORTANT:** GitHub cannot embed external MP4s directly. Use a clickable GIF that links to the video:
+
+```markdown
+## Demo
+
+[![Feature Demo]([preview-gif-url])]([video-mp4-url])
+
+*Click to view full video*
+```
+
+Example:
+```markdown
+[![Feature Demo](https://pub-4047722ebb1b4b09853f24d3b61467f1.r2.dev/pr-videos/pr-137/feature-demo-preview.gif)](https://pub-4047722ebb1b4b09853f24d3b61467f1.r2.dev/pr-videos/pr-137/feature-demo.mp4)
+```
+
+**Update the PR:**
+```bash
+gh pr edit [number] --body "[updated body with video section]"
+```
+
+**Or add as a comment if preferred:**
+```bash
+gh pr comment [number] --body "## Feature Demo
+
+![Demo]([video-url])
+
+_Automated walkthrough of the changes in this PR_"
+```
+
+</update_pr>
+
+### 8. Cleanup
+
+<cleanup>
+
+```bash
+# Optional: Clean up screenshots
+rm -rf tmp/screenshots
+
+# Keep videos for reference
+echo "Video retained at: tmp/videos/feature-demo.gif"
+```
+
+</cleanup>
+
+### 9. Summary
+
+<summary>
+
+Present completion summary:
+
+```markdown
+## Feature Video Complete
+
+**PR:** #[number] - [title]
+**Video:** [url or local path]
+**Duration:** ~[X] seconds
+**Format:** [GIF/MP4]
+
+### Shots Captured
+1. [Starting point] - [description]
+2. [Navigation] - [description]
+3. [Feature demo] - [description]
+4. [Result] - [description]
+
+### PR Updated
+- [x] Video section added to PR description
+- [ ] Ready for review
+
+**Next steps:**
+- Review the video to ensure it accurately demonstrates the feature
+- Share with reviewers for context
+```
+
+</summary>
+
+## Quick Usage Examples
+
+```bash
+# Record video for current branch's PR
+/feature-video
+
+# Record video for specific PR
+/feature-video 847
+
+# Record with custom base URL
+/feature-video 847 http://localhost:5000
+
+# Record for staging environment
+/feature-video current https://staging.example.com
+```
+
+## Tips
+
+- **Keep it short**: 10-30 seconds is ideal for PR demos
+- **Focus on the change**: Don't include unrelated UI
+- **Show before/after**: If fixing a bug, show the broken state first (if possible)
+- **Annotate if needed**: Add text overlays for complex features