agileflow 3.4.2 → 4.0.0-alpha.1

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

@@ -1,122 +0,0 @@
----
-description: Update API expertise after making endpoint/middleware changes
-argument-hint: [optional context about what changed]
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/api/expertise.yaml
----
-
-# API Expert - Self-Improve
-
-You are updating your mental model (expertise file) to reflect API changes. 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:
-- Route file locations
-- Middleware structure
-- Endpoint registry
-- Auth patterns
-
-### Step 2: Analyze What Changed
-Identify API changes using:
-
-**Check git diff for API files:**
-```bash
-git diff HEAD~1 --name-only | grep -E "(api|routes|controllers|middleware|schemas)"
-```
-
-**Look for:**
-- New endpoints added
-- Auth requirements changed
-- New middleware introduced
-- Validation schemas updated
-- Response formats changed
-
-### Step 3: Update Expertise
-
-**Update `files` section if:**
-- New route/controller files added
-- File structure reorganized
-- New middleware introduced
-
-**Update `relationships` (endpoint registry) if:**
-- New endpoints created
-- Endpoints modified or removed
-- Auth requirements changed
-
-Example addition:
-```yaml
-relationships:
-  - endpoint: "POST /api/sessions"
-    controller: SessionController.create
-    auth_required: false
-    validation: loginSchema
-    rate_limited: true
-```
-
-**Update `patterns` section if:**
-- New auth pattern introduced
-- Validation approach changed
-- Error handling updated
-- New API conventions adopted
-
-**Update `conventions` section if:**
-- Response format changed
-- New headers required
-- Naming conventions updated
-
-**ALWAYS add to `learnings` section:**
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Added rate limiting to public auth endpoints"
-    files_affected:
-      - src/api/middleware/rateLimit.ts
-      - src/api/routes/auth.routes.ts
-    context: "US-0050 - Security improvements"
-```
-
-### Step 4: Validate Updated Model
-After updating, verify:
-1. All route file paths still exist
-2. Endpoint registry matches actual routes
-3. Auth patterns match middleware code
-4. Conventions reflect current practice
-
-### Step 5: Write Updated Expertise
-Save the updated expertise.yaml file with:
-- Updated `last_updated` timestamp
-- New/modified sections
-- New learnings entry
-
-## API-Specific Rules
-
-### DO:
-- Track all public endpoints
-- Note auth requirements per endpoint
-- Record validation patterns
-- Document rate limiting
-- Update when API version changes
-
-### DON'T:
-- Store API keys or secrets
-- Include sensitive business logic details
-- Keep deprecated endpoint references
-- Document internal-only implementation details
-
-## Quality Checklist
-
-Before saving:
-- [ ] `last_updated` is today's date
-- [ ] All route file paths verified
-- [ ] Endpoint registry accurate
-- [ ] New learnings entry added
-- [ ] No references to removed endpoints
-- [ ] Expertise stays focused (<200 lines)
-
-## Context
-
-{{argument}}

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

@@ -1,248 +0,0 @@
----
-description: Plan, build, and improve API feature with expertise-driven workflow
-argument-hint: <API feature description>
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/api/expertise.yaml
----
-
-# API Expert: Plan → Build → Self-Improve
-
-You are executing a complete API feature implementation with automatic knowledge capture. This workflow ensures you leverage existing API 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:
-- Route file locations and patterns
-- Controller/handler structure
-- Middleware chain
-- Authentication patterns
-- Response format conventions
-- Recent learnings that might apply
-
-### 1.2 Validate Against Codebase
-Before planning, verify your expertise is accurate:
-
-```bash
-# Check API route files exist
-ls -la src/api/ src/routes/ app/api/ pages/api/ 2>/dev/null || true
-
-# Check for recent API changes
-git log --oneline -5 -- "**/*api*" "**/*route*" "**/controller*" 2>/dev/null || true
-```
-
-Note any discrepancies between expertise and actual state.
-
-### 1.3 Create Implementation Plan
-Based on validated expertise, create a specific plan:
-
-```markdown
-## API Implementation Plan
-
-### Endpoints to Create/Modify
-1. [METHOD] [/path] - [purpose]
-   - Request: [body/params schema]
-   - Response: [response schema]
-   - Auth: [required auth level]
-
-### Files to Create/Modify
-- [route file path]
-- [controller/handler path]
-- [validation schema path]
-- [types/interfaces path]
-
-### Pattern to Follow
-[Reference specific pattern from expertise - e.g., "Use REST conventions from /users endpoints"]
-
-### Middleware Required
-- [auth middleware if needed]
-- [validation middleware]
-- [rate limiting if applicable]
-
-### Validation
-- [ ] Endpoint responds correctly
-- [ ] Auth enforced properly
-- [ ] Error responses follow format
-- [ ] Types are accurate
-```
-
-**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 referenced middleware exists
-- Verify auth patterns are in place
-- Check for route conflicts
-
-### 2.2 Execute the Plan
-Follow your implementation plan:
-
-**Create route file:**
-```typescript
-// Follow existing route patterns from expertise
-// Use consistent naming conventions
-// Apply required middleware
-```
-
-**Create handler/controller:**
-```typescript
-// Follow controller pattern from expertise
-// Use proper error handling
-// Return consistent response format
-```
-
-### 2.3 Capture Changes
-After building, document what changed:
-
-```bash
-# Capture the diff for self-improve
-git diff --name-only | grep -E "(api|route|controller|handler)"
-git diff HEAD
-```
-
-### 2.4 Validate Build
-Verify the implementation:
-- Endpoint responds to requests
-- Auth works as expected
-- Validation catches invalid input
-- Types compile without errors
-
-**Output**: Working API endpoint(s) 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 endpoints added
-- New route files created
-- New middleware applied
-- New response patterns used
-- New validation schemas
-
-### 3.2 Update Expertise File
-Read and update `{{EXPERTISE_FILE}}`:
-
-**Update `files` section if:**
-```yaml
-files:
-  routes:
-    - path: path/to/new/route.ts
-      purpose: "New endpoint for [feature]"
-```
-
-**Update `relationships` section if:**
-```yaml
-relationships:
-  - route: /api/v1/new-resource
-    controller: NewResourceController
-    methods: [GET, POST]
-    auth: required
-```
-
-**Update `patterns` section if:**
-New pattern discovered or confirmed.
-
-**Update `conventions` section if:**
-New naming or structural conventions applied.
-
-### 3.3 Add Learnings Entry
-**ALWAYS** add a new learnings entry:
-
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Added [endpoint] for [purpose]"
-    files_affected:
-      - path/to/route
-      - path/to/controller
-    context: "Feature: {{argument}}"
-```
-
-### 3.4 Validate Updated Expertise
-Before saving:
-- [ ] All file paths exist
-- [ ] Routes match actual endpoints
-- [ ] `last_updated` is current
-- [ ] No duplicate endpoint entries
-- [ ] File stays focused (<200 lines)
-
-### 3.5 Save Expertise
-Write the updated expertise.yaml file.
-
----
-
-## API-Specific Error Handling
-
-### If Route Conflicts
-- Check for duplicate paths
-- Verify HTTP methods don't conflict
-- Check route ordering (specific before general)
-
-### If Auth Fails
-- Verify middleware is applied
-- Check auth token handling
-- Verify permissions are correct
-
-### If Validation Fails
-- Check schema matches request
-- Verify required fields
-- Check type coercion
-
----
-
-## Example Usage
-
-**Request**: "Add endpoint to fetch user sessions"
-
-**Step 1 Output** (Plan):
-```markdown
-## API Implementation Plan
-
-### Endpoints to Create/Modify
-1. GET /api/v1/users/:id/sessions - List user sessions
-   - Request: { params: { id: string }, query: { limit?, offset? } }
-   - Response: { sessions: Session[], total: number }
-   - Auth: required (own user or admin)
-
-### Files to Create/Modify
-- src/api/v1/users/[id]/sessions/route.ts
-- src/types/session.ts (if needed)
-
-### Pattern to Follow
-Using nested resource pattern from /users/:id/posts
-Using pagination pattern from /users endpoint
-```
-
-**Step 2 Output** (Build):
-- Created route file at src/api/v1/users/[id]/sessions/route.ts
-- Added Session type to types
-- Applied auth middleware
-- Diff: 2 files changed
-
-**Step 3 Output** (Self-Improve):
-- Added sessions endpoint to routes list
-- Added learning: "Added nested sessions endpoint under users"
-
----
-
-## Feature Request
-
-{{argument}}

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

