agileflow 3.4.2 → 4.0.0-alpha.1

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

@@ -1,74 +0,0 @@
-# Analytics Expert - Question Workflow
-
-**Purpose**: Answer questions about analytics and event tracking using expertise-first approach.
-
-## Workflow
-
-### Step 1: Load Expertise
-```
-Read: packages/cli/src/core/experts/analytics/expertise.yaml
-```
-
-Parse the expertise file to understand:
-- Known tracking file locations
-- Event naming conventions
-- Event categories and schemas
-- Key metrics definitions
-- Privacy and consent patterns
-
-### Step 2: Validate Against Codebase
-
-Before answering, verify expertise is current:
-1. Check if mentioned files/directories exist
-2. Spot-check event catalog
-3. Verify tracking implementation exists
-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 event naming conventions
-- Include privacy considerations
-- 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 event discovered: [event_name]
-- Metric not documented: [metric]
-- Schema changed: [event]
-```
-
-## Example Usage
-
-**Question**: "How do we track button clicks?"
-
-**Expertise-First Answer**:
-1. Check expertise.yaml → patterns → Event Tracking Facade
-2. Check event_categories → user_actions → button_clicked
-3. Answer: "Use `analytics.track('button_clicked', { button_name: 'signup' })`. The tracking facade is in `src/analytics/`. Follow snake_case naming convention."
-
-**Question**: "What are our key retention metrics?"
-
-**Expertise-First Answer**:
-1. Check expertise.yaml → key_metrics → retention
-2. List: day_1_retention, day_7_retention, day_30_retention, churn_rate
-3. Answer with definitions and where dashboards are defined
-
-## Key Principles
-
-1. **Expertise First**: Always check expertise.yaml before searching
-2. **Privacy Focus**: Always mention consent requirements and PII restrictions
-3. **Naming Conventions**: Enforce object_action snake_case naming
-4. **Learn**: Note gaps for self-improve to fill later

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

@@ -1,163 +0,0 @@
-# Analytics Expert - Self-Improve Workflow
-
-**Purpose**: Automatically update expertise.yaml after completing analytics work.
-
-## When to Run
-
-Run this workflow after:
-- Adding new event tracking
-- Creating new metrics or dashboards
-- Updating event schemas
-- Implementing new analytics features
-- Discovering privacy or data quality issues
-
-## Workflow
-
-### Step 1: Load Current Expertise
-```
-Read: packages/cli/src/core/experts/analytics/expertise.yaml
-```
-
-### Step 2: Analyze Changes Made
-
-Review what was just implemented:
-1. What new events were added?
-2. What dashboards or metrics were created?
-3. What schemas were defined?
-4. What privacy considerations were addressed?
-5. What was learned during implementation?
-
-### Step 3: Generate Diff
-
-Identify what's new or changed:
-- New events not in event_categories
-- New metrics not in key_metrics
-- Schema changes
-- New tracking patterns
-- Privacy or compliance updates
-
-### 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 event_categories if new events added:
-```yaml
-event_categories:
-  category_name:
-    - new_event_added
-```
-
-### Step 5: Validate Update
-
-Ensure the expertise file:
-- Is valid YAML
-- Has updated `last_updated` date
-- All events follow naming convention
-- Privacy considerations documented
-
-## Learning Categories
-
-### New Events
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Added checkout funnel events: cart_viewed, checkout_started, payment_submitted"
-    files_affected:
-      - src/analytics/events/checkout.ts
-      - src/analytics/schemas/checkout.ts
-    context: "US-0070: Checkout funnel tracking"
-
-# Also update event_categories:
-event_categories:
-  conversions:
-    - cart_viewed
-    - checkout_started
-    - payment_submitted
-    - purchase_completed
-```
-
-### Dashboard Learnings
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Retention cohort dashboard requires BigQuery for performance"
-    files_affected: [docs/analytics/dashboards/retention.md]
-    context: "US-0071: Build retention dashboard"
-```
-
-### Schema Discoveries
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Event properties exceeding 100 keys cause Amplitude to drop events"
-    files_affected: [src/analytics/schemas/validation.ts]
-    context: "US-0072: Fix event validation"
-```
-
-### Privacy Insights
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Must hash user_id before sending to analytics per GDPR requirements"
-    files_affected:
-      - src/analytics/privacy.ts
-      - src/analytics/providers/AmplitudeProvider.ts
-    context: "US-0073: GDPR compliance update"
-```
-
-### A/B Testing Learnings
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Need minimum 10k users per variant for statistical significance on conversion"
-    files_affected: [docs/analytics/ab-testing.md]
-    context: "US-0074: Set up A/B test framework"
-```
-
-## Example Update
-
-Before work:
-```yaml
-event_categories:
-  user_actions:
-    - button_clicked
-    - form_submitted
-```
-
-After adding search tracking:
-```yaml
-event_categories:
-  user_actions:
-    - button_clicked
-    - form_submitted
-  search:
-    - search_performed
-    - search_result_clicked
-    - search_filter_applied
-    - search_no_results
-
-learnings:
-  - date: 2025-12-16
-    insight: "Search events need query_length and result_count for analysis"
-    files_affected:
-      - src/analytics/events/search.ts
-      - src/analytics/schemas/search.ts
-    context: "US-0075: Implement search analytics"
-```
-
-## Key Principles
-
-1. **Event Naming**: Always use object_action snake_case format
-2. **Privacy First**: Note any PII handling or consent requirements
-3. **Schema Validation**: Document any schema constraints discovered
-4. **Data Quality**: Note validation rules and data quality checks
-5. **GDPR Compliance**: Always document privacy implications

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

