agileflow 3.4.3 → 4.0.0-alpha.2

package/src/core/experts/integrations/self-improve.md

@@ -1,151 +0,0 @@
-# Integrations Expert - Self-Improve Workflow
-
-**Purpose**: Automatically update expertise.yaml after completing integration work.
-
-## When to Run
-
-Run this workflow after:
-- Adding a new third-party integration
-- Implementing webhook handlers
-- Updating API client implementations
-- Discovering new integration patterns
-- Adding new environment variables
-
-## Workflow
-
-### Step 1: Load Current Expertise
-```
-Read: packages/cli/src/core/experts/integrations/expertise.yaml
-```
-
-### Step 2: Analyze Changes Made
-
-Review what was just implemented:
-1. What new integration clients were created?
-2. What webhook handlers were added?
-3. What environment variables are required?
-4. What error handling patterns were used?
-5. What was learned during implementation?
-
-### Step 3: Generate Diff
-
-Identify what's new or changed:
-- New integrations not in catalog
-- New webhook endpoints
-- New environment variables
-- Pattern changes or improvements
-- Gotchas and edge cases discovered
-
-### Step 4: Update Expertise
-
-Add a new learning entry:
-```yaml
-learnings:
-  - date: YYYY-MM-DD
-    insight: "Brief description of what was learned"
-    files_affected:
-      - path/to/file1
-      - path/to/file2
-    context: "Story or task context"
-```
-
-Update integrations_catalog if new service added:
-```yaml
-integrations_catalog:
-  category:
-    - name: ServiceName
-      env_vars: [VAR1, VAR2]
-      webhooks: [event.type1, event.type2]
-```
-
-### Step 5: Validate Update
-
-Ensure the expertise file:
-- Is valid YAML
-- Has updated `last_updated` date
-- Doesn't exceed ~200 lines
-- All environment variables documented
-
-## Learning Categories
-
-### New Integrations
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Added Plaid integration for bank account linking"
-    files_affected:
-      - src/integrations/clients/PlaidClient.ts
-      - src/integrations/webhooks/PlaidWebhookHandler.ts
-    context: "US-0060: Bank account verification"
-
-# Also update integrations_catalog:
-integrations_catalog:
-  banking:
-    - name: Plaid
-      env_vars: [PLAID_CLIENT_ID, PLAID_SECRET, PLAID_ENV]
-      webhooks: [ITEM_LOGIN_REQUIRED, TRANSACTIONS_READY]
-```
-
-### Webhook Learnings
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Stripe webhooks require raw body for signature validation"
-    files_affected: [src/integrations/webhooks/StripeWebhookHandler.ts]
-    context: "US-0061: Fix webhook signature verification"
-```
-
-### Error Handling Discoveries
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Twilio returns 429 with Retry-After header - use that value for backoff"
-    files_affected: [src/integrations/clients/TwilioClient.ts]
-    context: "US-0062: Improve SMS retry logic"
-```
-
-### Security Insights
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Auth0 tokens must be validated server-side, not just decoded"
-    files_affected: [src/services/auth/Auth0Service.ts]
-    context: "US-0063: Security audit fixes"
-```
-
-## Example Update
-
-Before work:
-```yaml
-integrations_catalog:
-  payment:
-    - name: Stripe
-      env_vars: [STRIPE_API_KEY, STRIPE_WEBHOOK_SECRET]
-```
-
-After adding PayPal:
-```yaml
-integrations_catalog:
-  payment:
-    - name: Stripe
-      env_vars: [STRIPE_API_KEY, STRIPE_WEBHOOK_SECRET]
-    - name: PayPal
-      env_vars: [PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_WEBHOOK_ID]
-      webhooks: [PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED]
-
-learnings:
-  - date: 2025-12-16
-    insight: "PayPal webhook validation requires fetching verification from PayPal API"
-    files_affected:
-      - src/integrations/clients/PayPalClient.ts
-      - src/integrations/webhooks/PayPalWebhookHandler.ts
-    context: "US-0064: Add PayPal payment support"
-```
-
-## Key Principles
-
-1. **Document All Env Vars**: Every integration needs documented configuration
-2. **Webhook Security**: Always note signature validation requirements
-3. **Error Patterns**: Document retry strategies and error handling
-4. **Rate Limits**: Note any rate limiting behavior discovered
-5. **Test Credentials**: Note if sandbox/test mode available

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