@@ -1,106 +0,0 @@
-domain: ci
-last_updated: 2025-12-21
-version: 1.1
-
-# AgileFlow-specific CI/CD configuration (learned from actual codebase)
-files:
-  workflows:
-    - path: .github/workflows/npm-publish.yml
-      purpose: Automated npm publish on git tag
-      trigger: "push to tags matching v*.*.*"
-      jobs: ["publish-npm"]
-      key_steps:
-        - "Checkout repository"
-        - "Setup Node.js 18 with npm registry"
-        - "Extract version from tag"
-        - "Verify package.json version matches tag"
-        - "Install dependencies (if package-lock.json exists)"
-        - "Publish to npm with NPM_TOKEN secret"
-        - "Generate summary report"
-      secrets: ["NPM_TOKEN"]
-
-  config:
-    - path: packages/cli/package.json
-      purpose: Main package config with scripts
-      key_scripts:
-        - "postinstall: node tools/postinstall.js"
-        - "agileflow: node tools/agileflow-npx.js"
-        - "lint: (not configured yet)"
-        - "test: (not configured yet)"
-    - path: .npmrc
-      purpose: npm config (local, gitignored)
-
-  validation:
-    - path: scripts/validate-expertise.sh
-      purpose: Validate agent expertise files
-      checks:
-        - "File existence"
-        - "YAML validity"
-        - "Learnings populated"
-        - "Staleness (age of last_updated)"
-    - path: scripts/expertise-metrics.sh
-      purpose: Dashboard for expertise health
-
-relationships:
-  - name: tag_triggers_publish
-    trigger: "git tag v*.*.*"
-    workflow: ".github/workflows/npm-publish.yml"
-    action: "Publish to npm registry"
-
-  - name: version_verification
-    step: "Verify package.json version matches tag"
-    files: ["packages/cli/package.json"]
-    failure_action: "Exit with error, block publish"
-
-  - name: secret_management
-    secret: "NPM_TOKEN"
-    location: "GitHub Secrets"
-    usage: "npm publish --access public"
-
-patterns:
-  - name: Tag-Based Release
-    description: "Git tags v*.*.* trigger GitHub Actions"
-    workflow_file: ".github/workflows/npm-publish.yml"
-
-  - name: Version Verification
-    description: "CI verifies package.json matches tag before publish"
-    prevents: "Mismatched version numbers"
-
-  - name: Conditional Install
-    description: "Only run npm ci if package-lock.json exists"
-    avoids: "Unnecessary install step"
-
-  - name: GitHub Step Summary
-    description: "Workflow outputs summary to GITHUB_STEP_SUMMARY"
-    provides: "Visible publish confirmation in Actions UI"
-
-conventions:
-  - "Trigger workflows on tag push (v*.*.*), not branch push"
-  - "Verify version matches between package.json and git tag"
-  - "Use NPM_TOKEN from GitHub Secrets (never commit)"
-  - "Publish with --access public for scoped packages"
-  - "Generate GITHUB_STEP_SUMMARY for visibility"
-  - "Node.js 18 is the target runtime"
-  - "Monorepo: publish from packages/cli/ directory"
-
-# Learned from AgileFlow codebase exploration
-learnings:
-  - date: 2025-12-21
-    context: "Analyzed npm-publish.yml workflow"
-    insight: "Workflow verifies package.json version matches tag before publishing to prevent mismatches"
-    source: ".github/workflows/npm-publish.yml"
-
-  - date: 2025-12-21
-    context: "Analyzed CI trigger pattern"
-    insight: "Uses tag-based publishing (v*.*.*) rather than branch push - cleaner release control"
-    source: ".github/workflows/npm-publish.yml"
-
-  - date: 2025-12-21
-    context: "Analyzed monorepo structure"
-    insight: "npm publish runs from packages/cli/ (working-directory), not root"
-    source: ".github/workflows/npm-publish.yml"
-
-  - date: 2025-12-21
-    context: "Analyzed validation tooling"
-    insight: "validate-expertise.sh and expertise-metrics.sh provide CI-style checks for agent expertise files"
-    source: "scripts/"

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