@@ -1,272 +0,0 @@
-# Analytics Expert - Complete Workflow
-
-**Purpose**: End-to-end workflow for implementing analytics tracking 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/analytics/expertise.yaml
-```
-
-Parse and internalize:
-- Known tracking file locations
-- Event naming conventions (object_action snake_case)
-- Existing event categories
-- Key metrics definitions
-- Privacy and consent patterns
-
-### 1.2 Validate Expertise Against Codebase
-
-Before planning, verify expertise is current:
-```bash
-# Check analytics implementation exists
-ls src/analytics/
-ls src/analytics/events/
-```
-
-Note any discrepancies for later update.
-
-### 1.3 Create Detailed Plan
-
-With expertise loaded, create implementation plan:
-
-1. **Check existing event categories** (from expertise)
-2. **Follow naming convention** (object_action snake_case)
-3. **Define event schema** with required properties
-4. **Plan privacy compliance** (consent check, no PII)
-
-Example Plan:
-```markdown
-## Implementation Plan: Add Search Analytics
-
-### From Expertise:
-- Tracking facade: src/analytics/
-- Event schemas: src/analytics/schemas/
-- Naming convention: object_action snake_case
-- Privacy: Check consent before tracking
-
-### Events to Add:
-- search_performed
-- search_result_clicked
-- search_filter_applied
-- search_no_results
-
-### Schema Definition:
-```typescript
-{
-  event_name: 'search_performed',
-  properties: {
-    query: string,           // Search query (anonymized)
-    result_count: number,
-    filter_count: number,
-    search_type: 'global' | 'scoped'
-  }
-}
-```
-
-### Implementation Steps:
-1. Define event schemas in src/analytics/schemas/search.ts
-2. Add events to catalog in src/analytics/events/search.ts
-3. Implement tracking calls in search components
-4. Verify consent check before tracking
-5. Test events in development
-```
-
----
-
-## Step 2: Build (Execute Plan)
-
-### 2.1 Execute Implementation
-
-Follow the plan exactly:
-- Use event naming convention from expertise
-- Apply consent pattern from expertise
-- Follow schema validation pattern
-
-### 2.2 Handle Discoveries
-
-If you discover something not in expertise:
-```markdown
-## Discovery Log
-- Found: Amplitude has 100 property limit per event
-- Pattern: Need to aggregate before sending
-- Gotcha: User ID must be hashed for GDPR compliance
-```
-
-### 2.3 Privacy Checklist
-
-Per expertise conventions:
-- ✅ Consent checked before tracking
-- ✅ No PII in event properties
-- ✅ User ID hashed/anonymous
-- ✅ Event schema validated
-- ✅ Documented in event catalog
-
-### 2.4 Capture Changes
-
-Document what was actually changed:
-```markdown
-## Changes Made
-- Created: src/analytics/schemas/search.ts
-- Created: src/analytics/events/search.ts
-- Modified: src/components/SearchBar.tsx (added tracking)
-- Updated: docs/analytics/events.md (documented new events)
-```
-
----
-
-## Step 3: Self-Improve (Update Expertise)
-
-### 3.1 Load Current Expertise
-```
-Read: packages/cli/src/core/experts/analytics/expertise.yaml
-```
-
-### 3.2 Identify Updates Needed
-
-Compare discoveries with current expertise:
-- New event categories to add?
-- New metrics defined?
-- Privacy learnings?
-- Schema constraints discovered?
-
-### 3.3 Update Expertise File
-
-Add to event_categories:
-```yaml
-event_categories:
-  search:
-    - search_performed
-    - search_result_clicked
-    - search_filter_applied
-    - search_no_results
-```
-
-Add learning entry:
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Search events need query_length (not full query) to avoid PII"
-    files_affected:
-      - src/analytics/schemas/search.ts
-      - src/analytics/events/search.ts
-    context: "US-0110: Search analytics implementation"
-```
-
-Update `last_updated` date.
-
-### 3.4 Validate Update
-
-Ensure expertise.yaml:
-- Is valid YAML
-- All events follow naming convention
-- Privacy considerations documented
-
----
-
-## Quick Reference
-
-### Before ANY Analytics Work
-```
-1. Read expertise.yaml
-2. Check existing event_categories
-3. Follow naming convention
-4. Plan privacy compliance
-```
-
-### After ANY Analytics Work
-```
-1. Add new events to categories
-2. Document any privacy considerations
-3. Note schema constraints
-4. Update expertise.yaml
-```
-
-### Event Naming Convention (from expertise)
-- Format: `object_action` in `snake_case`
-- Examples: `button_clicked`, `form_submitted`, `page_viewed`
-- DO NOT: `buttonClick`, `FormSubmit`, `pageView`
-
-### Privacy Conventions (from expertise)
-- NEVER track PII (email, name, phone)
-- ALWAYS check consent before tracking
-- Hash user IDs before sending
-- Validate events against schema
-
----
-
-## Example: Complete Analytics Implementation
-
-**Task**: Track checkout funnel
-
-### Plan Phase
-```markdown
-From expertise:
-- Event categories exist for conversions
-- Must follow object_action naming
-- Need consent check
-
-Events to add:
-- cart_viewed
-- checkout_started
-- payment_method_selected
-- payment_submitted
-- purchase_completed
-- purchase_failed
-```
-
-### Build Phase
-```markdown
-Created:
-- src/analytics/events/checkout.ts
-- src/analytics/schemas/checkout.ts
-
-Properties tracked:
-- cart_total (number, not amount string)
-- item_count (number)
-- payment_method (string, e.g., 'card', 'paypal')
-- currency (string, ISO code)
-
-Discoveries:
-- Need to track cart_id for funnel correlation
-- Should track time_in_step for optimization
-```
-
-### Self-Improve Phase
-```yaml
-event_categories:
-  conversions:
-    - cart_viewed
-    - checkout_started
-    - payment_method_selected
-    - payment_submitted
-    - purchase_completed
-    - purchase_failed
-
-key_metrics:
-  conversion:
-    - cart_to_checkout_rate
-    - checkout_completion_rate
-    - payment_success_rate
-
-learnings:
-  - date: 2025-12-16
-    insight: "Checkout funnel needs cart_id to correlate events across sessions"
-    files_affected:
-      - src/analytics/events/checkout.ts
-      - src/analytics/schemas/checkout.ts
-    context: "US-0111: Checkout funnel tracking"
-```
-
----
-
-This workflow ensures privacy-compliant analytics and continuous improvement.

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

