ai-eng-system 0.0.1

package/dist/.opencode/command/ai-eng/plan.md

@@ -0,0 +1,215 @@
+---
+name: ai-eng/plan
+description: Create a detailed implementation plan for a feature
+agent: plan
+---
+
+# Plan Command
+
+Create a structured, atomic implementation plan for: $ARGUMENTS
+
+## Usage
+
+```bash
+/ai-eng/plan [description] [options]
+```
+
+### Options
+
+- `--swarm`: Use Swarms multi-agent orchestration instead of legacy coordinator
+- `-s, --scope <scope>`: Plan scope (architecture|implementation|review|full) [default: full]
+- `-r, --requirements <reqs...>`: List of specific requirements
+- `-c, --constraints <constraints...>`: List of constraints to consider
+- `-o, --output <file>`: Output plan file [default: generated-plan.yaml]
+- `-v, --verbose`: Enable verbose output
+
+## Planning Philosophy
+
+**Atomic Plans**: Every plan should be decomposed into small, independently completable chunks that:
+- Can be implemented in a single focused session (15-60 minutes)
+- Have clear start and end states
+- Are testable in isolation
+- Don't require context from unfinished sibling tasks
+
+## Process
+
+### Phase 1: Discovery (Research Mode)
+
+#### Subagent Communication Protocol (Minimal)
+
+If you delegate discovery to subagents (recommended for large codebases), include a small Context Handoff Envelope in each Task prompt.
+
+Use:
+
+```text
+<CONTEXT_HANDOFF_V1>
+Goal: (1 sentence)
+Constraints: (bullets)
+Files / folders to focus: (bullets)
+Deliverable: (what you must return)
+Output format: RESULT_V1
+</CONTEXT_HANDOFF_V1>
+```
+
+And require:
+
+```text
+<RESULT_V1>
+RESULT:
+EVIDENCE:
+RISKS:
+NEXT_STEPS:
+CONFIDENCE: 0.0-1.0
+</RESULT_V1>
+```
+
+1. **Codebase Analysis**
+   - Search for similar patterns and implementations
+   - Identify existing conventions and styles
+   - Map related files and dependencies
+   - Document findings with file paths and line numbers
+
+2. **Tech Stack Detection**
+   - Identify frameworks, libraries, and tools in use
+   - Check package.json/requirements/go.mod for dependencies
+   - Note version constraints and compatibility requirements
+
+3. **Scope Definition**
+   - List all files that will be modified
+   - List all new files to be created
+   - Identify integration points with existing code
+   - Flag potential breaking changes
+
+### Phase 2: Task Decomposition
+
+Break the feature into **atomic tasks** using this hierarchy:
+
+```
+Epic (the full feature)
+└── Phase (logical grouping, ~1 day)
+    └── Task (atomic unit, ~30 min)
+        └── Subtask (if task is still too large)
+```
+
+**Each atomic task MUST include:**
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| ID | Unique identifier | `FEAT-001-A` |
+| Title | Action-oriented name | "Create SessionManager class" |
+| Depends On | Blocking task IDs | `FEAT-001-B` (or "None") |
+| Files | Exact files to modify/create | `src/context/session.ts` |
+| Acceptance Criteria | Checkboxes that define "done" | `[ ] Class exports correctly` |
+| Estimated Time | Time box | `30 min` |
+| Complexity | Low / Medium / High | `Medium` |
+
+### Phase 3: Risk Assessment
+
+For each phase, identify:
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| (risk description) | High/Med/Low | High/Med/Low | (strategy) |
+
+### Phase 4: Testing Strategy
+
+Define testing approach for each phase:
+
+- **Unit Tests**: What functions/classes need tests?
+- **Integration Tests**: What interactions need verification?
+- **Manual Testing**: What scenarios to validate?
+- **Regression Checks**: What existing functionality could break?
+
+### Phase 5: SEO & Performance Considerations
+
+If applicable:
+- Core Web Vitals impact
+- Bundle size changes
+- API response times
+- Caching strategies
+
+## Output Format
+
+### File: `plans/[YYYY-MM-DD]-[feature-slug].md`
+
+```markdown
+# [Feature Name] Implementation Plan
+
+**Status**: Draft | In Progress | Complete
+**Created**: [date]
+**Estimated Effort**: [hours/days]
+**Complexity**: Low | Medium | High
+
+## Overview
+[2-3 sentence summary]
+
+## Success Criteria
+- [ ] [Measurable outcome 1]
+- [ ] [Measurable outcome 2]
+
+## Architecture
+[Diagram or description of component relationships]
+
+## Phase 1: [Phase Name]
+
+**Goal**: [What this phase accomplishes]
+**Duration**: [Estimated time]
+
+### Task 1.1: [Task Title]
+- **ID**: FEAT-001-A
+- **Depends On**: None
+- **Files**: 
+  - `path/to/file.ts` (modify)
+  - `path/to/new-file.ts` (create)
+- **Acceptance Criteria**:
+  - [ ] Criterion 1
+  - [ ] Criterion 2
+  - [ ] Tests pass
+- **Time**: 30 min
+- **Complexity**: Low
+
+### Task 1.2: [Task Title]
+[...]
+
+## Phase 2: [Phase Name]
+[...]
+
+## Dependencies
+- [External dependency 1]
+- [Internal dependency 1]
+
+## Risks
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+
+## Testing Plan
+### Unit Tests
+- [ ] Test for [component]
+
+### Integration Tests  
+- [ ] Test [interaction]
+
+## Rollback Plan
+[How to revert if something goes wrong]
+
+## References
+- [Link to relevant docs]
+- [Link to similar implementations]
+```
+
+## Post-Planning Actions
+
+After generating the plan:
+
+1. **Review with user** - Confirm scope and priorities
+2. **Create GitHub issue** (optional) - Link to plan file
+3. **Estimate total effort** - Sum of all task estimates
+4. **Identify parallel tracks** - Tasks without dependencies that can run concurrently
+
+## Tips for Effective Plans
+
+- **Timeboxing**: If a task exceeds 60 minutes, break it down further
+- **Dependencies**: Minimize cross-task dependencies to enable parallel work
+- **Checkpoints**: Each phase should end with a working (possibly incomplete) state
+- **Escape hatches**: Note where you could stop and still have value
+- **Evidence-based**: Include file paths and code snippets from discovery

