agileflow 3.4.2 → 4.0.0-alpha.1

package/src/core/experts/epic-planner/expertise.yaml

@@ -1,144 +0,0 @@
-# Epic Planner Expert - Domain Knowledge
-# This file is the agent's "mental model" of the epic planning domain
-# AUTO-UPDATED by self-improve.md after completing work
-
-domain: epic-planner
-last_updated: 2025-12-21
-version: 1.1
-
-# AgileFlow-specific epic planning structure (learned from actual codebase)
-files:
-  epics:
-    - path: docs/05-epics/
-      purpose: "Epic definitions with goals and metrics"
-      conventions: "EP-#### naming (e.g., EP-0001)"
-      example: "ep-0001-agent-expert-pilot.md"
-    - path: docs/00-meta/templates/epic-template.md
-      purpose: "Epic template with sections: Goal, Problem Statement, Solution, Stories, etc."
-
-  stories:
-    - path: docs/06-stories/
-      purpose: "User stories organized by epic subdirectory"
-      conventions: "US-#### naming (e.g., US-0001)"
-      subdirectory_pattern: "stories/<epic-id>/ for grouping"
-    - path: docs/00-meta/templates/story-template.md
-      purpose: "Story template with AC, test stub, estimates"
-
-  testing:
-    - path: docs/07-testing/test-cases/
-      purpose: "Test case stubs per story"
-      conventions: "One file per US-####"
-    - path: docs/09-agents/status.json
-      purpose: "Story test_status tracking (passing/failing/not_run)"
-
-  research:
-    - path: docs/10-research/
-      purpose: "Technical research to inform planning"
-      naming: "YYYYMMDD-slug.md format"
-    - path: docs/03-decisions/
-      purpose: "ADRs constraining architecture"
-      naming: "adr-NNNN-title.md format"
-
-  coordination:
-    - path: docs/09-agents/status.json
-      purpose: "Single source of truth for story tracking"
-      fields: ["owner", "status", "priority", "estimate", "depends_on", "test_status"]
-    - path: docs/09-agents/bus/log.jsonl
-      purpose: "Agent coordination messages (append-only)"
-
-relationships:
-  - parent: epics
-    child: stories
-    type: decomposes_into
-    notes: "Epics decompose into 3-10 stories; EP-0001 had 6 stories"
-  - parent: stories
-    child: test_cases
-    type: has
-    notes: "Each story has test case stub in docs/07-testing/"
-  - parent: stories
-    child: agents
-    type: assigned_to
-    notes: "Stories assigned via owner field in status.json"
-  - parent: research
-    child: epics
-    type: informs
-    notes: "Research notes link to epics (see EP-0001 referencing research)"
-
-patterns:
-  - name: INVEST Criteria
-    description: "Independent, Negotiable, Valuable, Estimable, Small, Testable"
-    location: N/A
-    example: "Validate each story against INVEST"
-
-  - name: Vertical Slices
-    description: "Each story delivers user-visible value"
-    location: docs/06-stories/
-    example: "Full feature slice, not horizontal layers"
-
-  - name: Story Table in Epic
-    description: "Epic markdown includes story table with ID, Title, Owner, Status, Estimate"
-    location: docs/05-epics/ep-0001-agent-expert-pilot.md
-    example: "| US-0001 | Expert Directory Structure | AG-DEVOPS | ready | 2h |"
-
-  - name: Story Status Flow
-    description: "Stories progress: ready → in_progress → in_review → done"
-    location: docs/09-agents/status.json
-    example: "Update status field as work progresses"
-
-  - name: Hour-Based Estimates
-    description: "Stories estimated in hours (2h, 3h) not days"
-    location: docs/05-epics/ep-0001-agent-expert-pilot.md
-    example: "Total Estimate: ~15 hours"
-
-conventions:
-  - "Stories typically 2-3 hours (not days)"
-  - "Status.json is single source of truth for story tracking"
-  - "Test stub created with story in docs/07-testing/test-cases/"
-  - "Dependencies listed in depends_on array in status.json"
-  - "Stories assigned via owner field (AG-UI, AG-API, AG-DEVOPS, etc.)"
-  - "Research notes referenced in epic with relative links"
-  - "Exit criteria checklist at bottom of epic ([ ] checkboxes)"
-  - "Epics have Problem Statement, Solution, Success Criteria sections"
-
-agent_assignments:
-  AG-UI:
-    - "Frontend components"
-    - "Styling and design systems"
-    - "Accessibility"
-    - "User interactions"
-  AG-API:
-    - "Backend endpoints"
-    - "Business logic"
-    - "Data models"
-    - "Database access"
-  AG-CI:
-    - "Test infrastructure"
-    - "CI/CD pipelines"
-    - "Code quality tools"
-  AG-DEVOPS:
-    - "Deployment"
-    - "Dependencies"
-    - "Technical debt"
-    - "Expert system infrastructure"
-
-# Learned from AgileFlow codebase exploration
-learnings:
-  - date: 2025-12-21
-    context: "Analyzed EP-0001 epic structure"
-    insight: "Epics include Problem Statement, Solution, Success Criteria, Stories table, Architecture Context, Dependencies, Risks, Exit Criteria sections"
-    source: "docs/05-epics/ep-0001-agent-expert-pilot.md"
-
-  - date: 2025-12-21
-    context: "Analyzed story tracking system"
-    insight: "status.json tracks stories with owner, status, priority, estimate, depends_on, test_status fields; updated timestamp at root"
-    source: "docs/09-agents/status.json"
-
-  - date: 2025-12-21
-    context: "Analyzed EP-0001 completion pattern"
-    insight: "Epic with 6 stories, ~15 hours total; stories ranged 2h-3h each; all marked done with test_status: passing"
-    source: "docs/05-epics/ep-0001-agent-expert-pilot.md, docs/09-agents/status.json"
-
-  - date: 2025-12-21
-    context: "Analyzed research integration"
-    insight: "Epics reference research notes with relative links (../10-research/YYYYMMDD-slug.md)"
-    source: "docs/05-epics/ep-0001-agent-expert-pilot.md"

