ag-cortex 0.1.0

package/.agent/workflows/compound.md

@@ -0,0 +1,202 @@
+---
+name: compound
+description: Document a recently solved problem to compound your team's knowledge
+argument-hint: "[optional: brief context about the fix]"
+---
+
+# /compound
+
+Coordinate multiple subagents working in parallel to document a recently solved problem.
+
+## Purpose
+
+Captures problem solutions while context is fresh, creating structured documentation in `docs/solutions/` with YAML frontmatter for searchability and future reference. Uses parallel subagents for maximum efficiency.
+
+**Why "compound"?** Each documented solution compounds your team's knowledge. The first time you solve a problem takes research. Document it, and the next occurrence takes minutes. Knowledge compounds.
+
+## Usage
+
+```bash
+/compound                    # Document the most recent fix
+/compound [brief context]    # Provide additional context hint
+```
+
+## Execution Strategy: Parallel Subagents
+
+This command launches multiple specialized subagents IN PARALLEL to maximize efficiency:
+
+### 1. **Context Analyzer** (Parallel)
+   - Extracts conversation history
+   - Identifies problem type, component, symptoms
+   - Validates against CORA schema
+   - Returns: YAML frontmatter skeleton
+
+### 2. **Solution Extractor** (Parallel)
+   - Analyzes all investigation steps
+   - Identifies root cause
+   - Extracts working solution with code examples
+   - Returns: Solution content block
+
+### 3. **Related Docs Finder** (Parallel)
+   - Searches `docs/solutions/` for related documentation
+   - Identifies cross-references and links
+   - Finds related GitHub issues
+   - Returns: Links and relationships
+
+### 4. **Prevention Strategist** (Parallel)
+   - Develops prevention strategies
+   - Creates best practices guidance
+   - Generates test cases if applicable
+   - Returns: Prevention/testing content
+
+### 5. **Category Classifier** (Parallel)
+   - Determines optimal `docs/solutions/` category
+   - Validates category against schema
+   - Suggests filename based on slug
+   - Returns: Final path and filename
+
+### 6. **Documentation Writer** (Parallel)
+   - Assembles complete markdown file
+   - Validates YAML frontmatter
+   - Formats content for readability
+   - Creates the file in correct location
+
+### 7. **Optional: Specialized Agent Invocation** (Post-Documentation)
+   Based on problem type detected, automatically invoke applicable agents:
+   - **performance_issue** → `performance-oracle`
+   - **security_issue** → `security-sentinel`
+   - **database_issue** → `data-integrity-guardian`
+   - **test_failure** → `cora-test-reviewer`
+   - Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
+
+## What It Captures
+
+- **Problem symptom**: Exact error messages, observable behavior
+- **Investigation steps tried**: What didn't work and why
+- **Root cause analysis**: Technical explanation
+- **Working solution**: Step-by-step fix with code examples
+- **Prevention strategies**: How to avoid in future
+- **Cross-references**: Links to related issues and docs
+
+## Preconditions
+
+<preconditions enforcement="advisory">
+  <check condition="problem_solved">
+    Problem has been solved (not in-progress)
+  </check>
+  <check condition="solution_verified">
+    Solution has been verified working
+  </check>
+  <check condition="non_trivial">
+    Non-trivial problem (not simple typo or obvious error)
+  </check>
+</preconditions>
+
+## What It Creates
+
+**Organized documentation:**
+
+- File: `docs/solutions/[category]/[filename].md`
+
+**Categories auto-detected from problem:**
+
+- build-errors/
+- test-failures/
+- runtime-errors/
+- performance-issues/
+- database-issues/
+- security-issues/
+- ui-bugs/
+- integration-issues/
+- logic-errors/
+
+## Success Output
+
+```
+✓ Parallel documentation generation complete
+
+Primary Subagent Results:
+  ✓ Context Analyzer: Identified performance_issue in brief_system
+  ✓ Solution Extractor: Extracted 3 code fixes
+  ✓ Related Docs Finder: Found 2 related issues
+  ✓ Prevention Strategist: Generated test cases
+  ✓ Category Classifier: docs/solutions/performance-issues/
+  ✓ Documentation Writer: Created complete markdown
+
+Specialized Agent Reviews (Auto-Triggered):
+  ✓ performance-oracle: Validated query optimization approach
+  ✓ kieran-rails-reviewer: Code examples meet Rails standards
+  ✓ code-simplicity-reviewer: Solution is appropriately minimal
+  ✓ every-style-editor: Documentation style verified
+
+File created:
+- docs/solutions/performance-issues/n-plus-one-brief-generation.md
+
+This documentation will be searchable for future reference when similar
+issues occur in the Email Processing or Brief System modules.
+
+What's next?
+1. Continue workflow (recommended)
+2. Link related documentation
+3. Update other references
+4. View documentation
+5. Other
+```
+
+## The Compounding Philosophy
+
+This creates a compounding knowledge system:
+
+1. First time you solve "N+1 query in brief generation" → Research (30 min)
+2. Document the solution → docs/solutions/performance-issues/n-plus-one-briefs.md (5 min)
+3. Next time similar issue occurs → Quick lookup (2 min)
+4. Knowledge compounds → Team gets smarter
+
+The feedback loop:
+
+```
+Build → Test → Find Issue → Research → Improve → Document → Validate → Deploy
+    ↑                                                                      ↓
+    └──────────────────────────────────────────────────────────────────────┘
+```
+
+**Each unit of engineering work should make subsequent units of work easier—not harder.**
+
+## Auto-Invoke
+
+<auto_invoke> <trigger_phrases> - "that worked" - "it's fixed" - "working now" - "problem solved" </trigger_phrases>
+
+<manual_override> Use /compound [context] to document immediately without waiting for auto-detection. </manual_override> </auto_invoke>
+
+## Routes To
+
+`compound-docs` skill
+
+## Applicable Specialized Agents
+
+Based on problem type, these agents can enhance documentation:
+
+### Code Quality & Review
+- **kieran-rails-reviewer**: Reviews code examples for Rails best practices
+- **code-simplicity-reviewer**: Ensures solution code is minimal and clear
+- **pattern-recognition-specialist**: Identifies anti-patterns or repeating issues
+
+### Specific Domain Experts
+- **performance-oracle**: Analyzes performance_issue category solutions
+- **security-sentinel**: Reviews security_issue solutions for vulnerabilities
+- **cora-test-reviewer**: Creates test cases for prevention strategies
+- **data-integrity-guardian**: Reviews database_issue migrations and queries
+
+### Enhancement & Documentation
+- **best-practices-researcher**: Enriches solution with industry best practices
+- **every-style-editor**: Reviews documentation style and clarity
+- **framework-docs-researcher**: Links to Rails/gem documentation references
+
+### When to Invoke
+- **Auto-triggered** (optional): Agents can run post-documentation for enhancement
+- **Manual trigger**: User can invoke agents after /compound completes for deeper review
+
+## Related Commands
+
+- `/research [topic]` - Deep investigation (searches docs/solutions/ for patterns)
+- `/plan` - Planning workflow (references documented solutions)