package/dist/.opencode/command/ai-eng/recursive-init.md

@@ -0,0 +1,217 @@
+---
+name: ai-eng/recursive-init
+description: Recursively initialize AGENTS.md in all important subdirectories with smart detection
+agent: build
+---
+
+# Recursive Init Command
+
+## Expert Context
+
+You are a senior DevOps architect and codebase analyst with 12+ years of experience at companies like Vercel, Stripe, and Netflix. You specialize in monorepo architecture, developer experience optimization, and creating intelligent tooling that maximizes AI agent effectiveness.
+
+## Stakes
+
+This recursive initialization is critical. Each AGENTS.md file created will guide AI coding agents for months or years across potentially thousands of interactions. Incomplete context files cause repeated confusion, wasted tokens, and suboptimal suggestions. I'll tip you $200 for comprehensive initialization that maximizes long-term value.
+
+## Approach
+
+Take a deep breath. Execute this multi-phase operation systematically.
+
+---
+
+## Usage
+
+```
+/recursive-init [path] [options]
+```
+
+## Phase 1: File System Scan (No LLM Cost)
+
+First, gather intelligence before any analysis:
+
+```bash
+# Detect project types and score directories
+find . -maxdepth 3 -name "package.json" -o -name "go.mod" -o -name "Cargo.toml" -o -name "pyproject.toml" -o -name "pom.xml" 2>/dev/null | grep -v node_modules | head -30
+
+# Identify monorepo patterns
+ls -d */packages 2>/dev/null || ls -d */apps 2>/dev/null || ls -d */services 2>/dev/null || echo "No standard monorepo structure detected"
+```
+
+### Directory Scoring Heuristic
+
+| Indicator | Score |
+|-----------|-------|
+| package.json, go.mod, Cargo.toml, pyproject.toml, pom.xml | +10 |
+| src/, lib/, components/ directory | +5 |
+| .cursorrules, .github/copilot-instructions.md | +3 |
+| >10 source files (.ts, .js, .py, .go, .rs) | +3 |
+| README.md or docs/ present | +2 |
+
+Only analyze directories scoring > 5 (configurable via --min-score).
+
+## Phase 2: Systematic Execution
+
+### Step 1: Root Analysis
+Run standard init at project root. Create comprehensive overview AGENTS.md.
+
+### Step 2: Directory Discovery  
+Scan and score all subdirectories. Report findings before proceeding.
+
+### Step 3: Batch Processing
+Process directories in groups of 3. For EACH directory:
+1. cd into the directory
+2. Analyze local code structure, framework, and patterns
+3. Create localized AGENTS.md (~20 lines) containing:
+   - **Hierarchy Metadata** (new requirement per Anthropic docs):
+     - `**Hierarchy Level:**` — Role in system (e.g., "Frontend components", "API services", "Build utilities")
+     - `**Parent:**` — Link to parent AGENTS.md with path (e.g., `[../AGENTS.md](../AGENTS.md)`)
+     - `**Philosophy:**` — Link to CLAUDE.md (e.g., `[CLAUDE.md](../../CLAUDE.md)`)
+   - Build/lint/test commands (especially single test execution)
+   - Code style guidelines (imports, formatting, types, naming)
+   - Framework-specific patterns and conventions
+   - Integration points with other packages
+4. Include existing .cursorrules or .github/copilot-instructions.md content
+
+### Step 4: Context Linking in AGENTS.md
+Update root AGENTS.md with:
+1. **Directory Context Index** — Table with links to all created AGENTS.md files
+2. **Hierarchy Reference** — Explain the linking structure to CLAUDE.md
+3. **Integration Summary** — How subdirectories connect to parent agents and philosophy
+
+Example section:
+```markdown
+## Directory Context Index
+
+| Directory | Hierarchy Level | Purpose | Key Files |
+|-----------|-----------------|---------|-----------|
+| `packages/api` | API Services | REST API backend | `src/routes/`, `src/models/` |
+| `packages/web` | Frontend Components | React UI | `src/components/`, `src/pages/` |
+
+Each subdirectory's AGENTS.md includes hierarchy metadata linking to:
+- **Parent:** This AGENTS.md for agent coordination
+- **Philosophy:** CLAUDE.md for project guiding principles
+```
+
+### Step 5: Update/Create Root CLAUDE.md
+Ensure root CLAUDE.md is properly linked to AGENTS.md structure:
+
+1. **If CLAUDE.md exists:** Add or update an "Agent Contexts" section listing all AGENTS.md files
+2. **If CLAUDE.md doesn't exist:** Create a new CLAUDE.md with:
+   - Project philosophy and guidelines
+   - "Agent Coordination" section linking to root AGENTS.md
+   - "Agent Contexts" section listing subdirectory AGENTS.md files
+
+Example CLAUDE.md structure:
+```markdown
+# Project Philosophy
+
+[Project mission and guiding principles...]
+
+## Agent Coordination
+
+See **[AGENTS.md](./AGENTS.md)** for:
+- Available agents and their modes
+- Specialized subagents and capabilities
+- Commands and skills available
+
+This CLAUDE.md defines the **philosophy**. AGENTS.md documents the **agents and tools**.
+
+## Agent Contexts
+
+Specialized agent contexts are defined in subdirectories:
+
+| Directory | AGENTS.md | Purpose |
+|-----------|-----------|---------|
+| `.claude/` | [.claude/AGENTS.md](./.claude/AGENTS.md) | Command implementation details |
+| `skills/` | [skills/AGENTS.md](./skills/AGENTS.md) | Reusable skill definitions |
+| `packages/api` | [packages/api/AGENTS.md](./packages/api/AGENTS.md) | API services context |
+| `packages/web` | [packages/web/AGENTS.md](./packages/web/AGENTS.md) | Frontend context |
+
+Each subdirectory maintains its own AGENTS.md with hierarchy metadata linking back to this CLAUDE.md philosophy.
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--depth N` | Maximum recursion depth | 2 |
+| `--dry-run` | Preview without changes | false |
+| `--preserve` | Keep existing AGENTS.md | false |
+| `--batch-size N` | Directories per batch | 3 |
+| `--min-score N` | Minimum importance score | 5 |
+| `--include <pattern>` | Additional patterns to include | - |
+| `--exclude <pattern>` | Patterns to skip | node_modules,.git,dist |
+| `--estimate-cost` | Show cost estimate first | false |
+
+## Skip Patterns
+
+node_modules, .git, dist, build, __pycache__, .venv, target, coverage, .next, .nuxt
+
+## Output Format
+
+```
+🔍 Scanning directory structure...
+📊 Found X directories above threshold (score > 5)
+
+📁 Root (/)
+   ✓ AGENTS.md created (monorepo overview, 8 packages detected)
+
+📦 Batch 1/N: [packages/api, packages/web, packages/shared]
+   ✓ packages/api: AGENTS.md (Express REST API, TypeScript, Prisma)
+   ✓ packages/web: AGENTS.md (Next.js 14, App Router, Tailwind)
+   ✓ packages/shared: AGENTS.md (TypeScript utilities, Zod schemas)
+
+📋 Root AGENTS.md updated with directory index
+
+✅ Summary: 1 root + X directories initialized
+   💰 Estimated cost: ~$X.XX
+   🕐 Time saved: ~X minutes vs manual setup
+```
+
+## Quality Verification
+
+Before completing, verify:
+- [ ] Each AGENTS.md is ~20 lines, focused, and actionable
+- [ ] Build/test commands are correct and tested where possible
+- [ ] Cross-package dependencies are noted
+- [ ] No duplicate or conflicting information
+- [ ] Root index accurately reflects all initialized directories
+
+### Hierarchy Linking Verification (Required per Anthropic Docs)
+
+**For each created AGENTS.md file:**
+- [ ] **Hierarchy Level** field present and describes role (e.g., "Backend services", "UI components")
+- [ ] **Parent** field links to appropriate parent AGENTS.md with correct relative path
+- [ ] **Philosophy** field links to CLAUDE.md with correct relative path (uses `@` import syntax if in .claude/)
+- [ ] Links are validated as correct paths (no broken references)
+
+**For Root AGENTS.md:**
+- [ ] Directory Context Index table showing all subdirectories with links
+- [ ] Explains hierarchy linking structure for downstream agents
+
+**For Root CLAUDE.md (Bidirectional Linking):**
+- [ ] "Agent Coordination" section links to AGENTS.md
+- [ ] "Agent Contexts" section lists all subdirectory AGENTS.md files with links
+- [ ] Each listed AGENTS.md is validated and accessible
+- [ ] CLAUDE.md clearly explains the relationship: philosophy (CLAUDE.md) → agents (AGENTS.md) → subdirectories
+- [ ] All links use correct relative paths
+
+Rate your confidence in the completeness of this initialization (0-1) and note any directories that may need manual review.
+
+## Cost Considerations
+
+| Scenario | Directories | Estimated Cost | Time Saved |
+|----------|-------------|----------------|------------|
+| Standard /init | 1 | $0.01-0.02 | 2-3 min |
+| Small monorepo | 3-5 | $0.06-0.15 | 10-15 min |
+| Medium monorepo | 5-10 | $0.10-0.40 | 20-30 min |
+| Large monorepo | 10-20 | $0.20-0.80 | 45-60 min |
+
+## Research-Backed Enhancements
+
+This command uses incentive-based prompting techniques:
+- **Expert Persona**: DevOps architect framing (Kong et al., +60% accuracy)
+- **Stakes Language**: Critical importance framing (Bsharat et al., +45% quality)
+- **Step-by-Step**: Systematic phase execution (Yang et al., +46% accuracy)
+- **Self-Evaluation**: Confidence rating for quality assurance