@@ -1,246 +0,0 @@
-# Integrations Expert - Complete Workflow
-
-**Purpose**: End-to-end workflow for implementing third-party integrations with expertise-first approach.
-
-## The Three-Step Workflow
-
-```
-Plan (with Expertise) → Build (Execute) → Self-Improve (Update Expertise)
-```
-
----
-
-## Step 1: Plan (with Expertise)
-
-### 1.1 Load Expertise First
-```
-Read: packages/cli/src/core/experts/integrations/expertise.yaml
-```
-
-Parse and internalize:
-- Known integration client locations
-- Existing integrations catalog
-- Webhook handler patterns
-- Error handling conventions
-- Environment variable requirements
-
-### 1.2 Validate Expertise Against Codebase
-
-Before planning, verify expertise is current:
-```bash
-# Check key directories exist
-ls src/integrations/clients/
-ls src/integrations/webhooks/
-```
-
-Note any discrepancies for later update.
-
-### 1.3 Create Detailed Plan
-
-With expertise loaded, create implementation plan:
-
-1. **Check if similar integration exists** (from catalog)
-2. **Identify required patterns** (retry, webhook validation, etc.)
-3. **List environment variables needed**
-4. **Plan error handling strategy**
-
-Example Plan:
-```markdown
-## Implementation Plan: Add Twilio SMS Integration
-
-### From Expertise:
-- Client location: src/integrations/clients/
-- Webhook location: src/integrations/webhooks/
-- Pattern: Retry with exponential backoff
-- Pattern: Webhook signature validation
-
-### Environment Variables:
-- TWILIO_ACCOUNT_SID
-- TWILIO_AUTH_TOKEN
-- TWILIO_WEBHOOK_SECRET
-
-### Files to Create:
-- src/integrations/clients/TwilioClient.ts
-- src/integrations/webhooks/TwilioWebhookHandler.ts
-
-### Implementation Steps:
-1. Create TwilioClient with retry logic
-2. Implement SMS sending method
-3. Create webhook handler with signature validation
-4. Add environment variable documentation
-5. Write integration tests with mocks
-```
-
----
-
-## Step 2: Build (Execute Plan)
-
-### 2.1 Execute Implementation
-
-Follow the plan exactly:
-- Use file paths from expertise
-- Apply patterns (retry, webhook validation) from expertise
-- Follow security conventions (no hardcoded secrets)
-
-### 2.2 Handle Discoveries
-
-If you discover something not in expertise:
-```markdown
-## Discovery Log
-- Found: Twilio returns 429 with Retry-After header
-- Pattern: Queue-based rate limiting more effective than token bucket
-- Gotcha: Webhook signature uses raw body, not parsed JSON
-```
-
-### 2.3 Security Checklist
-
-Per expertise conventions:
-- ✅ API keys in environment variables
-- ✅ Webhook signatures validated
-- ✅ No secrets in logs or errors
-- ✅ Retry logic with exponential backoff
-- ✅ Rate limiting respected
-
-### 2.4 Capture Changes
-
-Document what was actually changed:
-```markdown
-## Changes Made
-- Created: src/integrations/clients/TwilioClient.ts
-- Created: src/integrations/webhooks/TwilioWebhookHandler.ts
-- Updated: .env.example (added Twilio vars)
-- Created: src/integrations/__tests__/TwilioClient.test.ts
-```
-
----
-
-## Step 3: Self-Improve (Update Expertise)
-
-### 3.1 Load Current Expertise
-```
-Read: packages/cli/src/core/experts/integrations/expertise.yaml
-```
-
-### 3.2 Identify Updates Needed
-
-Compare discoveries with current expertise:
-- New integration to add to catalog?
-- New environment variables documented?
-- New webhook endpoints?
-- Error handling learnings?
-
-### 3.3 Update Expertise File
-
-Add to integrations_catalog:
-```yaml
-integrations_catalog:
-  messaging:
-    - name: Twilio
-      env_vars: [TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_WEBHOOK_SECRET]
-      webhooks: [message.delivered, message.failed, message.received]
-```
-
-Add learning entry:
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Twilio webhook validation requires X-Twilio-Signature header and raw body"
-    files_affected:
-      - src/integrations/webhooks/TwilioWebhookHandler.ts
-    context: "US-0100: Add Twilio SMS support"
-```
-
-Update `last_updated` date.
-
-### 3.4 Validate Update
-
-Ensure expertise.yaml:
-- Is valid YAML
-- All env vars documented
-- Reflects current integrations
-
----
-
-## Quick Reference
-
-### Before ANY Integration Work
-```
-1. Read expertise.yaml
-2. Check integrations_catalog for similar services
-3. Identify required patterns
-4. Plan with security in mind
-```
-
-### After ANY Integration Work
-```
-1. Add new integration to catalog
-2. Document all environment variables
-3. Note webhook handling requirements
-4. Update expertise.yaml
-```
-
-### Key Patterns (from expertise)
-- API Client Pattern: Wrap SDK for testability
-- Webhook Handler Pattern: Validate → Check idempotency → Process → Respond 200
-- Retry Pattern: Exponential backoff with jitter
-- Circuit Breaker: Stop calling failing services
-
-### Security Conventions (from expertise)
-- NEVER hardcode API keys
-- ALWAYS validate webhook signatures
-- ALWAYS implement retry with backoff
-- ALWAYS log without secrets
-
----
-
-## Example: Complete Integration Implementation
-
-**Task**: Integrate Stripe for payments
-
-### Plan Phase
-```markdown
-From expertise:
-- Client pattern: src/integrations/clients/
-- Webhook pattern: signature validation required
-- Similar integration: See PayPal in catalog
-
-Plan:
-1. Create StripeClient.ts
-2. Implement payment methods
-3. Create webhook handler with signature validation
-4. Add idempotency for webhook events
-5. Document env vars
-```
-
-### Build Phase
-```markdown
-Created:
-- src/integrations/clients/StripeClient.ts
-- src/integrations/webhooks/StripeWebhookHandler.ts
-
-Discoveries:
-- Stripe requires raw body for webhook signature
-- Need to use stripe.webhooks.constructEvent()
-- Idempotency key useful for create operations
-```
-
-### Self-Improve Phase
-```yaml
-integrations_catalog:
-  payment:
-    - name: Stripe
-      env_vars: [STRIPE_API_KEY, STRIPE_WEBHOOK_SECRET]
-      webhooks: [payment_intent.succeeded, charge.refunded, subscription.updated]
-
-learnings:
-  - date: 2025-12-16
-    insight: "Stripe webhooks need express.raw() middleware before json parsing"
-    files_affected:
-      - src/integrations/webhooks/StripeWebhookHandler.ts
-      - src/app.ts
-    context: "US-0101: Stripe payment integration"
-```
-
----
-
-This workflow ensures secure integrations and continuous learning.

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

@@ -1,125 +0,0 @@
-# Mentor Expert - Domain Knowledge
-# This file is the agent's "mental model" of the mentor/orchestration domain
-# AUTO-UPDATED by self-improve.md after completing work
-
-domain: mentor
-last_updated: 2025-12-21
-version: 1.1
-
-# AgileFlow-specific mentor/babysit workflow (learned from actual codebase)
-files:
-  coordination:
-    - path: docs/09-agents/status.json
-      purpose: "Single source of truth for story statuses"
-      fields: ["owner", "status", "priority", "estimate", "depends_on", "test_status"]
-      conventions: "Update after every status change"
-    - path: docs/09-agents/bus/log.jsonl
-      purpose: "Agent coordination message bus"
-      conventions: "Append-only JSON Lines, newest last"
-
-  planning:
-    - path: docs/05-epics/
-      purpose: "Epic definitions"
-      conventions: "EP-#### naming (e.g., EP-0001)"
-    - path: docs/06-stories/
-      purpose: "User stories"
-      conventions: "US-#### naming, organized by epic subdirectory"
-    - path: docs/07-testing/test-cases/
-      purpose: "Test stubs for stories"
-      conventions: "One per story"
-
-  research:
-    - path: docs/10-research/
-      purpose: "Technical research notes"
-      conventions: "YYYYMMDD-slug.md format"
-      example_notes:
-        - "20251216-agent-experts-self-improving-agents.md"
-        - "20251216-mermaid-js-diagramming.md"
-    - path: docs/03-decisions/
-      purpose: "Architecture Decision Records"
-      conventions: "adr-NNNN-title.md format"
-
-  project:
-    - path: CLAUDE.md
-      purpose: "Project context and conventions (internal)"
-    - path: docs/08-project/roadmap.md
-      purpose: "Product roadmap"
-    - path: docs/08-project/backlog.md
-      purpose: "Feature backlog"
-
-  agent_experts:
-    - path: packages/cli/src/core/experts/
-      purpose: "Agent expertise files (25 domains)"
-      pattern: "<domain>/expertise.yaml, question.md, self-improve.md, workflow.md"
-    - path: packages/cli/src/core/agents/
-      purpose: "Agent prompt files (26+ agents)"
-      pattern: "<agent>.md with YAML frontmatter"
-
-relationships:
-  - parent: mentor
-    child: specialized_agents
-    type: coordinates
-    notes: "Mentor spawns Agent Experts with pre-loaded domain knowledge"
-  - parent: epics
-    child: stories
-    type: contains
-    notes: "Epics break down into 3-10 stories (EP-0001 had 6)"
-  - parent: research
-    child: planning
-    type: informs
-    notes: "Research informs epic planning (see EP-0001 research link)"
-  - parent: status_json
-    child: stories
-    type: tracks
-    notes: "status.json is single source of truth for all story tracking"
-
-patterns:
-  - name: Babysit Workflow
-    description: "Interactive mentor guiding from idea to PR"
-    location: packages/cli/src/core/commands/babysit.md
-    flow: "Ask what to work on → Check status.json → Create/update stories → Spawn agents → Verify → Commit"
-
-  - name: Session Harness
-    description: "Test verification before marking complete"
-    commands:
-      - "/agileflow:verify STORY=US-XXXX"
-      - "/agileflow:baseline 'description'"
-    location: "Session init verifies build/tests"
-
-  - name: Story Status Flow
-    description: "Stories progress through defined states"
-    states: ["ready", "in_progress", "in_review", "done"]
-    location: docs/09-agents/status.json
-
-  - name: Agent Expertise Workflow
-    description: "Three-step: Plan → Build → Self-Improve"
-    location: packages/cli/src/core/experts/
-    benefit: "Agents accumulate learnings over time"
-
-  - name: Auto-Archival
-    description: "Completed stories archived after 7 days"
-    script: scripts/archive-completed-stories.sh
-    destination: "docs/09-agents/archive/YYYY-MM.json"
-
-conventions:
-  - "Always check existing epics/stories in status.json before creating new"
-  - "Use /agileflow:verify before marking story in_review"
-  - "Update status.json after every status change"
-  - "WIP limit: max 2 stories per agent"
-  - "Stories typically 2-3 hours (not days)"
-  - "Spawn Agent Experts (not generic agents) for domain work"
-  - "Research notes inform epic planning"
-  - "NO AI attribution in commits (per CLAUDE.md)"
-
-# Agent roster: AG-UI, AG-API, AG-CI, AG-DEVOPS, EPIC-PLANNER, ADR-WRITER, RESEARCH, MENTOR
-# (details in babysit.md delegation framework - omitted here)
-
-# Learnings (trimmed - keep 2 most actionable)
-learnings:
-  - date: 2025-12-21
-    context: "Babysit workflow"
-    insight: "Guides from task selection through story creation, agent spawning, verification, and commit. Status.json tracks epics + stories."
-
-  - date: 2025-12-21
-    context: "Agent Expert system"
-    insight: "26 domain experts with expertise.yaml, question.md, self-improve.md, workflow.md. Agents load expertise first before tasks."

package/src/core/experts/mentor/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/mentor/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}}