@@ -1,69 +0,0 @@
----
-description: Ask questions about CI/CD - uses expertise for fast, accurate answers
-argument-hint: <your question>
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/ci/expertise.yaml
----
-
-# CI Expert - Question
-
-You are an expert on the CI/CD 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:
-- Workflow file locations (.github/workflows/, etc.)
-- CI platform (GitHub Actions, GitLab CI, Jenkins, etc.)
-- Jobs and their triggers
-- Caching and optimization patterns
-- 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 workflow files exist at expected locations
-2. Verify CI platform matches expertise
-3. Check job configurations are current
-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 workflow files
-3. Include YAML examples for CI configurations
-4. If expertise was wrong, note it in your answer
-5. If you don't know, say so (don't guess)
-
-## CI-Specific Knowledge
-
-**CI Platforms**:
-- GitHub Actions: .github/workflows/*.yml
-- GitLab CI: .gitlab-ci.yml
-- Jenkins: Jenkinsfile
-- CircleCI: .circleci/config.yml
-
-**Common Questions I Can Answer**:
-- What CI platform is used?
-- Where are the workflow files?
-- What jobs run on PR?
-- How do I add a new job?
-- Why is CI failing?
-- How do I fix flaky CI?
-
-## 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
-- Recommending CI patterns not used in this project
-
-## Question
-
-{{argument}}

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

@@ -1,100 +0,0 @@
----
-description: Update CI expertise after making changes
-argument-hint: [optional context about what changed]
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/ci/expertise.yaml
----
-
-# CI 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:
-- Workflow file locations
-- CI platform and jobs
-- Caching patterns
-- Quality tools
-
-### 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 "(workflow|ci|\.github|gitlab|jenkins|eslint|prettier|tsconfig)"
-```
-
-**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 workflows added
-- Config files relocated
-- New quality tools configured
-
-**Update `relationships` section if:**
-- New jobs added to workflows
-- Job triggers changed
-- New tools integrated
-
-**Update `patterns` section if:**
-- New caching strategies
-- New optimization patterns
-- Better workflow structures
-
-**Update `conventions` section if:**
-- Build time targets changed
-- Required checks updated
-- New quality standards
-
-### Step 4: Add Learnings Entry
-**ALWAYS** add a new learnings entry:
-
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Brief description of what was learned"
-    files_affected:
-      - .github/workflows/ci.yml
-    context: "Feature: {{argument}}"
-```
-
-### Step 5: Validate Updated Expertise
-Before saving:
-- [ ] All workflow paths exist
-- [ ] Job configurations accurate
-- [ ] `last_updated` is current
-- [ ] No duplicate entries
-- [ ] File stays focused (<200 lines)
-
-### Step 6: Save Expertise
-Write the updated expertise.yaml file.
-
-## CI-Specific Updates
-
-**After adding new workflow:**
-- Add to workflows files list
-- Document triggers and jobs
-- Note any new patterns
-
-**After optimizing CI:**
-- Update patterns with optimization
-- Document time savings in learnings
-- Update conventions if thresholds changed
-
-**After fixing flaky CI:**
-- Document root cause in learnings
-- Add prevention pattern to conventions
-
-## Context
-
-{{argument}}