package/src/core/experts/epic-planner/question.md

@@ -1,56 +0,0 @@
----
-description: Ask questions about {{DOMAIN}} - uses expertise for fast, accurate answers
-argument-hint: <your question>
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/{{DOMAIN}}/expertise.yaml
----
-
-# {{DOMAIN_TITLE}} Expert - Question
-
-You are an expert on the {{DOMAIN}} domain for this codebase. You maintain a mental model (expertise file) that helps you answer questions quickly and accurately.
-
-## CRITICAL: Expertise-First Workflow
-
-**You MUST follow this workflow. Do not skip steps.**
-
-### Step 1: Load Your Expertise
-Read your expertise file at `{{EXPERTISE_FILE}}` FIRST, before doing anything else.
-
-This file contains:
-- Key file locations you already know
-- Relationships between entities
-- Patterns and conventions to follow
-- Recent learnings from past work
-
-### Step 2: Validate Against Actual Code
-Your expertise is a mental model, NOT the source of truth. The code is always the source of truth.
-
-For each relevant piece of expertise:
-1. Check if the file/pattern still exists
-2. Verify your understanding matches current code
-3. Note any discrepancies (for self-improve later)
-
-### Step 3: Answer the Question
-With your validated mental model:
-1. Answer based on your expertise + validation
-2. Be specific - reference exact file paths
-3. If expertise was wrong, note it in your answer
-4. If you don't know, say so (don't guess)
-
-## Key Principles
-
-- **Speed**: Use expertise to skip unnecessary searching
-- **Accuracy**: Always validate against actual code
-- **Honesty**: Acknowledge when expertise is stale
-- **Learning**: Note discrepancies for self-improve
-
-## Anti-Patterns to Avoid
-
-- Reading expertise but ignoring it
-- Searching the codebase before checking expertise
-- Trusting expertise blindly without validation
-- Giving vague answers when expertise has specifics
-
-## Question
-
-{{argument}}

package/src/core/experts/epic-planner/self-improve.md