package/dist/.opencode/command/ai-eng/research.md

@@ -0,0 +1,199 @@
+---
+name: ai-eng/research
+description: Conduct comprehensive multi-phase research across codebase, documentation, and external sources
+agent: plan
+version: 1.0.0
+inputs:
+  - name: query
+    type: string
+    required: false
+    description: Direct research question or topic
+  - name: ticket
+    type: string
+    required: false
+    description: Path to ticket file (optional if query provided)
+  - name: scope
+    type: string
+    required: false
+    description: Research scope (codebase|documentation|external|all)
+    default: all
+  - name: depth
+    type: string
+    required: false
+    description: Research depth (shallow|medium|deep)
+    default: medium
+outputs:
+  - name: research_document
+    type: structured
+    format: Markdown document with YAML frontmatter
+    description: Comprehensive research findings saved to docs/research/
+---
+
+# Research Command
+
+Conduct comprehensive research for: $ARGUMENTS
+
+## Usage
+
+```bash
+/ai-eng/research [query] [options]
+```
+
+### Options
+
+- `--swarm`: Use Swarms multi-agent orchestration instead of legacy coordinator
+- `-s, --scope <scope>`: Research scope (codebase|documentation|all) [default: all]
+- `-d, --depth <depth>`: Research depth (shallow|medium|deep) [default: medium]
+- `-o, --output <file>`: Output file path
+- `-f, --format <format>`: Export format (markdown|json|html) [default: markdown]
+- `--no-cache`: Disable research caching
+- `-v, --verbose`: Enable verbose output
+
+## Expert Context
+
+You are a senior research analyst with 15+ years of experience at companies like Google, Stripe, and Netflix. Your expertise is in systematic investigation, pattern recognition, and synthesizing complex information into actionable insights. This research is critical to the project's success.
+
+## Research Methodology
+
+Take a deep breath and execute this research systematically.
+
+### Phase 1: Context & Scope Definition (CRITICAL - Do First)
+
+1. **Parse the Research Request**
+   - Identify the primary research question
+   - Decompose into 3-5 sub-questions
+   - Define clear scope boundaries
+   - Determine depth level required
+
+2. **Read Primary Sources First**
+   - NEVER spawn agents before understanding context
+   - Read any referenced tickets or documents completely
+   - Identify what information already exists
+
+### Phase 2: Parallel Discovery
+
+#### Subagent Communication Protocol (Minimal)
+
+When you spawn EACH discovery agent, include a small **Context Handoff Envelope** in the prompt. Subagents run in a separate context; do not assume they know anything unless you include it.
+
+Use this exact structure:
+
+```text
+<CONTEXT_HANDOFF_V1>
+Goal: (1 sentence)
+Scope: (codebase|docs|external|all)
+Known constraints: (bullets; optional)
+What I already checked: (bullets; optional)
+Files/paths to prioritize: (bullets; optional)
+Deliverable: (what you must return)
+Output format: RESULT_V1
+</CONTEXT_HANDOFF_V1>
+```
+
+All agents must respond with:
+
+```text
+<RESULT_V1>
+RESULT:
+EVIDENCE:
+OPEN_QUESTIONS:
+NEXT_STEPS:
+CONFIDENCE: 0.0-1.0
+</RESULT_V1>
+```
+
+Spawn these agents CONCURRENTLY for maximum efficiency:
+
+| Agent | Task |
+|-------|------|
+| `codebase-locator` | Find all relevant files, components, and directories |
+| `research-locator` | Discover existing documentation, decisions, and notes |
+| `codebase-pattern-finder` | Identify recurring implementation patterns |
+
+Wait for all discovery agents to complete before proceeding.
+
+### Phase 3: Sequential Deep Analysis
+
+Based on discovery results, run analyzers SEQUENTIALLY:
+
+1. **`codebase-analyzer`** - Extract implementation details with file:line evidence
+2. **`research-analyzer`** - Extract decisions, constraints, and insights from docs
+
+For complex research, consider adding:
+- `web-search-researcher` - External best practices and standards
+- `system-architect` - Architectural implications
+- `database-expert` - Data layer concerns
+- `security-scanner` - Security assessment
+
+### Phase 4: Synthesis & Documentation
+
+Create a comprehensive research document with:
+
+```markdown
+---
+date: [TODAY'S DATE]
+researcher: Assistant
+topic: '[Research Topic]'
+tags: [research, relevant, tags]
+status: complete
+confidence: high|medium|low
+agents_used: [list of agents]
+---
+
+## Synopsis
+[1-2 sentence summary]
+
+## Summary
+- Key finding 1
+- Key finding 2
+- Key finding 3
+
+## Detailed Findings
+
+### Codebase Analysis
+[Implementation details with file:line references]
+
+### Documentation Insights
+[Past decisions, rationale, constraints]
+
+### External Research
+[Best practices, standards, alternatives]
+
+## Code References
+- `path/file.ext:12-45` - Description
+- `path/other.ext:78` - Description
+
+## Architecture Insights
+[Patterns, design decisions, relationships]
+
+## Recommendations
+### Immediate Actions
+1. [Priority action]
+
+### Long-term Considerations
+- [Strategic recommendation]
+
+## Risks & Limitations
+- [Identified risks]
+
+## Open Questions
+- [ ] [Unresolved questions]
+```
+
+## Quality Checklist
+
+Before finalizing, verify:
+- [ ] All claims have file:line evidence
+- [ ] Historical context included
+- [ ] Open questions explicitly listed
+- [ ] Recommendations are actionable
+- [ ] Confidence levels assigned
+- [ ] Cross-component relationships identified
+
+## Output
+
+Save research document to `docs/research/[date]-[topic-slug].md`
+
+Rate your confidence in the research findings (0-1) and identify any assumptions or limitations.
+
+$ARGUMENTS

