agileflow 3.4.3 → 4.0.0-alpha.2

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

@@ -1,264 +0,0 @@
-# Monitoring Expert - Complete Workflow
-
-**Purpose**: End-to-end workflow for implementing monitoring 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/monitoring/expertise.yaml
-```
-
-Parse and internalize:
-- Known logging and metrics locations
-- Structured logging patterns
-- Metric types (counter, gauge, histogram)
-- Health check implementations
-- Alert rules and runbooks
-- SLO targets
-
-### 1.2 Validate Expertise Against Codebase
-
-Before planning, verify expertise is current:
-```bash
-# Check monitoring implementation exists
-ls src/logging/
-ls src/metrics/
-ls monitoring/alerts/
-```
-
-Note any discrepancies for later update.
-
-### 1.3 Create Detailed Plan
-
-With expertise loaded, create implementation plan:
-
-1. **Identify monitoring gap** (from expertise)
-2. **Determine metric types needed** (counter, gauge, histogram)
-3. **Plan alert thresholds** based on SLO targets
-4. **Create runbook outline** for the alert
-
-Example Plan:
-```markdown
-## Implementation Plan: Add Database Monitoring
-
-### From Expertise:
-- Metrics location: src/metrics/
-- Metric types: RED (Rate, Errors, Duration)
-- SLO targets: p95 <200ms, error rate <0.1%
-- Every alert needs runbook
-
-### Metrics to Add:
-- db_query_duration_seconds (histogram)
-- db_query_total (counter)
-- db_query_errors_total (counter)
-- db_connection_pool_size (gauge)
-- db_connection_pool_available (gauge)
-
-### Alerts to Create:
-- DatabaseSlowQueries: p95 query time >200ms
-- DatabaseConnectionPoolExhausted: available <5
-
-### Runbooks to Write:
-- monitoring/runbooks/db-slow-queries.md
-- monitoring/runbooks/db-pool-exhausted.md
-
-### Implementation Steps:
-1. Add metrics collection to database client
-2. Create Grafana dashboard for database metrics
-3. Configure alerts with thresholds
-4. Write runbooks for each alert
-5. Test alerting in staging
-```
-
----
-
-## Step 2: Build (Execute Plan)
-
-### 2.1 Execute Implementation
-
-Follow the plan exactly:
-- Use metric naming from expertise
-- Apply structured logging pattern
-- Follow runbook template
-
-### 2.2 Handle Discoveries
-
-If you discover something not in expertise:
-```markdown
-## Discovery Log
-- Found: Connection pool metrics require custom instrumentation
-- Pattern: Use histogram for latency, counter for errors
-- Gotcha: Prometheus labels have cardinality limits
-```
-
-### 2.3 Security Checklist
-
-Per expertise conventions:
-- ✅ No PII in logs
-- ✅ No secrets in logs
-- ✅ Request ID included for correlation
-- ✅ Appropriate log levels used
-
-### 2.4 Capture Changes
-
-Document what was actually changed:
-```markdown
-## Changes Made
-- Created: src/metrics/database.ts
-- Created: monitoring/dashboards/database.json
-- Created: monitoring/alerts/database-alerts.yaml
-- Created: monitoring/runbooks/db-slow-queries.md
-- Created: monitoring/runbooks/db-pool-exhausted.md
-```
-
----
-
-## Step 3: Self-Improve (Update Expertise)
-
-### 3.1 Load Current Expertise
-```
-Read: packages/cli/src/core/experts/monitoring/expertise.yaml
-```
-
-### 3.2 Identify Updates Needed
-
-Compare discoveries with current expertise:
-- New metric files?
-- New alert rules?
-- New runbooks?
-- SLO adjustments?
-
-### 3.3 Update Expertise File
-
-Add to files section:
-```yaml
-files:
-  metrics:
-    - path: src/metrics/database.ts
-      purpose: "Database query metrics"
-```
-
-Add learning entry:
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Database connection pool needs prometheus-client custom collector"
-    files_affected:
-      - src/metrics/database.ts
-    context: "US-0120: Database monitoring"
-```
-
-Update `last_updated` date.
-
-### 3.4 Validate Update
-
-Ensure expertise.yaml:
-- Is valid YAML
-- All alerts have runbook references
-- SLO targets are current
-
----
-
-## Quick Reference
-
-### Before ANY Monitoring Work
-```
-1. Read expertise.yaml
-2. Check existing metrics and alerts
-3. Identify SLO targets
-4. Plan runbooks for new alerts
-```
-
-### After ANY Monitoring Work
-```
-1. Document new metrics
-2. Link alerts to runbooks
-3. Update SLO targets if changed
-4. Update expertise.yaml
-```
-
-### Metric Types (from expertise)
-- **Counter**: Cumulative (requests_total, errors_total)
-- **Gauge**: Current value (connections, queue_size)
-- **Histogram**: Distribution (duration, size)
-
-### Log Levels (from expertise)
-- **ERROR**: Service unavailable, data loss
-- **WARN**: Degraded, unexpected but handled
-- **INFO**: Important state changes
-- **DEBUG**: Diagnostic info (dev only)
-
----
-
-## Example: Complete Monitoring Implementation
-
-**Task**: Add API endpoint monitoring
-
-### Plan Phase
-```markdown
-From expertise:
-- RED metrics pattern (Rate, Errors, Duration)
-- SLO: p95 <200ms, error rate <0.1%
-- Every alert needs runbook
-
-Metrics:
-- http_request_total (counter)
-- http_request_duration_seconds (histogram)
-- http_request_errors_total (counter)
-
-Alerts:
-- HighLatency: p95 >200ms for 5 minutes
-- HighErrorRate: error rate >0.1% for 5 minutes
-
-Runbooks:
-- high-latency.md
-- high-error-rate.md
-```
-
-### Build Phase
-```markdown
-Created:
-- src/metrics/http.ts
-- monitoring/dashboards/api-overview.json
-- monitoring/alerts/api-alerts.yaml
-- monitoring/runbooks/high-latency.md
-- monitoring/runbooks/high-error-rate.md
-
-Discoveries:
-- Need request_id label for correlation
-- 5-minute window reduces alert noise
-- Should add endpoint label for drill-down
-```
-
-### Self-Improve Phase
-```yaml
-patterns:
-  - name: HTTP Metrics Middleware
-    description: "Collect RED metrics for all HTTP endpoints"
-    location: src/metrics/middleware.ts
-
-learnings:
-  - date: 2025-12-16
-    insight: "5-minute alerting window reduces transient spike noise by 80%"
-    files_affected:
-      - monitoring/alerts/api-alerts.yaml
-    context: "US-0121: API monitoring"
-
-# Updated SLO if needed:
-slo_targets:
-  latency_p95: "<200ms"
-  error_rate: "<0.1%"
-```
-
----
-
-This workflow ensures comprehensive observability and continuous improvement.

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