@@ -1,106 +0,0 @@
----
-description: Update {{DOMAIN}} expertise after making changes
-argument-hint: [optional context about what changed]
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/{{DOMAIN}}/expertise.yaml
----
-
-# {{DOMAIN_TITLE}} Expert - Self-Improve
-
-You are updating your mental model (expertise file) to reflect changes in the codebase. This keeps your expertise accurate and useful for future tasks.
-
-## CRITICAL: Self-Improve Workflow
-
-### Step 1: Read Current Expertise
-Load your expertise file at `{{EXPERTISE_FILE}}`.
-
-Understand what you currently know about:
-- File locations
-- Relationships
-- Patterns
-- Conventions
-
-### Step 2: Analyze What Changed
-Identify changes using one of these methods:
-
-**If git diff available:**
-```bash
-git diff HEAD~1 --name-only | grep -E "{{DOMAIN_PATTERN}}"
-```
-
-**If context provided:**
-Use the argument/context to understand what changed.
-
-**If neither:**
-Compare expertise file against actual codebase state.
-
-### Step 3: Update Expertise
-
-**Update `files` section if:**
-- New files were added to the domain
-- Files were moved or renamed
-- Key exports changed
-- Purpose or conventions changed
-
-**Update `relationships` section if:**
-- New relationships were created
-- Existing relationships changed
-- Relationships were removed
-
-**Update `patterns` section if:**
-- New patterns were introduced
-- Existing patterns were modified
-- Better patterns discovered
-
-**Update `conventions` section if:**
-- New conventions established
-- Existing conventions changed
-- Conventions deprecated
-
-**ALWAYS add to `learnings` section:**
-```yaml
-learnings:
-  - date: {{TODAY}}
-    insight: "Brief description of what was learned"
-    files_affected: [list, of, files]
-    context: "What triggered this learning (story ID, task, etc.)"
-```
-
-### Step 4: Validate Updated Model
-After updating, verify:
-1. All file paths in expertise still exist
-2. Relationships match actual code structure
-3. Patterns are still used as described
-4. No contradictions in the expertise file
-
-### Step 5: Write Updated Expertise
-Save the updated expertise.yaml file.
-
-## Rules for Self-Improve
-
-### DO:
-- Add only verified information
-- Remove stale/incorrect entries
-- Keep entries focused on {{DOMAIN}} domain only
-- Use specific file paths, not vague descriptions
-- Date all learnings entries
-
-### DON'T:
-- Add speculative information
-- Keep outdated entries "just in case"
-- Add knowledge from other domains
-- Make expertise file too large (keep it focused)
-- Forget to update last_updated timestamp
-
-## Quality Checklist
-
-Before saving:
-- [ ] `last_updated` timestamp is current
-- [ ] All file paths verified to exist
-- [ ] New learnings entry added with today's date
-- [ ] No duplicate entries
-- [ ] Expertise stays under 200 lines (focused)
-
-## Context
-
-{{argument}}

package/src/core/experts/epic-planner/workflow.md

@@ -1,184 +0,0 @@
----
-description: Plan, build, and improve {{DOMAIN}} feature with expertise-driven workflow
-argument-hint: <feature description>
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/{{DOMAIN}}/expertise.yaml
-  DOMAIN_PATTERN: "{{DOMAIN_GLOB_PATTERN}}"
----
-
-# {{DOMAIN_TITLE}} Expert: Plan → Build → Self-Improve
-
-You are executing a complete feature implementation with automatic knowledge capture. This workflow ensures you leverage existing expertise, execute efficiently, and capture learnings for future tasks.
-
-## CRITICAL: Three-Step Workflow
-
-**You MUST follow this exact sequence. Do not skip steps.**
-
----
-
-## Step 1: PLAN (Expertise-Informed)
-
-### 1.1 Load Your Expertise
-Read your expertise file at `{{EXPERTISE_FILE}}` FIRST.
-
-Extract from it:
-- Relevant file locations for this feature
-- Existing patterns you should follow
-- Relationships to consider
-- Recent learnings that might apply
-
-### 1.2 Validate Against Codebase
-Before planning, verify your expertise is accurate:
-- Check that referenced files still exist
-- Confirm patterns match current code
-- Note any discrepancies
-
-### 1.3 Create Implementation Plan
-Based on validated expertise, create a specific plan:
-
-```markdown
-## Implementation Plan
-
-### Files to Create/Modify
-1. [exact file path] - [what changes]
-2. [exact file path] - [what changes]
-
-### Pattern to Follow
-[Reference specific pattern from expertise]
-
-### Dependencies
-[What must exist before this work]
-
-### Validation
-[How to verify the implementation works]
-```
-
-**Output**: A detailed plan with exact file paths and specific changes.
-
----
-
-## Step 2: BUILD (Execute Plan)
-
-### 2.1 Pre-Build Verification
-Before making changes:
-- Ensure all dependencies from plan exist
-- Verify you have the required permissions/access
-- Check for any blocking issues
-
-### 2.2 Execute the Plan
-Follow your implementation plan exactly:
-- Create/modify files in the specified order
-- Apply patterns consistently
-- Add appropriate tests if applicable
-
-### 2.3 Capture Changes
-After building, document what changed:
-
-```bash
-# Capture the diff for self-improve
-git diff --name-only
-git diff HEAD
-```
-
-### 2.4 Validate Build
-Verify the implementation:
-- Run relevant tests
-- Check for type/lint errors
-- Verify the feature works as intended
-
-**Output**: Working code changes with captured diff.
-
-**On Failure**: Stop and report the error. Do NOT proceed to self-improve.
-
----
-
-## Step 3: SELF-IMPROVE (Update Expertise)
-
-**ONLY run this step if Step 2 succeeded.**
-
-### 3.1 Analyze What Changed
-Review the git diff and identify:
-- New files added to your domain
-- New patterns introduced
-- Relationships created or changed
-- Conventions established
-
-### 3.2 Update Expertise File
-Read and update `{{EXPERTISE_FILE}}`:
-
-**Update `files` section if:**
-- New files were added
-- Files were moved or renamed
-
-**Update `relationships` section if:**
-- New entities or relationships created
-- Cardinality changed
-
-**Update `patterns` section if:**
-- New implementation patterns used
-- Better approaches discovered
-
-**Update `conventions` section if:**
-- New naming conventions applied
-- New structural conventions established
-
-### 3.3 Add Learnings Entry
-**ALWAYS** add a new learnings entry:
-
-```yaml
-learnings:
-  - date: {{TODAY}}
-    insight: "Brief description of what was learned"
-    files_affected:
-      - path/to/file1
-      - path/to/file2
-    context: "Feature: {{argument}}"
-```
-
-### 3.4 Validate Updated Expertise
-Before saving:
-- [ ] All file paths exist
-- [ ] Relationships match code
-- [ ] `last_updated` is current
-- [ ] No duplicates added
-- [ ] File stays focused (<200 lines)
-
-### 3.5 Save Expertise
-Write the updated expertise.yaml file.
-
----
-
-## Error Handling
-
-### If Plan Step Fails
-- Report what information is missing
-- Suggest how to resolve (update expertise, provide context)
-- Do NOT proceed to build
-
-### If Build Step Fails
-- Report the specific error
-- Capture partial progress if any
-- Do NOT proceed to self-improve
-- Consider if expertise needs correction
-
-### If Self-Improve Step Fails
-- Report what couldn't be updated
-- Save what you can
-- Build step is still valid
-
----
-
-## Context Protection Notes
-
-This workflow is designed for context efficiency:
-- **Orchestrator**: Passes minimal data between steps
-- **Sub-agents**: Each step can run in isolated context if needed
-- **Token efficiency**: Expertise file provides compressed knowledge
-
-For large features, consider running each step as a separate sub-agent invocation.
-
----
-
-## Feature Request
-
-{{argument}}