package/.agent/workflows/create-agent-skill.md

@@ -0,0 +1,8 @@
+---
+name: create-agent-skill
+description: Create or edit Antigravity skills with expert guidance on structure and best practices
+allowed-tools: Skill(create-agent-skills)
+argument-hint: [skill description or requirements]
+---
+
+Invoke the create-agent-skills skill for: $ARGUMENTS

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

@@ -0,0 +1,334 @@
+---
+Description: Internal sub-workflow for the Deepen Plan research phase. Launches parallel agents for Skills, Learnings, and Reviews.
+---
+
+# Deepen Plan - Phase 2: Research Execution
+
+## Context
+Target Plan: <plan_path> #$ARGUMENTS </plan_path>
+
+## Main Tasks
+
+### 1. Parse and Analyze Plan Structure
+
+<thinking>
+First, read and parse the plan to identify each major section that can be enhanced with research.
+</thinking>
+
+**Read the plan file and extract:**
+- [ ] Overview/Problem Statement
+- [ ] Proposed Solution sections
+- [ ] Technical Approach/Architecture
+- [ ] Implementation phases/steps
+- [ ] Code examples and file references
+- [ ] Acceptance criteria
+- [ ] Any UI/UX components mentioned
+- [ ] Technologies/frameworks mentioned (Rails, React, Python, TypeScript, etc.)
+- [ ] Domain areas (data models, APIs, UI, security, performance, etc.)
+
+**Create a section manifest:**
+```
+Section 1: [Title] - [Brief description of what to research]
+Section 2: [Title] - [Brief description of what to research]
+...
+```
+
+### 2. Discover and Apply Available Skills
+
+<thinking>
+Dynamically discover all available skills and match them to plan sections. Don't assume what skills exist - discover them at runtime.
+</thinking>
+
+**Step 1: Discover ALL available skills from ALL sources**
+
+```bash
+# 1. Project-local skills (highest priority - project-specific)
+ls .agent/skills/
+
+# 2. User's global skills (~/.agent/)
+ls ~/.agent/skills/
+
+# 3. ALL other installed plugins - check every plugin for skills
+find ~/.agent -type d -name "skills" 2>/dev/null
+```
+
+**Important:** Check EVERY source. Don't assume Cortex is the only plugin. Use skills from ANY installed plugin that's relevant.
+
+**Step 2: For each discovered skill, read its SKILL.md to understand what it does**
+
+```bash
+# For each skill directory found, read its documentation
+cat [skill-path]/SKILL.md
+```
+
+**Step 3: Match skills to plan content**
+
+For each skill discovered:
+- Read its SKILL.md description
+- Check if any plan sections match the skill's domain
+- If there's a match, spawn a sub-agent to apply that skill's knowledge
+
+**Step 4: Spawn a sub-agent for EVERY matched skill**
+
+**CRITICAL: For EACH skill that matches, spawn a separate sub-agent and instruct it to USE that skill.**
+
+For each matched skill:
+```
+Task general-purpose: "You have the [skill-name] skill available at [skill-path].
+
+YOUR JOB: Use this skill on the plan.
+
+1. Read the skill: cat [skill-path]/SKILL.md
+2. Follow the skill's instructions exactly
+3. Apply the skill to this content:
+
+[relevant plan section or full plan]
+
+4. Return the skill's full output
+
+The skill tells you what to do - follow it. Execute the skill completely."
+```
+
+**Spawn ALL skill sub-agents in PARALLEL:**
+- 1 sub-agent per matched skill
+- Each sub-agent reads and uses its assigned skill
+- All run simultaneously
+- 10, 20, 30 skill sub-agents is fine
+
+**Each sub-agent:**
+1. Reads its skill's SKILL.md
+2. Follows the skill's workflow/instructions
+3. Applies the skill to the plan
+4. Returns whatever the skill produces (code, recommendations, patterns, reviews, etc.)
+
+**Example spawns:**
+```
+Task general-purpose: "Use the dhh-rails-style skill at ~/.agent/plugins/.../dhh-rails-style. Read SKILL.md and apply it to: [Rails sections of plan]"
+
+Task general-purpose: "Use the frontend-design skill at ~/.agent/plugins/.../frontend-design. Read SKILL.md and apply it to: [UI sections of plan]"
+
+Task general-purpose: "Use the agent-native-architecture skill at ~/.agent/plugins/.../agent-native-architecture. Read SKILL.md and apply it to: [agent/tool sections of plan]"
+
+Task general-purpose: "Use the security-patterns skill at ~/.agent/skills/security-patterns. Read SKILL.md and apply it to: [full plan]"
+```
+
+**No limit on skill sub-agents. Spawn one for every skill that could possibly be relevant.**
+
+### 3. Discover and Apply Learnings/Solutions
+
+<thinking>
+Check for documented learnings from /compound. These are solved problems stored as markdown files. Spawn a sub-agent for each learning to check if it's relevant.
+</thinking>
+
+**LEARNINGS LOCATION - Check these exact folders:**
+
+```
+docs/solutions/           <-- PRIMARY: Project-level learnings (created by /compound)
+├── performance-issues/
+│   └── *.md
+├── debugging-patterns/
+│   └── *.md
+├── configuration-fixes/
+│   └── *.md
+├── integration-issues/
+│   └── *.md
+├── deployment-issues/
+│   └── *.md
+└── [other-categories]/
+    └── *.md
+```
+
+**Step 1: Find ALL learning markdown files**
+
+Run these commands to get every learning file:
+
+```bash
+# PRIMARY LOCATION - Project learnings
+find docs/solutions -name "*.md" -type f 2>/dev/null
+
+# If docs/solutions doesn't exist, check alternate locations:
+find .agent/docs -name "*.md" -type f 2>/dev/null
+find ~/.agent/docs -name "*.md" -type f 2>/dev/null
+```
+
+**Step 2: Read frontmatter of each learning to filter**
+
+Each learning file has YAML frontmatter with metadata. Read the first ~20 lines of each file to get:
+
+```yaml
+---
+title: "N+1 Query Fix for Briefs"
+category: performance-issues
+tags: [activerecord, n-plus-one, includes, eager-loading]
+module: Briefs
+symptom: "Slow page load, multiple queries in logs"
+root_cause: "Missing includes on association"
+---
+```
+
+**For each .md file, quickly scan its frontmatter:**
+
+```bash
+# Read first 20 lines of each learning (frontmatter + summary)
+head -20 docs/solutions/**/*.md
+```
+
+**Step 3: Filter - only spawn sub-agents for LIKELY relevant learnings**
+
+Compare each learning's frontmatter against the plan:
+- `tags:` - Do any tags match technologies/patterns in the plan?
+- `category:` - Is this category relevant? (e.g., skip deployment-issues if plan is UI-only)
+- `module:` - Does the plan touch this module?
+- `symptom:` / `root_cause:` - Could this problem occur with the plan?
+
+**SKIP learnings that are clearly not applicable:**
+- Plan is frontend-only → skip `database-migrations/` learnings
+- Plan is Python → skip `rails-specific/` learnings
+- Plan has no auth → skip `authentication-issues/` learnings
+
+**SPAWN sub-agents for learnings that MIGHT apply:**
+- Any tag overlap with plan technologies
+- Same category as plan domain
+- Similar patterns or concerns
+
+**Step 4: Spawn sub-agents for filtered learnings**
+
+For each learning that passes the filter:
+
+```
+Task general-purpose: "
+LEARNING FILE: [full path to .md file]
+
+1. Read this learning file completely
+2. This learning documents a previously solved problem
+
+Check if this learning applies to this plan:
+
+---
+[full plan content]
+---
+
+If relevant:
+- Explain specifically how it applies
+- Quote the key insight or solution
+- Suggest where/how to incorporate it
+
+If NOT relevant after deeper analysis:
+- Say 'Not applicable: [reason]'
+"
+```
+
+**Example filtering:**
+```
+# Found 15 learning files, plan is about "Rails API caching"
+
+# SPAWN (likely relevant):
+docs/solutions/performance-issues/n-plus-one-queries.md      # tags: [activerecord] ✓
+docs/solutions/performance-issues/redis-cache-stampede.md    # tags: [caching, redis] ✓
+docs/solutions/configuration-fixes/redis-connection-pool.md  # tags: [redis] ✓
+
+# SKIP (clearly not applicable):
+docs/solutions/deployment-issues/heroku-memory-quota.md      # not about caching
+docs/solutions/frontend-issues/stimulus-race-condition.md    # plan is API, not frontend
+docs/solutions/authentication-issues/jwt-expiry.md           # plan has no auth
+```
+
+**Spawn sub-agents in PARALLEL for all filtered learnings.**
+
+**These learnings are institutional knowledge - applying them prevents repeating past mistakes.**
+
+### 4. Launch Per-Section Research Agents
+
+<thinking>
+For each major section in the plan, spawn dedicated sub-agents to research improvements. Use the Explore agent type for open-ended research.
+</thinking>
+
+**For each identified section, launch parallel research:**
+
+```
+Task Explore: "Research best practices, patterns, and real-world examples for: [section topic].
+Find:
+- Industry standards and conventions
+- Performance considerations
+- Common pitfalls and how to avoid them
+- Documentation and tutorials
+Return concrete, actionable recommendations."
+```
+
+**Also use Context7 MCP for framework documentation:**
+
+For any technologies/frameworks mentioned in the plan, query Context7:
+```
+mcp_context7_resolve-library-id: Find library ID for [framework]
+mcp_context7_query-docs: Query documentation for specific patterns
+```
+
+**Use WebSearch for current best practices:**
+
+Search for recent (2024-2025) articles, blog posts, and documentation on topics in the plan.
+
+### 5. Discover and Run ALL Review Agents
+
+<thinking>
+Dynamically discover every available agent and run them ALL against the plan. Don't filter, don't skip, don't assume relevance. 40+ parallel agents is fine. Use everything available.
+</thinking>
+
+**Step 1: Discover ALL available agents from ALL sources**
+
+```bash
+# 1. Project-local agents (highest priority - project-specific)
+find .agent/agents -name "*.md" 2>/dev/null
+
+# 2. User's global agents (~/.agent/)
+find ~/.agent/agents -name "*.md" 2>/dev/null
+
+# 3. compound-engineering plugin agents (all subdirectories)
+find ~/.agent/plugins/cache/*/compound-engineering/*/agents -name "*.md" 2>/dev/null
+
+# 4. ALL other installed plugins - check every plugin for agents
+find ~/.agent/plugins/cache -path "*/agents/*.md" 2>/dev/null
+
+# 5. Check installed_plugins.json to find all plugin locations
+cat ~/.agent/plugins/installed_plugins.json
+
+# 6. For local plugins (isLocal: true), check their source directories
+# Parse installed_plugins.json and find local plugin paths
+```
+
+**Important:** Check EVERY source. Include agents from:
+- Project `.agent/agents/`
+- User's `~/.agent/agents/`
+- compound-engineering plugin (but SKIP workflow/ agents - only use review/, research/, design/, docs/)
+- ALL other installed plugins (agent-sdk-dev, frontend-design, etc.)
+- Any local plugins
+
+**For compound-engineering plugin specifically:**
+- USE: `agents/review/*` (all reviewers)
+- USE: `agents/research/*` (all researchers)
+- USE: `agents/design/*` (design agents)
+- USE: `agents/docs/*` (documentation agents)
+- SKIP: `agents/workflow/*` (these are workflow orchestrators, not reviewers)
+
+**Step 2: For each discovered agent, read its description**
+
+Read the first few lines of each agent file to understand what it reviews/analyzes.
+
+**Step 3: Launch ALL agents in parallel**
+
+For EVERY agent discovered, launch a Task in parallel:
+
+```
+Task [agent-name]: "Review this plan using your expertise. Apply all your checks and patterns. Plan content: [full plan content]"
+```
+
+**CRITICAL RULES:**
+- Do NOT filter agents by "relevance" - run them ALL
+- Do NOT skip agents because they "might not apply" - let them decide
+- Launch ALL agents in a SINGLE message with multiple Task tool calls
+- 20, 30, 40 parallel agents is fine - use everything
+- Each agent may catch something others miss
+- The goal is MAXIMUM coverage, not efficiency
+
+**Step 4: Also discover and run research agents**
+
+Research agents (like `best-practices-researcher`, `framework-docs-researcher`, `git-history-analyzer`, `repo-research-analyst`) should also be run for relevant plan sections.