@@ -1,68 +0,0 @@
-domain: performance
-last_updated: 2025-12-21
-version: 1.1
-
-files:
-  benchmarks:
-    - path: benchmarks/
-      purpose: Performance benchmark files
-    - path: tests/performance/
-      purpose: Performance tests
-
-  profiling:
-    - path: .clinic/
-      purpose: Node.js profiling output
-    - path: profiles/
-      purpose: CPU/memory profiles
-
-  config:
-    - path: lighthouse.config.js
-      purpose: Lighthouse performance config
-    - path: webpack.config.js
-      purpose: Bundle optimization config
-
-relationships:
-  - metric_type: api_response_time
-    target: "<200ms p95"
-    measurement: "Load testing, APM"
-  - metric_type: page_load
-    target: "<3s LCP"
-    measurement: "Lighthouse, Core Web Vitals"
-  - metric_type: bundle_size
-    target: "<250KB gzipped"
-    measurement: "Webpack analyzer"
-  - metric_type: database_query
-    target: "<50ms p95"
-    measurement: "Query profiling"
-
-# Generic perf patterns (N+1, caching, lazy loading, indexing) omitted - models know these
-
-conventions:
-  - "Profile before optimizing (no premature optimization)"
-  - "Measure before and after every change"
-
-learnings:
-  - date: 2025-12-21
-    context: "AgileFlow status.json management"
-    learning: "Auto-archival system keeps status.json lean by moving completed stories >7 days old to monthly archives (docs/09-agents/archive/YYYY-MM.json). This prevents file bloat and improves agent processing speed. Configured in docs/00-meta/agileflow-metadata.json with threshold_days: 7."
-    impact: "Maintains fast status.json parsing even in long-running projects"
-
-  - date: 2025-12-21
-    context: "AgileFlow status.json compression"
-    learning: "/agileflow:compress command removes verbose fields (user_stories.*.description, user_stories.*.acceptance_criteria) from status.json. Use when file grows too large. Original data preserved in story files under docs/06-stories/."
-    impact: "Reduces status.json size by 60-80% when needed"
-
-  - date: 2025-12-21
-    context: "AgileFlow installation performance"
-    learning: "Dynamic content injection happens at install time, not runtime. Placeholders like {{AGENT_LIST}} in source files get replaced during 'npx agileflow setup'. This means zero runtime overhead - installed files are pre-rendered with current lists."
-    impact: "No template parsing overhead during Claude Code sessions"
-
-  - date: 2025-12-21
-    context: "AgileFlow expertise file sizing"
-    learning: "Keep expertise.yaml files under 200 lines each. Large expertise files slow down expert initialization. Split domains into focused experts (e.g., performance, security, architecture) rather than one monolithic file."
-    impact: "Faster expert loading, better maintainability"
-
-  - date: 2025-12-21
-    context: "AgileFlow agent model selection"
-    learning: "Most AgileFlow agents use Haiku model (not Opus/Sonnet) for cost-effectiveness and speed. Haiku is sufficient for focused tasks like status updates, story tracking, git operations. Reserve Opus for complex reasoning tasks."
-    impact: "90% cost reduction on routine agent operations while maintaining quality"

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