package/src/core/experts/integrations/expertise.yaml

@@ -1,113 +0,0 @@
-# Integrations Expert - Domain Knowledge
-# This file is the agent's "mental model" of the integrations domain
-# AUTO-UPDATED by self-improve.md after completing work
-
-domain: integrations
-last_updated: 2025-12-21
-version: 1.1
-
-files:
-  clients:
-    - path: src/integrations/
-      purpose: "Third-party API client implementations"
-      key_exports: []
-      conventions: "One client per service (StripeClient, TwilioClient)"
-    - path: src/integrations/clients/
-      purpose: "API client classes for external services"
-      conventions: "Named *Client.ts"
-    - path: src/integrations/webhooks/
-      purpose: "Webhook receivers and handlers"
-      conventions: "Named *WebhookHandler.ts"
-
-  configuration:
-    - path: src/config/integrations.ts
-      purpose: "Integration configuration and API key management"
-      conventions: "All secrets from environment variables"
-    - path: .env.example
-      purpose: "Template for required environment variables"
-      conventions: "Document all integration API keys here"
-
-  types:
-    - path: src/types/integrations/
-      purpose: "TypeScript types for external service responses"
-      conventions: "Match external API response schemas"
-
-  services:
-    - path: src/services/payment/
-      purpose: "Payment processing service layer"
-      conventions: "Wraps Stripe/PayPal/Square clients"
-    - path: src/services/email/
-      purpose: "Email delivery service layer"
-      conventions: "Wraps SendGrid/Mailgun/SES"
-    - path: src/services/auth/
-      purpose: "Authentication provider integrations"
-      conventions: "OAuth flows for Google/GitHub/Auth0"
-
-relationships:
-  - parent: services
-    child: clients
-    type: uses
-    notes: "Service layer uses API clients"
-  - parent: webhooks
-    child: services
-    type: triggers
-    notes: "Webhooks trigger service layer actions"
-  - parent: api_endpoints
-    child: services
-    type: calls
-    notes: "API endpoints call integration services"
-
-patterns:
-  - name: API Client Pattern
-    description: "Wrap third-party SDK with custom client for testability"
-    location: src/integrations/clients/
-    example: |
-      class StripeClient {
-        constructor(apiKey: string) { ... }
-        async createPayment(amount: number) { ... }
-      }
-
-  - name: Webhook Handler Pattern
-    description: "Validate signature, parse event, handle idempotently"
-    location: src/integrations/webhooks/
-    example: |
-      1. Validate webhook signature
-      2. Check if event already processed (idempotency)
-      3. Parse and route to handler
-      4. Respond 200 immediately
-
-  - name: Retry with Exponential Backoff
-    description: "Retry failed external requests with increasing delays"
-    location: src/integrations/clients/
-    example: "1s, 2s, 4s, 8s delays with jitter"
-
-  - name: Circuit Breaker
-    description: "Stop calling failing services to prevent cascade failures"
-    location: src/integrations/clients/
-    example: "Open circuit after 5 consecutive failures"
-
-  - name: Rate Limiting
-    description: "Respect external service rate limits"
-    location: src/integrations/clients/
-    example: "Token bucket or queue-based rate limiting"
-
-conventions:
-  - "NEVER hardcode API keys - use environment variables"
-  - "ALWAYS validate webhook signatures before processing"
-  - "ALWAYS implement retry logic with exponential backoff"
-  - "ALWAYS log external service calls (without secrets)"
-  - "ALWAYS handle rate limiting gracefully"
-  - "Implement idempotency for webhook handlers"
-  - "Use circuit breaker for unreliable services"
-  - "Mock external services in tests"
-  - "Document all required environment variables"
-
-# Learnings (trimmed - keep 2 most actionable)
-learnings:
-  - date: 2025-12-21
-    context: "IDE integration pattern"
-    insight: "IDE-specific installers in installers/ide/ handle different config dirs (.claude/, .cursor/, .windsurf/). Shared logic in _base-ide.js, overrides per IDE."
-
-  - date: 2025-12-21
-    context: "Content injection"
-    insight: "Placeholders ({{AGENT_LIST}}, {{COMMAND_LIST}}) in source files replaced at install time. Zero runtime overhead."

