agileflow 3.4.3 → 4.0.0-alpha.2

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

@@ -1,234 +0,0 @@
----
-description: Plan, build, and improve database feature with expertise-driven workflow
-argument-hint: <database feature description>
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/database/expertise.yaml
----
-
-# Database Expert: Plan → Build → Self-Improve
-
-You are executing a complete database feature implementation with automatic knowledge capture. This workflow ensures you leverage existing database 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:
-- Schema file locations (migrations, models)
-- Existing table relationships
-- Naming conventions (snake_case, prefixes)
-- Migration patterns
-- Recent learnings that might apply
-
-### 1.2 Validate Against Codebase
-Before planning, verify your expertise is accurate:
-
-```bash
-# Check schema files exist
-ls -la src/db/ prisma/ migrations/ 2>/dev/null || true
-
-# Check for recent changes
-git log --oneline -5 -- "**/*migration*" "**/*schema*" "**/prisma*" 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
-## Database Implementation Plan
-
-### Schema Changes
-1. [Table name] - [columns, types, constraints]
-2. [Index/constraint changes]
-
-### Migration Strategy
-- Migration file: [path/filename]
-- Rollback plan: [how to reverse]
-
-### Related Files
-- [model file if ORM used]
-- [seed data if applicable]
-
-### Pattern to Follow
-[Reference specific pattern from expertise - e.g., "Use timestamps pattern from users table"]
-
-### Validation
-- [ ] Migration runs without errors
-- [ ] Foreign keys valid
-- [ ] Indexes created properly
-```
-
-**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 tables exist
-- Verify ORM client is in sync
-- Check for pending migrations
-
-### 2.2 Execute the Plan
-Follow your implementation plan:
-
-**For Prisma projects:**
-```bash
-# After schema changes
-npx prisma generate
-npx prisma migrate dev --name descriptive_name
-```
-
-**For raw SQL migrations:**
-```bash
-# Create migration file following naming convention
-# Run migration
-```
-
-### 2.3 Capture Changes
-After building, document what changed:
-
-```bash
-# Capture the diff for self-improve
-git diff --name-only | grep -E "(schema|migration|model|prisma)"
-git diff HEAD
-```
-
-### 2.4 Validate Build
-Verify the implementation:
-- Migration completed successfully
-- Database schema reflects changes
-- Related models/types updated
-- No type errors
-
-**Output**: Working schema 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 tables added
-- New columns on existing tables
-- New relationships (foreign keys)
-- New indexes or constraints
-- New migration patterns used
-
-### 3.2 Update Expertise File
-Read and update `{{EXPERTISE_FILE}}`:
-
-**Update `files` section if:**
-```yaml
-files:
-  migrations:
-    - path: path/to/new/migration
-      purpose: "New table for [feature]"
-```
-
-**Update `relationships` section if:**
-```yaml
-relationships:
-  - from: new_table
-    to: existing_table
-    type: belongs_to
-    foreign_key: existing_table_id
-```
-
-**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 [table] for [purpose]"
-    files_affected:
-      - path/to/migration
-      - path/to/model
-    context: "Feature: {{argument}}"
-```
-
-### 3.4 Validate Updated Expertise
-Before saving:
-- [ ] All file paths exist
-- [ ] Relationships match actual foreign keys
-- [ ] `last_updated` is current
-- [ ] No duplicate table entries
-- [ ] File stays focused (<200 lines)
-
-### 3.5 Save Expertise
-Write the updated expertise.yaml file.
-
----
-
-## Database-Specific Error Handling
-
-### If Migration Fails
-- Check for conflicting migrations
-- Verify foreign key references exist
-- Check for duplicate table/column names
-- Rollback if partial migration occurred
-
-### If Validation Fails
-- Type errors: regenerate ORM client
-- FK errors: verify referenced tables exist
-- Index errors: check for duplicate index names
-
----
-
-## Example Usage
-
-**Request**: "Add a sessions table to track user logins"
-
-**Step 1 Output** (Plan):
-```markdown
-## Database Implementation Plan
-
-### Schema Changes
-1. sessions table - id, user_id (FK), token, ip_address, user_agent, expires_at, created_at
-
-### Migration Strategy
-- File: prisma/migrations/20251216_add_sessions
-- Rollback: DROP TABLE sessions;
-
-### Pattern to Follow
-Using timestamps pattern from users table (created_at, updated_at)
-Using uuid for id (matching users.id pattern)
-```
-
-**Step 2 Output** (Build):
-- Created migration file
-- Ran `npx prisma migrate dev`
-- Generated new Prisma client
-- Diff: prisma/schema.prisma, prisma/migrations/...
-
-**Step 3 Output** (Self-Improve):
-- Added sessions to tables list
-- Added sessions→users relationship
-- Added learning: "Added sessions table for auth tracking"
-
----
-
-## Feature Request
-
-{{argument}}

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

@@ -1,141 +0,0 @@
-# Data Migration Expert - Domain Knowledge
-# This file is the agent's "mental model" of the data migration domain
-# AUTO-UPDATED by self-improve.md after completing work
-
-domain: datamigration
-last_updated: 2025-12-21
-version: 1.1
-
-files:
-  migrations:
-    - path: src/migrations/
-      purpose: "Database migration scripts"
-      conventions: "Timestamped: YYYYMMDDHHMMSS_description.ts"
-    - path: src/migrations/data/
-      purpose: "Data transformation scripts"
-      conventions: "Separate from schema migrations"
-    - path: src/migrations/rollback/
-      purpose: "Rollback scripts for each migration"
-
-  validation:
-    - path: src/migrations/validators/
-      purpose: "Data validation scripts"
-      conventions: "Pre and post-migration validators"
-    - path: docs/migrations/validation-reports/
-      purpose: "Validation report outputs"
-
-  documentation:
-    - path: docs/migrations/
-      purpose: "Migration documentation"
-    - path: docs/migrations/runbooks/
-      purpose: "Migration runbooks"
-    - path: docs/migrations/history.md
-      purpose: "Migration history log"
-
-relationships:
-  - parent: schema_migration
-    child: data_migration
-    type: precedes
-    notes: "Schema changes before data transformations"
-  - parent: migration
-    child: rollback
-    type: paired_with
-    notes: "Every migration has a rollback script"
-  - parent: validation
-    child: migration
-    type: verifies
-    notes: "Validation before and after migration"
-
-patterns:
-  - name: Zero-Downtime Migration
-    description: "Migrate without taking service offline"
-    location: docs/migrations/
-    example: |
-      1. Add new column (nullable)
-      2. Backfill data
-      3. Switch application to use new column
-      4. Remove old column
-
-  - name: Expand-Contract Pattern
-    description: "Add new, migrate data, remove old"
-    location: src/migrations/
-    example: "Add column → copy data → remove old column"
-
-  - name: Blue-Green Migration
-    description: "Run old and new in parallel, switch over"
-    location: docs/migrations/
-    example: "Write to both, read from old, switch reads, stop old writes"
-
-  - name: Validation Checkpoints
-    description: "Validate data at each migration step"
-    location: src/migrations/validators/
-    example: "Count check, integrity check, sample verification"
-
-conventions:
-  - "ALWAYS backup before migration"
-  - "ALWAYS have rollback script ready"
-  - "NEVER run migrations during peak hours"
-  - "Validate data before and after migration"
-  - "Test migrations in staging first"
-  - "Document migration in runbook"
-  - "Monitor during and after migration"
-  - "Keep migrations idempotent when possible"
-
-migration_checklist:
-  pre_migration:
-    - "Backup completed and verified"
-    - "Rollback script tested"
-    - "Staging migration successful"
-    - "Downtime window scheduled (if needed)"
-    - "Stakeholders notified"
-    - "Monitoring dashboards ready"
-
-  during_migration:
-    - "Progress logging enabled"
-    - "Error handling active"
-    - "Checkpoint validation passing"
-    - "Performance within bounds"
-
-  post_migration:
-    - "Data validation passed"
-    - "Application functioning correctly"
-    - "No data loss verified"
-    - "Rollback script archived"
-    - "Migration documented in history"
-
-# Learnings are AUTO-UPDATED by self-improve.md
-learnings:
-  - date: 2025-12-21
-    context: AgileFlow auto-archival system
-    learning: |
-      JSON-based data migration pattern: AgileFlow uses scripts/archive-completed-stories.sh
-      to automatically migrate completed stories from status.json to archive/YYYY-MM.json files.
-      This is a time-based migration (7-day threshold) that keeps the active status file lean
-      while preserving historical data in monthly archives. The migration is idempotent and
-      runs automatically on session start via SessionStart hook.
-
-  - date: 2025-12-21
-    context: AgileFlow status.json compression
-    learning: |
-      Data compression migration: The scripts/compress-status.sh script performs field-level
-      migration by removing verbose fields (like descriptions, acceptance criteria) while
-      preserving essential data. This is a vertical migration (reducing fields per record)
-      rather than horizontal (moving records between files). Useful for reducing file size
-      without losing critical tracking data.
-
-  - date: 2025-12-21
-    context: AgileFlow archival configuration
-    learning: |
-      Configuration-driven migration: Migration behavior is controlled via
-      docs/00-meta/agileflow-metadata.json with archival.threshold_days and archival.enabled
-      settings. This allows users to customize migration behavior without code changes.
-      The threshold_days acts as a temporal boundary for data migration decisions.
-
-  - date: 2025-12-21
-    context: AgileFlow JSON data patterns
-    learning: |
-      JSON file migration differs from SQL migrations: No schema enforcement, no transactions,
-      no referential integrity. Instead, rely on: (1) atomic file writes, (2) backup before
-      modify, (3) validation via JSON.parse, (4) idempotent scripts that check for existing
-      data before migrating. AgileFlow's archival system demonstrates these patterns well -
-      it checks if story already exists in archive before moving it.

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