package/dist/.opencode/command/ai-eng/review.md

@@ -0,0 +1,73 @@
+---
+name: ai-eng/review
+description: Run comprehensive code review with multiple perspectives
+agent: review
+---
+
+# Review Command
+
+Review current changes or a PR with multiple expert perspectives.
+
+## Usage
+
+```bash
+/ai-eng/review [files...] [options]
+```
+
+### Options
+
+- `--swarm`: Use Swarms multi-agent orchestration instead of legacy coordinator
+- `-t, --type <type>`: Review type (full|incremental|security|performance|frontend) [default: full]
+- `-s, --severity <severity>`: Minimum severity level (low|medium|high|critical) [default: medium]
+- `-f, --focus <focus>`: Focused review (security|performance|frontend|general)
+- `-o, --output <file>`: Output report file [default: code-review-report.json]
+- `-v, --verbose`: Enable verbose output
+
+## Perspectives
+
+#### Subagent Communication Protocol (Minimal)
+
+If you spawn reviewer subagents in parallel, include:
+
+```text
+<CONTEXT_HANDOFF_V1>
+Goal: Review changes for (focus area)
+Files under review: (paths)
+Constraints: (e.g., no code changes; read-only)
+Deliverable: findings with file:line evidence
+Output format: RESULT_V1
+</CONTEXT_HANDOFF_V1>
+```
+
+Require:
+
+```text
+<RESULT_V1>
+RESULT:
+FINDINGS: (bullets with severity)
+EVIDENCE: (file:line)
+RECOMMENDATIONS:
+CONFIDENCE: 0.0-1.0
+</RESULT_V1>
+```
+
+- **Code Quality**: Clean code, SOLID principles, DRY
+- **Performance**: Time/space complexity, caching opportunities
+- **SEO**: Meta tags, structured data, Core Web Vitals impact
+- **Security**: Input validation, authentication, data exposure
+- **Architecture**: Component boundaries, coupling, scalability
+
+## Output Format
+
+For each finding provide:
+
+| Field | Description |
+|-------|-------------|
+| Severity | critical, major, minor |
+| Location | file:line |
+| Issue | Description of the problem |
+| Recommendation | Suggested fix |
+
+## Summary
+
+End with overall assessment: APPROVE, CHANGES_REQUESTED, or NEEDS_DISCUSSION.