package/src/core/experts/integrations/question.md

@@ -1,74 +0,0 @@
-# Integrations Expert - Question Workflow
-
-**Purpose**: Answer questions about third-party integrations using expertise-first approach.
-
-## Workflow
-
-### Step 1: Load Expertise
-```
-Read: packages/cli/src/core/experts/integrations/expertise.yaml
-```
-
-Parse the expertise file to understand:
-- Known integration client locations
-- Webhook handler patterns
-- Environment variable conventions
-- Retry and error handling patterns
-- Active integrations catalog
-
-### Step 2: Validate Against Codebase
-
-Before answering, verify expertise is current:
-1. Check if mentioned files/directories exist
-2. Spot-check integration clients mentioned
-3. Verify environment variables documented
-4. Note any discrepancies for later self-improve
-
-### Step 3: Answer with Expertise
-
-When answering questions:
-
-**If expertise covers the question:**
-- Provide direct answer from expertise
-- Include specific file paths
-- Reference patterns (retry logic, webhook validation)
-- Include required environment variables
-- Skip unnecessary exploration
-
-**If expertise is incomplete:**
-- Search codebase for missing information
-- Answer the question
-- Note gaps for self-improve
-
-### Step 4: Flag Updates Needed
-
-If you discovered new information:
-```
-Note for self-improve:
-- New integration discovered: [service]
-- Webhook endpoint not documented: [path]
-- Environment variable missing: [var]
-```
-
-## Example Usage
-
-**Question**: "Where is the Stripe integration?"
-
-**Expertise-First Answer**:
-1. Check expertise.yaml → integrations_catalog → payment → Stripe
-2. Check file locations → `src/integrations/clients/`
-3. Answer: "Stripe client is in `src/integrations/clients/StripeClient.ts`. Required env vars: `STRIPE_API_KEY`, `STRIPE_WEBHOOK_SECRET`. Webhook handlers in `src/integrations/webhooks/`."
-
-**Question**: "How do we handle webhook signature validation?"
-
-**Expertise-First Answer**:
-1. Check expertise.yaml → patterns → Webhook Handler Pattern
-2. Reference the pattern description
-3. Answer with specific implementation location
-
-## Key Principles
-
-1. **Expertise First**: Always check expertise.yaml before searching
-2. **Security Focus**: Always mention required env vars and signature validation
-3. **Be Specific**: Provide exact file paths and required configuration
-4. **Learn**: Note gaps for self-improve to fill later