@@ -1,41 +0,0 @@
----
-description: Ask questions about performance - uses expertise for fast, accurate answers
-argument-hint: <your question>
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/performance/expertise.yaml
----
-
-# Performance Expert - Question
-
-You are an expert on the performance domain for this codebase.
-
-## CRITICAL: Expertise-First Workflow
-
-### Step 1: Load Your Expertise
-Read `{{EXPERTISE_FILE}}` FIRST.
-
-This contains:
-- Benchmark locations
-- Performance targets and metrics
-- Known bottlenecks
-- Optimization patterns
-
-### Step 2: Validate Against Actual Code
-Check if benchmark files exist.
-Note any discrepancies for self-improve.
-
-### Step 3: Answer the Question
-- Reference exact metrics and targets
-- Include profiling examples
-- If expertise was wrong, note it
-
-## Common Questions I Can Answer
-- What are the performance targets?
-- Where are the benchmarks?
-- What's causing slow response times?
-- How do I profile this code?
-- Is there an N+1 query here?
-
-## Question
-
-{{argument}}

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

@@ -1,45 +0,0 @@
----
-description: Update performance expertise after making changes
-argument-hint: [optional context about what changed]
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/performance/expertise.yaml
----
-
-# Performance Expert - Self-Improve
-
-Update your expertise file after performance changes.
-
-## Workflow
-
-### Step 1: Read Current Expertise
-Load `{{EXPERTISE_FILE}}`.
-
-### Step 2: Analyze What Changed
-```bash
-git diff HEAD~1 --name-only | grep -E "(benchmark|perf|cache|optim)"
-```
-
-### Step 3: Update Expertise
-
-**Update `files` if:** New benchmarks, profiling configs added
-**Update `relationships` if:** New metrics, targets changed
-**Update `patterns` if:** New optimization patterns
-**Update `bottlenecks` if:** New bottlenecks discovered/fixed
-
-### Step 4: Add Learnings Entry
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Optimized [what] - [before] → [after]"
-    files_affected: [list]
-    context: "{{argument}}"
-```
-
-### Step 5: Validate and Save
-- [ ] All paths exist
-- [ ] `last_updated` current
-- [ ] No duplicates
-
-## Context
-
-{{argument}}

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

@@ -1,61 +0,0 @@
----
-description: Plan, build, and improve performance with expertise-driven workflow
-argument-hint: <performance task description>
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/performance/expertise.yaml
----
-
-# Performance Expert: Plan → Build → Self-Improve
-
-## Step 1: PLAN
-
-### 1.1 Load Expertise
-Read `{{EXPERTISE_FILE}}` - know targets, bottlenecks, patterns.
-
-### 1.2 Profile First
-```bash
-# Measure baseline performance
-npm run benchmark
-```
-
-### 1.3 Create Plan
-```markdown
-## Performance Plan
-- Bottleneck identified: [what]
-- Current metric: [value]
-- Target metric: [value]
-- Optimization approach: [pattern]
-```
-
-## Step 2: BUILD
-
-### 2.1 Execute Plan
-- Apply optimization
-- Verify correctness
-- Measure improvement
-
-### 2.2 Capture Changes
-```bash
-git diff --name-only
-# Run benchmark again
-npm run benchmark
-```
-
-### 2.3 Validate
-- Behavior unchanged
-- Performance improved
-- No regressions
-
-## Step 3: SELF-IMPROVE
-
-### 3.1 Update Expertise
-- Document before/after metrics
-- Note successful patterns
-- Update bottleneck list
-
-### 3.2 Save
-Update `{{EXPERTISE_FILE}}` with learnings.
-
-## Performance Request
-
-{{argument}}

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

@@ -1,143 +0,0 @@
-# Product Expert - Domain Knowledge
-# This file is the agent's "mental model" of the product domain
-# AUTO-UPDATED by self-improve.md after completing work
-
-domain: product
-last_updated: 2025-12-21
-version: 1.1
-
-# AgileFlow-specific product management patterns (learned from actual codebase)
-files:
-  requirements:
-    - path: docs/05-epics/
-      purpose: "Epic definitions with goals and success metrics"
-      conventions: "EP-#### naming (e.g., EP-0001)"
-      example: "ep-0001-agent-expert-pilot.md"
-      sections:
-        - "Goal"
-        - "Problem Statement"
-        - "Solution"
-        - "Success Criteria"
-        - "Stories table"
-        - "Architecture Context"
-        - "Dependencies"
-        - "Risks"
-        - "Exit Criteria"
-    - path: docs/06-stories/
-      purpose: "User stories organized by epic"
-      conventions: "US-#### naming, Given/When/Then AC"
-    - path: docs/01-brainstorming/
-      purpose: "Early ideas and feature sketches"
-      conventions: "Informal, exploratory notes"
-
-  documentation:
-    - path: docs/08-project/roadmap.md
-      purpose: "Product roadmap and priorities"
-    - path: docs/08-project/backlog.md
-      purpose: "Feature backlog"
-    - path: CLAUDE.md
-      purpose: "Project context and conventions (internal, gitignored)"
-    - path: README.md
-      purpose: "Public project overview and getting started"
-
-  research:
-    - path: docs/10-research/
-      purpose: "Technical research to inform product decisions"
-      naming: "YYYYMMDD-slug.md format"
-      example_notes:
-        - "20251216-agent-experts-self-improving-agents.md"
-
-  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"
-
-relationships:
-  - parent: epics
-    child: stories
-    type: contains
-    notes: "Epics break down into 3-10 stories (EP-0001 had 6 stories)"
-  - parent: research
-    child: epics
-    type: informs
-    notes: "Research notes linked from epics (e.g., EP-0001 references research)"
-  - parent: roadmap
-    child: epics
-    type: prioritizes
-    notes: "Roadmap determines epic priorities"
-  - parent: status_json
-    child: stories
-    type: tracks
-    notes: "status.json is single source of truth for story state"
-
-patterns:
-  - name: User Story Format
-    description: "As a [role], I want [action], so that [benefit]"
-    location: docs/06-stories/
-    example: "As a new user, I want to sign up with email, so that I can access my account"
-
-  - name: Acceptance Criteria
-    description: "Given/When/Then format for testable criteria"
-    location: docs/06-stories/
-    example: "Given a new user, When they submit signup, Then account is created"
-
-  - name: Definition of Ready
-    description: "Story has AC, test stub, no blockers, architecture context"
-    location: docs/09-agents/status.json
-    example: "status: ready"
-    checklist:
-      - "Acceptance Criteria written (Given/When/Then)"
-      - "Architecture Context with source citations"
-      - "Test stub at docs/07-testing/test-cases/<US_ID>.md"
-      - "Dependencies resolved and documented"
-
-  - name: Epic Story Table
-    description: "Markdown table in epic with ID, Title, Owner, Status, Estimate"
-    location: docs/05-epics/
-    example: "| US-0001 | Expert Directory Structure | AG-DEVOPS | ready | 2h |"
-
-  - name: Hour-Based Estimates
-    description: "Stories estimated in hours not days"
-    location: docs/05-epics/, docs/09-agents/status.json
-    range: "2h-3h typical for a story"
-
-  - name: Research-Informed Planning
-    description: "Epics reference research notes with relative links"
-    location: docs/05-epics/
-    example: "See [Research](../10-research/20251216-agent-experts.md)"
-
-conventions:
-  - "User stories must have clear benefit (the 'so that' clause)"
-  - "Acceptance criteria in Given/When/Then format"
-  - "Include edge cases and error scenarios"
-  - "Stories typically 2-3 hours (not days)"
-  - "Link research notes to epics with relative paths"
-  - "Document scope (in/out of feature) in epic"
-  - "status.json is single source of truth for story tracking"
-  - "Exit criteria checklist at bottom of epic"
-  - "Test status tracked per story (passing/failing/not_run)"
-  - "Agent owner assigned to each story (AG-UI, AG-API, AG-DEVOPS, etc.)"
-
-# Learned from AgileFlow codebase exploration
-learnings:
-  - date: 2025-12-21
-    context: "Analyzed EP-0001 epic structure"
-    insight: "Epics include Goal, Problem Statement, Solution, Success Criteria, Stories table, Architecture Context, Dependencies, Risks, Exit Criteria"
-    source: "docs/05-epics/ep-0001-agent-expert-pilot.md"
-
-  - date: 2025-12-21
-    context: "Analyzed story tracking workflow"
-    insight: "Stories tracked in status.json with owner, status, priority, estimate, depends_on, test_status fields; 'done' status with test_status: passing"
-    source: "docs/09-agents/status.json"
-
-  - date: 2025-12-21
-    context: "Analyzed research-to-epic flow"
-    insight: "Research notes (docs/10-research/) inform epic planning; epics link to research with relative paths"
-    source: "docs/05-epics/ep-0001-agent-expert-pilot.md"
-
-  - date: 2025-12-21
-    context: "Analyzed estimation patterns"
-    insight: "Stories use hour-based estimates (2h, 3h) not day-based; EP-0001 had 6 stories totaling ~15 hours"
-    source: "docs/05-epics/ep-0001-agent-expert-pilot.md"

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