@@ -1,124 +0,0 @@
-# API Expert - Mental Model
-#
-# This file represents the agent's understanding of API patterns.
-# Populated with AgileFlow-specific CLI architecture knowledge.
-#
-# NOT a source of truth - always validate against actual code.
-
-domain: api
-last_updated: 2025-12-21
-version: 1.1
-
-# AgileFlow CLI architecture (not a web API - it's a Node.js CLI tool)
-files:
-  cli_entry:
-    - path: packages/cli/tools/agileflow-npx.js
-      purpose: Main CLI entry point (npx agileflow)
-      role: "Routes to agileflow-cli.js for command execution"
-    - path: packages/cli/tools/cli/agileflow-cli.js
-      purpose: Command router using Commander.js
-      pattern: "Dynamically loads commands from commands/ directory"
-
-  commands:
-    - path: packages/cli/tools/cli/commands/
-      purpose: CLI command implementations
-      pattern: "<command>.js exports {name, description, options, action}"
-      examples:
-        - "setup.js - Interactive installation wizard"
-        - "status.js - Show installation status"
-        - "doctor.js - Diagnose and auto-fix issues"
-        - "list.js - List installed components"
-        - "update.js - Update AgileFlow version"
-        - "uninstall.js - Remove AgileFlow"
-        - "config.js - Manage configuration"
-
-  lib_utilities:
-    - path: packages/cli/tools/cli/lib/ui.js
-      purpose: CLI UI utilities (logo, prompts, colors)
-      exports: [displayLogo, displaySection, success, warning, error, info, promptInstall, confirm]
-    - path: packages/cli/tools/cli/lib/version-checker.js
-      purpose: npm version checking for updates
-      exports: [checkForUpdate, getCurrentVersion]
-    - path: packages/cli/tools/cli/lib/content-injector.js
-      purpose: Dynamic placeholder replacement (agent lists, command lists)
-    - path: packages/cli/tools/cli/lib/docs-setup.js
-      purpose: Documentation structure creation
-    - path: packages/cli/tools/cli/lib/npm-utils.js
-      purpose: npm package utilities
-
-  installers:
-    - path: packages/cli/tools/cli/installers/core/installer.js
-      purpose: Core installation logic (Installer class)
-      key_methods: [install, getStatus, countInstalledItems]
-    - path: packages/cli/tools/cli/installers/ide/
-      purpose: IDE-specific installers (Claude Code, Cursor, Windsurf)
-
-relationships:
-  - name: command_structure
-    pattern: "Each command exports {name, description, options, action}"
-    loader: "agileflow-cli.js dynamically loads from commands/"
-
-  - name: ui_consistency
-    lib: "lib/ui.js"
-    usage: "All commands use same displayLogo, success, warning, error functions"
-
-  - name: installer_flow
-    entry: "setup.js"
-    core: "installers/core/installer.js"
-    ide: "installers/ide/manager.js"
-
-patterns:
-  - name: Commander.js CLI
-    description: "Commands defined as objects with name, description, options, action"
-    library: "commander"
-    pattern: "program.command(name).description(...).option(...).action(...)"
-
-  - name: Async Actions
-    description: "All command actions are async functions"
-    pattern: "action: async (options) => { ... }"
-
-  - name: Error Handling
-    description: "Try-catch with chalk.red error display"
-    pattern: "try { ... } catch (err) { console.error(chalk.red('Error:'), err.message) }"
-
-  - name: Spinner Progress
-    description: "ora spinners for long operations"
-    library: "ora"
-    pattern: "const spinner = ora('...').start(); ... spinner.stop();"
-
-  - name: Dynamic Loading
-    description: "Commands dynamically loaded from directory"
-    location: "agileflow-cli.js"
-    pattern: "fs.readdirSync(commandsPath).filter(f => f.endsWith('.js'))"
-
-conventions:
-  - "Commands export {name, description, options, action}"
-  - "Use chalk for colored output (green=success, yellow=warning, red=error)"
-  - "Use ora spinners for async operations"
-  - "Use inquirer for interactive prompts"
-  - "All actions are async functions"
-  - "Exit with process.exit(0) on success, process.exit(1) on error"
-  - "Support --directory option for project path"
-  - "Use fs-extra for filesystem operations"
-
-# Learned from AgileFlow codebase exploration
-learnings:
-  - date: 2025-12-21
-    context: "Analyzed AgileFlow CLI architecture"
-    insight: "AgileFlow is a Node.js CLI tool using Commander.js, not a REST API"
-    source: "packages/cli/tools/"
-
-  - date: 2025-12-21
-    context: "Analyzed command structure"
-    insight: "7 CLI commands (setup, status, doctor, list, update, uninstall, config) dynamically loaded"
-    source: "packages/cli/tools/cli/commands/"
-
-  - date: 2025-12-21
-    context: "Analyzed lib utilities"
-    insight: "Shared UI utilities (ui.js), version checking (version-checker.js), content injection (content-injector.js)"
-    source: "packages/cli/tools/cli/lib/"
-
-  - date: 2025-12-21
-    context: "Analyzed installer pattern"
-    insight: "Core Installer class with install, getStatus, countInstalledItems methods; IDE-specific installers for Claude/Cursor/Windsurf"
-    source: "packages/cli/tools/cli/installers/"

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

