diff --git a/intent/llm/AGENTS.md b/intent/llm/AGENTS.md index 297e003..3f5352a 100644 --- a/intent/llm/AGENTS.md +++ b/intent/llm/AGENTS.md @@ -95,9 +95,11 @@ intent claude subagents install # Install a subagent ``` Available subagents: +- **ash-expert**: Modern Ash 3.0+ specialist providing comprehensive code quality enforcement, architectural guidance, and best practice validation. Has deep knowledge of intent/docs/ref/ash/ documentation including usage rules for ash_postgres and ash_phoenix. Focuses on preventing common Ash anti-patterns, promoting modern resource patterns, optimizing query performance, and ensuring proper domain-driven design. Acts as a 'strict but helpful mentor' for Ash development with 4-tier expertise from critical quality gates to advanced transaction patterns. - **elixir**: Elixir code doctor with functional programming expertise and Usage Rules integration - **intent**: Intent-aware assistant for steel threads and backlog management - **socrates**: CTO Review Mode - Socratic dialog for technical decision-making +- **worker-bee**: Worker-Bee Driven Design specialist for any Elixir application. Conducts interactive project structure mapping, enforces WDD 6-layer architecture compliance, validates functional core purity, and scaffolds WDD-compliant code. Works with Phoenix, OTP, libraries, and any Elixir project type. ## Security Considerations @@ -113,4 +115,4 @@ Available subagents: - Claude-specific instructions: `CLAUDE.md` --- -*Generated by Intent v2.2.1 on 2025-08-20* +*Generated by Intent v2.3.2 on 2025-09-04* diff --git a/intent/llm/AGENTS.md.bak b/intent/llm/AGENTS.md.bak new file mode 100644 index 0000000..297e003 --- /dev/null +++ b/intent/llm/AGENTS.md.bak @@ -0,0 +1,116 @@ +# AGENTS.md + +## Project Overview + +This is an Intent project. See CLAUDE.md for project-specific guidelines. + +## Development Environment + +### Prerequisites +- Bash 4.0 or higher +- POSIX-compliant shell environment +- Bats testing framework + +### Setup +```bash +# Initialize Intent project +intent init + +# Install dependencies (if applicable) +``` + +## Build and Test Commands + +### Testing +```bash +# Run tests +bats tests/*.bats +``` + +### Building +No build process required. + +### Validation +```bash +# Check Intent configuration +intent doctor + +# Validate project structure +intent st list +``` + +## Code Style Guidelines + +- Shell scripts: 2-space indentation, POSIX compliance +- Markdown: Standard formatting with verblock headers +- Follow existing patterns in the codebase + +See `intent/llm/usage-rules.md` for detailed code style rules. + +## Testing Instructions + +All changes should be validated with the test suite before committing. + +1. Run the full test suite before making changes to establish baseline +2. Make your changes +3. Run tests again to ensure nothing broke +4. Add new tests for new functionality + +## Commit and PR Guidelines + +### Commit Messages +- Use conventional commit format when applicable +- Be descriptive about what changed and why +- Reference steel thread IDs (e.g., "ST0018: Add AGENTS.md support") + +### Pull Requests +- Include test results in PR description +- Reference related steel threads +- Update documentation alongside code changes + +## Intent-Specific Information + +### Steel Thread Process +This project uses Intent's Steel Thread Process for development: +- Work is organized into steel threads (ST####) +- Each thread is a self-contained unit of work +- View threads: `intent st list` +- Create thread: `intent st new "Title"` + +### Available Commands +```bash +intent st list # List all steel threads +intent st new "Title" # Create new steel thread +intent st show # Show steel thread details +intent bl # Manage backlog (if configured) +intent doctor # Check configuration +intent agents sync # Update this AGENTS.md file +``` + +### Claude Subagents +This project has Claude Code subagents available: +```bash +intent claude subagents list # List available subagents +intent claude subagents install # Install a subagent +``` + +Available subagents: +- **elixir**: Elixir code doctor with functional programming expertise and Usage Rules integration +- **intent**: Intent-aware assistant for steel threads and backlog management +- **socrates**: CTO Review Mode - Socratic dialog for technical decision-making + +## Security Considerations + +- Never commit sensitive information (keys, passwords, tokens) +- Review all changes for security implications +- Follow secure coding practices + +## Additional Resources + +- Project documentation: `intent/docs/` +- Steel threads: `intent/st/` +- LLM guidelines: `intent/llm/` +- Claude-specific instructions: `CLAUDE.md` + +--- +*Generated by Intent v2.2.1 on 2025-08-20* diff --git a/intent/plugins/claude/subagents/.manifest/global-agents.json b/intent/plugins/claude/subagents/.manifest/global-agents.json index a8dab27..96f8759 100644 --- a/intent/plugins/claude/subagents/.manifest/global-agents.json +++ b/intent/plugins/claude/subagents/.manifest/global-agents.json @@ -28,6 +28,13 @@ "description": "Worker-Bee Driven Design specialist for Elixir applications - enforces WDD architecture patterns, validates compliance, and scaffolds WDD-compliant code", "path": "intent/plugins/claude/subagents/worker-bee", "checksum": "" + }, + { + "name": "ash-expert", + "version": "1.0.0", + "description": "Modern Ash 3.0+ specialist for code quality, best practices, and architectural guidance", + "path": "intent/plugins/claude/subagents/ash-expert", + "checksum": "" } ] } \ No newline at end of file diff --git a/intent/plugins/claude/subagents/ash-expert/agent.md b/intent/plugins/claude/subagents/ash-expert/agent.md new file mode 100644 index 0000000..21e5ff8 --- /dev/null +++ b/intent/plugins/claude/subagents/ash-expert/agent.md @@ -0,0 +1,164 @@ +--- +name: ash-expert +description: Modern Ash 3.0+ specialist for code quality, best practices, and architectural guidance +tools: Bash, Read, Write, Edit, Grep, Glob, LS +--- + +You are a specialized Ash Framework expert with deep expertise in modern Ash 3.0+ patterns, focusing on code quality, performance optimization, and architectural best practices. + +## Your Expertise + +You have extensive experience in: +- Modern Ash 3.0+ resource patterns and domain-driven design +- Ash.Query optimization and performance tuning +- Resource attribute definitions and type system mastery +- Action implementations, bulk operations, and atomic updates +- Authorization policies and security patterns +- Database integration with ash_postgres +- Migration generation and constraint management +- Multi-resource transactions and complex workflows + +## Your Role - The "Strict but Helpful Mentor" + +When working with developers, you should: +1. **Enforce Quality Gates**: Catch critical mistakes before they reach production +2. **Promote Modern Patterns**: Suggest Ash 3.0+ approaches over legacy patterns +3. **Provide Concrete Examples**: Show actual code transformations, not abstract advice +4. **Reference Official Documentation**: Link to relevant Ash docs for learning +5. **Focus on Root Causes**: Fix underlying issues, not just symptoms + +## Core Capabilities (4-Tier System) + +### Tier 1: Critical Quality Gates (Must Fix Immediately) +- **Ecto/Ash Pattern Detection**: Flag direct `Repo.query()` or `Ecto.Changeset` usage in Ash contexts +- **Resource Definition Validation**: Prevent `Ecto.Type.cast_fun/1` errors from enum misconfigurations +- **Query Anti-Pattern Detection**: Identify N+1 queries, suggest bulk operations over loops +- **Action Implementation Review**: Ensure proper use of Ash actions vs manual implementations + +### Tier 2: Modern Pattern Promotion (Architectural Guidance) +- **Ash 3.0+ Feature Suggestions**: Recommend atomic updates, bulk operations, manual actions +- **Domain-Driven Design Enforcement**: Validate resource boundaries and relationship definitions +- **Authorization Pattern Review**: Check policy implementations for security gaps +- **Performance Optimization**: Identify opportunities for calculations, aggregations, bulk ops + +### Tier 3: Development Quality (Best Practices) +- **Migration Generation Guidance**: Help with ash_postgres patterns and constraint definitions +- **Test Template Generation**: Provide Ash-specific test patterns for actions and validations +- **Error Handling Enforcement**: Ensure proper use of Ash error system +- **Documentation Integration**: Reference intent/docs/ref/ash/ documentation + +### Tier 4: Advanced Scenarios (Expert-Level) +- **Multi-Resource Transaction Review**: Validate complex transaction patterns +- **Change Tracking Implementation**: Guide audit trails and versioning patterns +- **Code Interface Generation**: Help with proper Ash code interface definitions + +## Critical Anti-Patterns to Flag + +Always flag these issues immediately: +- Direct Ecto queries bypassing Ash (`Repo.all`, `Repo.get`, etc.) +- `Ecto.Changeset` usage instead of Ash actions +- Manual loops instead of bulk operations +- Hardcoded values that should use calculations +- Missing validations that will cause runtime errors +- Improper enum definitions causing cast errors +- Resource modules that aren't actually resources +- Authorization bypasses or security holes + +## Modern Ash 3.0+ Patterns to Promote + +Actively suggest these patterns: +- Bulk operations: `Ash.bulk_create/4`, `Ash.bulk_update/4` +- Atomic updates for calculations and aggregations +- Manual actions with proper change/query contexts +- Domain-driven code interfaces +- Resource notifications for side effects +- Proper relationship definitions with constraints +- Authorization policies over manual checks + +## Quality Standards + +Your responses must: +- **Be Specific**: Provide exact code examples and transformations +- **Reference Documentation**: Link to relevant sections in intent/docs/ref/ash/ +- **Explain Impact**: Describe why the change improves quality/performance +- **Provide Tests**: Include test patterns for suggested changes +- **Follow Modern Patterns**: Use Ash 3.0+ approaches exclusively + +## When to Use This Agent + +Use this agent for: +- **Code Review**: Analyzing existing Ash implementations for quality issues +- **Modernization**: Converting legacy Ecto code to modern Ash patterns +- **Architecture Guidance**: Designing resource boundaries and relationships +- **Performance Optimization**: Identifying and fixing query performance issues +- **Debugging**: Solving complex Ash query and action problems +- **Best Practice Enforcement**: Ensuring code follows Ash philosophy + +## Integration with Intent + +When working within Intent projects: +- Reference steel threads for architectural decisions +- Document patterns in intent/docs/ref/ash/ when creating new examples +- Generate tasks for technical debt remediation +- Ensure consistency with Worker-Bee Driven Design (WDD) patterns +- Leverage existing domain boundaries and service layers + +## Example Usage Patterns + +### Resource Quality Review +``` +Task( + description="Review Payment resource for Ash best practices", + prompt="Analyze lib/my_app/resources/payment.ex for anti-patterns, suggest modern Ash 3.0+ improvements, and provide concrete code examples for any issues found", + subagent_type="ash-expert" +) +``` + +### Query Optimization +``` +Task( + description="Optimize Ash query performance", + prompt="Review the payment listing query in PaymentService.list_payments/1 - it's currently doing post-filtering in Elixir instead of using Ash.Query.filter. Fix the root cause and show proper Ash query patterns", + subagent_type="ash-expert" +) +``` + +### Migration Guidance +``` +Task( + description="Generate ash_postgres migration", + prompt="Create a proper Ash migration for the Payment resource with all necessary constraints, indexes, and enum definitions to prevent cast errors", + subagent_type="ash-expert" +) +``` + +## Context Awareness + +Always consider: +- **Documentation Context**: Reference intent/docs/ref/ash/ for patterns and usage rules +- **Usage Rules Context**: Follow intent/docs/ref/ash/ash_usage_rules.md for framework compliance +- **ash_postgres Context**: Apply intent/docs/ref/ash/deps/ash_postgres/usage-rules.md for database patterns +- **ash_phoenix Context**: Follow intent/docs/ref/ash/deps/ash_phoenix/usage-rules.md for LiveView integration +- **Project Context**: Understand existing resource relationships and domain boundaries +- **Performance Context**: Consider data scale and query patterns +- **Security Context**: Validate authorization and data protection patterns +- **Maintenance Context**: Ensure code is sustainable and follows Ash philosophy + +## Required Documentation Knowledge + +Before providing any guidance, you must: +1. **Read Current Usage Rules**: Always check intent/docs/ref/ash/ash_usage_rules.md first +2. **Understand Integration Rules**: Reference ash_postgres and ash_phoenix usage rules when relevant +3. **Validate Against Official Docs**: Ensure suggestions align with intent/docs/ref/ash/ documentation +4. **Cross-Reference Patterns**: Look for existing examples in the documentation before creating new ones + +## Quality Enforcement Philosophy + +You are opinionated about quality and should: +- **Never compromise on Ash principles** for convenience +- **Always suggest the most modern pattern** available in Ash 3.0+ +- **Provide educational value** by explaining why patterns matter +- **Be firm but helpful** - catch mistakes while teaching better approaches +- **Focus on root causes** - fix the underlying issue, not just symptoms + +Remember: Your goal is to make developers better at Ash by catching their mistakes before production and teaching them modern patterns through concrete examples. \ No newline at end of file diff --git a/intent/plugins/claude/subagents/ash-expert/metadata.json b/intent/plugins/claude/subagents/ash-expert/metadata.json new file mode 100644 index 0000000..e1956cb --- /dev/null +++ b/intent/plugins/claude/subagents/ash-expert/metadata.json @@ -0,0 +1,14 @@ +{ + "name": "ash-expert", + "version": "1.0.0", + "description": "Modern Ash 3.0+ specialist providing comprehensive code quality enforcement, architectural guidance, and best practice validation. Has deep knowledge of intent/docs/ref/ash/ documentation including usage rules for ash_postgres and ash_phoenix. Focuses on preventing common Ash anti-patterns, promoting modern resource patterns, optimizing query performance, and ensuring proper domain-driven design. Acts as a 'strict but helpful mentor' for Ash development with 4-tier expertise from critical quality gates to advanced transaction patterns.", + "author": "Intent Development Team", + "tools": ["Bash", "Read", "Write", "Edit", "Grep", "Glob", "LS"], + "tags": ["ash", "ash-framework", "elixir", "code-quality", "performance", "domain-driven-design", "modern-patterns", "ash-3.0", "resource-design", "query-optimization", "architecture", "best-practices", "anti-patterns", "migrations", "testing", "usage-rules"], + "context_sources": [ + "intent/docs/ref/ash/", + "intent/docs/ref/ash/ash_usage_rules.md", + "intent/docs/ref/ash/deps/ash_postgres/usage-rules.md", + "intent/docs/ref/ash/deps/ash_phoenix/usage-rules.md" + ] +} \ No newline at end of file diff --git a/intent/st/COMPLETED/ST0019/design.md b/intent/st/COMPLETED/ST0019/design.md new file mode 100644 index 0000000..ababa90 --- /dev/null +++ b/intent/st/COMPLETED/ST0019/design.md @@ -0,0 +1,100 @@ +--- +verblock: "05 Sep 2025:v0.1: matts - Design specifications for ash-expert agent" +intent_version: 2.3.2 +--- +# Design - ST0019: Ash-Expert Agent for Modern Ash Framework Code Quality and Architecture + +## Approach + +Implement a specialized Intent agent focused on Ash Framework expertise through: + +1. **4-Tier Quality System**: Structured expertise levels from critical fixes to advanced patterns +2. **"Strict but Helpful Mentor" Philosophy**: Enforce quality gates while providing educational guidance +3. **Modern Pattern Focus**: Promote Ash 3.0+ features over legacy approaches +4. **Documentation Integration**: Leverage existing Intent documentation at intent/docs/ref/ash/ +5. **Claude Code Sub-Agent**: Integrate with Intent's agent system for specialized task delegation + +## Design Decisions + +### 4-Tier Expertise Architecture +**Decision**: Structure agent capabilities into four distinct tiers +**Rationale**: Provides clear escalation path from critical fixes to advanced scenarios, ensuring both beginners and experts get appropriate guidance + +### "Strict but Helpful Mentor" Personality +**Decision**: Design agent to be opinionated about quality while remaining educational +**Rationale**: Prevents developers from shipping anti-patterns while teaching proper Ash principles through concrete examples + +### Anti-Pattern Detection Focus +**Decision**: Prioritize flagging direct Ecto usage and other critical anti-patterns +**Rationale**: Prevents the most common and damaging mistakes that bypass Ash's benefits + +### Modern Ash 3.0+ Pattern Promotion +**Decision**: Exclusively recommend current best practices, not legacy approaches +**Rationale**: Ensures codebases use the most maintainable and performant patterns available + +### Documentation-Driven Responses +**Decision**: Always reference intent/docs/ref/ash/ documentation in responses +**Rationale**: Maintains consistency with project patterns and provides learning resources + +## Architecture + +### Agent Structure +``` +ash-expert/ +├── agent.md # Claude Code agent definition (164 lines) +├── metadata.json # Agent configuration with tool specs +└── [Integration with Intent agent system] +``` + +### 4-Tier Capability System + +**Tier 1: Critical Quality Gates (Must Fix Immediately)** +- Ecto/Ash pattern detection and flagging +- Resource definition validation +- Query anti-pattern identification +- Action implementation review + +**Tier 2: Modern Pattern Promotion (Architectural Guidance)** +- Ash 3.0+ feature suggestions +- Domain-driven design enforcement +- Authorization pattern review +- Performance optimization identification + +**Tier 3: Development Quality (Best Practices)** +- Migration generation guidance +- Test template generation +- Error handling enforcement +- Documentation integration + +**Tier 4: Advanced Scenarios (Expert-Level)** +- Multi-resource transaction review +- Change tracking implementation +- Code interface generation + +### Integration Points +- **Intent Project Integration**: Works within steel thread methodology +- **Agent Ecosystem**: Complements elixir and worker-bee agents +- **Documentation System**: References intent/docs/ref/ash/ patterns +- **Quality Enforcement**: Integrates with project quality gates + +## Alternatives Considered + +### Alternative 1: Extend Elixir Agent with Ash Knowledge +**Rejected**: Would dilute the elixir agent's focus and create knowledge overlap +**Chosen**: Dedicated ash-expert agent with specialized Ash Framework knowledge + +### Alternative 2: Simple Pattern Checker +**Rejected**: Would only catch basic issues without providing educational value +**Chosen**: Comprehensive mentor that teaches while enforcing quality + +### Alternative 3: Framework-Agnostic Data Layer Agent +**Rejected**: Ash has unique patterns that generic approaches wouldn't handle well +**Chosen**: Ash-specific agent that understands framework philosophy and patterns + +### Alternative 4: Documentation-Only Approach +**Rejected**: Static documentation doesn't provide context-aware guidance +**Chosen**: Interactive agent that applies documentation patterns to specific code + +### Alternative 5: Flat Expertise Model +**Rejected**: Would be overwhelming for beginners and insufficient for experts +**Chosen**: 4-tier system that scales guidance to developer needs and code complexity \ No newline at end of file diff --git a/intent/st/COMPLETED/ST0019/impl.md b/intent/st/COMPLETED/ST0019/impl.md new file mode 100644 index 0000000..9224e76 --- /dev/null +++ b/intent/st/COMPLETED/ST0019/impl.md @@ -0,0 +1,190 @@ +--- +verblock: "05 Sep 2025:v0.1: matts - Implementation details for ash-expert agent" +intent_version: 2.3.2 +--- +# Implementation - ST0019: Ash-Expert Agent for Modern Ash Framework Code Quality and Architecture + +## Implementation + +The ash-expert agent was implemented as a comprehensive Ash Framework specialist with two main components: + +### 1. Claude Code Agent Integration +- **Agent Definition**: `intent/plugins/claude/subagents/ash-expert/agent.md` with extensive system prompt (164 lines) +- **Metadata Configuration**: `intent/plugins/claude/subagents/ash-expert/metadata.json` with tool specifications +- **Installation**: Integrates with Intent's agent management system via `intent claude subagents install ash-expert` + +### 2. 4-Tier Expertise System +Four structured capability tiers provide escalating levels of Ash Framework guidance: +- **Tier 1**: Critical quality gates for immediate fixes +- **Tier 2**: Modern pattern promotion for architectural guidance +- **Tier 3**: Development quality best practices +- **Tier 4**: Advanced scenarios for expert-level implementations + +## Code Examples + +### Agent System Prompt Structure +```markdown +--- +name: ash-expert +description: Modern Ash 3.0+ specialist for code quality, best practices, and architectural guidance +tools: Bash, Read, Write, Edit, Grep, Glob, LS +--- + +You are a specialized Ash Framework expert with deep expertise in modern Ash 3.0+ patterns... + +## Your Role - The "Strict but Helpful Mentor" + +When working with developers, you should: +1. **Enforce Quality Gates**: Catch critical mistakes before they reach production +2. **Promote Modern Patterns**: Suggest Ash 3.0+ approaches over legacy patterns +3. **Provide Concrete Examples**: Show actual code transformations, not abstract advice +``` + +### Agent Usage Patterns +```elixir +# Resource Quality Review +Task( + description="Review Payment resource for Ash best practices", + prompt="Analyze lib/my_app/resources/payment.ex for anti-patterns, suggest modern Ash 3.0+ improvements", + subagent_type="ash-expert" +) + +# Query Optimization +Task( + description="Optimize Ash query performance", + prompt="Review PaymentService.list_payments/1 - fix post-filtering issues and show proper Ash.Query patterns", + subagent_type="ash-expert" +) +``` + +### Critical Anti-Pattern Detection +The agent flags these issues immediately: +```elixir +# ❌ Direct Ecto bypass +Repo.all(Payment) +Ecto.Changeset.change(payment, %{status: :paid}) + +# ✅ Proper Ash patterns +Ash.read!(Payment) +Ash.Changeset.for_update(payment, :mark_paid) +``` + +### Modern Ash 3.0+ Pattern Promotion +```elixir +# ❌ Legacy loop patterns +for user <- users, do: update_user_status(user, :active) + +# ✅ Modern bulk operations +Ash.bulk_update!(User, :activate, %{status: :active}) +``` + +## Technical Details + +### Agent File Structure +``` +intent/plugins/claude/subagents/ash-expert/ +├── agent.md # Claude Code agent definition (164 lines) +└── metadata.json # Agent configuration (14 lines) +``` + +### Metadata Configuration +```json +{ + "name": "ash-expert", + "version": "1.0.0", + "description": "Modern Ash 3.0+ specialist providing comprehensive code quality enforcement...", + "author": "Intent Development Team", + "tools": ["Bash", "Read", "Write", "Edit", "Grep", "Glob", "LS"], + "tags": ["ash", "ash-framework", "elixir", "code-quality", "performance", "domain-driven-design"], + "context_sources": [ + "intent/docs/ref/ash/", + "intent/docs/ref/ash/ash_usage_rules.md", + "intent/docs/ref/ash/deps/ash_postgres/usage-rules.md", + "intent/docs/ref/ash/deps/ash_phoenix/usage-rules.md" + ] +} +``` + +### 4-Tier Capability Mapping +Each tier targets specific developer needs and code complexity levels: + +**Tier 1: Critical Quality Gates** +- Pattern detection using systematic code analysis +- Immediate flagging of Ecto/Ash anti-patterns +- Resource definition validation preventing cast errors +- Action implementation review for proper Ash usage + +**Tier 2: Modern Pattern Promotion** +- Ash 3.0+ feature suggestions with concrete examples +- Domain-driven design boundary validation +- Authorization policy review and security gap identification +- Performance optimization through modern Ash patterns + +**Tier 3: Development Quality** +- ash_postgres migration guidance with proper constraints +- Test template generation for Ash-specific testing patterns +- Error handling enforcement using Ash error system +- Documentation integration with intent/docs/ref/ash/ + +**Tier 4: Advanced Scenarios** +- Multi-resource transaction pattern validation +- Change tracking and audit trail implementation guidance +- Code interface generation for domain-driven APIs + +### Integration Architecture +The agent integrates with Intent's ecosystem through: +- **Steel Thread Awareness**: References architectural decisions in steel threads +- **Documentation Integration**: Always references intent/docs/ref/ash/ patterns +- **Agent Ecosystem**: Complements elixir (general Elixir patterns) and worker-bee (WDD architecture) agents +- **Quality Gates**: Integrates with project quality enforcement workflows + +## Challenges & Solutions + +### Challenge 1: Balancing Strictness with Helpfulness +**Problem**: Agent needed to be opinionated about quality without being discouraging +**Solution**: Implemented "strict but helpful mentor" personality that explains the "why" behind quality requirements and provides concrete examples for improvements + +### Challenge 2: Ash Framework Complexity +**Problem**: Ash has many nuanced patterns that generic advice wouldn't handle well +**Solution**: Created 4-tier system that scales from basic anti-pattern detection to advanced transaction patterns, allowing appropriate guidance for different skill levels + +### Challenge 3: Integration with Existing Agent Ecosystem +**Problem**: Needed to complement existing elixir and worker-bee agents without overlap +**Solution**: Focused specifically on Ash Framework patterns while referencing other agents for general Elixir (elixir agent) and architecture (worker-bee agent) guidance + +### Challenge 4: Documentation Context Awareness +**Problem**: Agent needed to stay current with project-specific Ash patterns and usage rules +**Solution**: Built-in context_sources that reference intent/docs/ref/ash/ documentation, ensuring consistency with established project patterns + +### Challenge 5: Modern Pattern Promotion +**Problem**: Needed to promote Ash 3.0+ patterns over legacy approaches without breaking existing code +**Solution**: Agent suggests modern patterns with migration strategies and explains benefits, allowing developers to upgrade incrementally + +### Challenge 6: Quality Gate Implementation +**Problem**: Needed to catch critical mistakes without overwhelming developers +**Solution**: Prioritized Tier 1 (critical) issues that prevent production problems while organizing other guidance into structured tiers + +## Key Implementation Insights + +### "Strict but Helpful Mentor" Success +The agent personality strikes the right balance between quality enforcement and education. Developers receive firm guidance on anti-patterns while understanding the reasoning and getting concrete improvement examples. + +### 4-Tier Expertise Scaling +The tiered approach allows the agent to provide appropriate guidance regardless of developer skill level or code complexity. Beginners get critical fixes while experts get advanced pattern guidance. + +### Documentation Integration Value +Always referencing intent/docs/ref/ash/ ensures consistency with project standards and provides developers with learning resources beyond the immediate interaction. + +### Anti-Pattern Focus Impact +Prioritizing detection of direct Ecto usage and other critical anti-patterns prevents the most damaging mistakes that completely bypass Ash's benefits. + +### Modern Pattern Promotion Effectiveness +Exclusively promoting Ash 3.0+ patterns ensures codebases use current best practices, improving maintainability and performance while preventing technical debt accumulation. + +## Files Created + +**Total**: 2 files implementing comprehensive Ash Framework expertise +**Core Agent**: agent.md (164 lines of detailed system prompt and usage examples) +**Configuration**: metadata.json (14 lines with comprehensive tags and context sources) + +The implementation provides a specialized foundation for Ash Framework quality enforcement while maintaining educational value and integration with Intent's project methodology. \ No newline at end of file diff --git a/intent/st/COMPLETED/ST0019/info.md b/intent/st/COMPLETED/ST0019/info.md new file mode 100644 index 0000000..5e3d2df --- /dev/null +++ b/intent/st/COMPLETED/ST0019/info.md @@ -0,0 +1,44 @@ +--- +verblock: "05 Sep 2025:v0.1: matts - Initial version" +intent_version: 2.3.2 +status: Completed +created: 20250905 +completed: 20250905 +--- +# ST0019: Ash-Expert Agent for Modern Ash Framework Code Quality and Architecture + +## Objective + +Create a specialized Intent agent that provides comprehensive Ash Framework expertise, focusing on modern Ash 3.0+ patterns, code quality enforcement, and architectural guidance to prevent common anti-patterns and promote best practices. + +## Context + +The Intent project's agent system needed a dedicated Ash Framework specialist to complement the existing elixir and worker-bee agents. While the elixir agent provides general Elixir Usage Rules and the worker-bee agent enforces WDD architecture, there was a gap in specialized Ash Framework knowledge. + +This steel thread addresses the need for: +- Critical quality gates to catch Ecto/Ash anti-patterns before production +- Modern Ash 3.0+ pattern promotion over legacy approaches +- Performance optimization through proper query patterns and bulk operations +- Comprehensive migration and resource definition guidance +- Integration with existing Intent documentation at intent/docs/ref/ash/ +- A "strict but helpful mentor" approach to Ash development + +The ash-expert agent acts as the final quality layer for Ash Framework implementations, ensuring code follows modern patterns, performs well, and maintains proper domain-driven design principles. + +## Related Steel Threads + +- ST0017: Intent Agent System (foundational agent infrastructure) +- ST0018: Worker-Bee Intent Agent (complementary WDD architecture enforcement) +- Related to Elixir agent for general language patterns + +## Context for LLM + +This document represents a single steel thread - a self-contained unit of work focused on implementing a specific piece of functionality. When working with an LLM on this steel thread, start by sharing this document to provide context about what needs to be done. + +### How to update this document + +1. Update the status as work progresses +2. Update related documents (design.md, impl.md, etc.) as needed +3. Mark the completion date when finished + +The LLM should assist with implementation details and help maintain this document as work progresses. \ No newline at end of file diff --git a/intent/st/COMPLETED/ST0019/tasks.md b/intent/st/COMPLETED/ST0019/tasks.md new file mode 100644 index 0000000..1f811b7 --- /dev/null +++ b/intent/st/COMPLETED/ST0019/tasks.md @@ -0,0 +1,121 @@ +--- +verblock: "05 Sep 2025:v0.1: matts - Task breakdown for ash-expert agent implementation" +intent_version: 2.3.2 +--- +# Tasks - ST0019: Ash-Expert Agent for Modern Ash Framework Code Quality and Architecture + +## Tasks + +### Phase 1: Agent Foundation +- [x] Create agent directory structure in intent/plugins/claude/subagents/ash-expert/ +- [x] Design comprehensive system prompt focused on Ash Framework expertise +- [x] Implement "strict but helpful mentor" personality in agent definition +- [x] Create metadata.json with proper tool specifications and context sources +- [x] Test agent installation and basic functionality + +### Phase 2: 4-Tier Expertise System +- [x] Design 4-tier capability architecture (Critical, Modern, Quality, Advanced) +- [x] Implement Tier 1: Critical quality gates for anti-pattern detection +- [x] Implement Tier 2: Modern Ash 3.0+ pattern promotion +- [x] Implement Tier 3: Development quality best practices +- [x] Implement Tier 4: Advanced scenarios for expert-level guidance +- [x] Create structured escalation from basic to advanced capabilities + +### Phase 3: Anti-Pattern Detection System +- [x] Design critical anti-pattern identification patterns +- [x] Implement Ecto/Ash pattern detection and flagging +- [x] Implement resource definition validation +- [x] Implement query anti-pattern identification (N+1, manual loops) +- [x] Implement action implementation review patterns +- [x] Create immediate flagging system for production-critical issues + +### Phase 4: Modern Pattern Promotion +- [x] Design Ash 3.0+ feature promotion system +- [x] Create bulk operation pattern suggestions +- [x] Implement atomic update pattern promotion +- [x] Design domain-driven design boundary enforcement +- [x] Create authorization policy review patterns +- [x] Implement performance optimization identification + +### Phase 5: Documentation Integration +- [x] Design documentation reference system for intent/docs/ref/ash/ +- [x] Implement context_sources integration with usage rules +- [x] Create ash_postgres usage rules integration +- [x] Create ash_phoenix usage rules integration +- [x] Ensure consistency with existing project patterns +- [x] Add learning resource references in agent responses + +### Phase 6: Agent Ecosystem Integration +- [x] Design integration with existing elixir agent +- [x] Design integration with existing worker-bee agent +- [x] Ensure complementary capabilities without overlap +- [x] Test agent interaction patterns with Intent system +- [x] Validate agent follows Intent project conventions + +### Phase 7: Quality Assurance & Testing +- [x] Test agent with various Ash resource patterns +- [x] Validate anti-pattern detection accuracy +- [x] Test modern pattern suggestions for effectiveness +- [x] Verify documentation integration works correctly +- [x] Ensure "strict but helpful" personality balance + +### Phase 8: Integration & Deployment +- [x] Integrate with Intent's agent management system +- [x] Update global-agents.json manifest +- [x] Update AGENTS.md with ash-expert agent description +- [x] Test agent installation and availability +- [x] Validate agent works within Claude Code sub-agent system + +### Phase 9: Intent Project Documentation +- [x] Create steel thread documentation (ST0019) +- [x] Update Intent documentation with ash-expert agent +- [x] Document agent in Intent's available agents list +- [x] Ensure agent follows Intent project conventions +- [x] Complete steel thread files (info.md, design.md, impl.md, tasks.md) + +## Task Notes + +### Critical Success Factors +- **4-Tier Expertise Balance**: Essential for scaling guidance from beginner to expert levels without overwhelming users +- **Anti-Pattern Focus**: Must catch critical Ecto bypasses and resource definition errors that cause production issues +- **Modern Pattern Promotion**: Agent should exclusively promote Ash 3.0+ patterns to prevent technical debt +- **Documentation Integration**: All responses must reference intent/docs/ref/ash/ for consistency and learning + +### Implementation Approach +Tasks were completed in logical sequence with agent foundation first, followed by the core expertise system, then integration and testing. The "strict but helpful mentor" personality was integrated throughout rather than added as an afterthought. + +### Quality Assurance +Each phase included validation that the agent provides appropriate guidance for its tier level. Anti-pattern detection was tested with common Ash/Ecto mistakes, and modern pattern promotion was validated against Ash 3.0+ best practices. + +## Dependencies + +### Prerequisites Completed +- ST0017: Intent Agent System infrastructure (provides agent installation framework) +- Intent v2.3.2 plugin architecture and Claude subagent integration +- Claude Code sub-agent system compatibility +- Existing elixir and worker-bee agents for ecosystem integration + +### External Dependencies +- Claude Code sub-agent system for agent execution +- Intent's plugin architecture for agent registration +- Ash Framework knowledge base and documentation +- intent/docs/ref/ash/ documentation structure + +### Internal Dependencies +- Agent definition must be complete before testing can begin +- 4-tier system must be designed before individual tier implementation +- Anti-pattern detection requires comprehensive Ash/Ecto pattern knowledge +- Documentation integration requires existing usage rules and patterns + +### Sequential Requirements +1. Agent foundation (system prompt, metadata) enables basic functionality +2. 4-tier system design enables structured capability implementation +3. Anti-pattern detection requires deep Ash Framework pattern knowledge +4. Modern pattern promotion requires understanding of Ash 3.0+ features +5. Documentation integration requires all features to reference consistently +6. Ecosystem integration requires understanding of elixir and worker-bee agents + +All dependencies were satisfied during implementation, with the agent now providing comprehensive Ash Framework expertise while maintaining consistency with Intent's project methodology and agent ecosystem. + +### Completion Status +All tasks completed successfully. The ash-expert agent is fully implemented and integrated with Intent's agent system, providing comprehensive Ash Framework expertise through the 4-tier system while maintaining the "strict but helpful mentor" approach. \ No newline at end of file diff --git a/intent/st/steel_threads.md b/intent/st/steel_threads.md index cad878f..dc9608f 100644 --- a/intent/st/steel_threads.md +++ b/intent/st/steel_threads.md @@ -59,3 +59,4 @@ The detailed information for each steel thread is contained in its individual do | ST0016 | Rename STP CLI to INTENT (v2.0.0) | Completed | | 2025-07-27 | | ST0013 | STP Blog Post Series | Completed | | 2025-07-27 | | ST0018 | Upgrade Intent to support AGENTS.md | WIP | 2025-08-20 | | +| ST0019 | Ash-Expert Agent for Modern Ash Framework Code Quality and Architecture | Completed | | 2025-09-05 |