@@ -1,74 +0,0 @@
----
-description: Ask questions about API - uses expertise for fast, accurate answers
-argument-hint: <your question about endpoints, auth, validation, patterns>
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/api/expertise.yaml
----
-
-# API Expert - Question
-
-You are an expert on the API 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:
-- Route/controller file locations
-- Middleware structure
-- Endpoint registry (if populated)
-- Auth and validation patterns
-- API conventions
-- 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 the question being asked:
-1. Check if referenced routes/controllers exist where expertise says
-2. Verify auth patterns match actual middleware
-3. Confirm validation schemas are as documented
-4. 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 and endpoint details
-3. If expertise was wrong/stale, note it in your answer
-4. If you don't know, say so (don't guess about API contracts)
-
-## API-Specific Guidance
-
-### Endpoint Questions
-- Reference the exact route file from expertise
-- Include HTTP method, path, auth requirements
-- Show request/response schema if available
-
-### Authentication Questions
-- Reference middleware location from expertise
-- Explain the auth flow (JWT, session, API key)
-- Note which endpoints require auth
-
-### Validation Questions
-- Reference schema file locations
-- Show validation rules and error responses
-- Note which library is used (Zod, Yup, etc.)
-
-### Error Handling Questions
-- Reference error middleware from expertise
-- Show error response format
-- Explain status code usage
-
-## Key Principles
-
-- **Speed**: Use expertise to skip unnecessary searching
-- **Accuracy**: Always validate against actual route files
-- **Honesty**: Acknowledge when expertise is stale
-- **Security**: Never expose sensitive patterns publicly
-
-## Question
-
-{{argument}}