agileflow 3.4.3 → 4.0.0-alpha.2

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

@@ -1,135 +0,0 @@
-domain: refactor
-last_updated: 2025-12-21
-version: 1.1
-
-# AgileFlow codebase patterns for refactoring
-files:
-  cli_structure:
-    - path: packages/cli/tools/cli/commands/
-      purpose: CLI command implementations
-      pattern: "Each command is self-contained .js file"
-      observation: "Good separation of concerns"
-
-    - path: packages/cli/tools/cli/lib/
-      purpose: Shared utilities
-      files:
-        - "ui.js - Display utilities (logo, colors, prompts)"
-        - "version-checker.js - npm version checking"
-        - "content-injector.js - Placeholder replacement"
-        - "docs-setup.js - Documentation scaffolding"
-        - "npm-utils.js - npm package utilities"
-
-    - path: packages/cli/tools/cli/installers/
-      purpose: Installation logic
-      pattern: "core/ for main logic, ide/ for IDE-specific"
-
-  core_content:
-    - path: packages/cli/src/core/commands/
-      purpose: Slash command markdown files
-      count: "{{COMMAND_COUNT}}"
-      pattern: "<command>.md with frontmatter"
-
-    - path: packages/cli/src/core/agents/
-      purpose: Agent prompt markdown files
-      count: "{{AGENT_COUNT}}"
-      pattern: "<agent>.md with frontmatter (name, description, tools, model)"
-
-    - path: packages/cli/src/core/experts/
-      purpose: Expert knowledge files
-      count: "{{SKILL_COUNT}}"
-      pattern: "<domain>/expertise.yaml, question.md, self-improve.md, workflow.md"
-
-    - path: packages/cli/src/core/skills/
-      purpose: Auto-activating skills
-      count: "{{SKILL_COUNT}}"
-      pattern: "<skill>/SKILL.md"
-
-  scripts:
-    - path: scripts/
-      purpose: Utility shell scripts
-      count: 12+
-      examples:
-        - "release.sh - Automated release"
-        - "validate-expertise.sh - Expert validation"
-        - "expertise-metrics.sh - Metrics dashboard"
-        - "archive-completed-stories.sh - Story archival"
-
-relationships:
-  - name: command_pattern
-    location: "packages/cli/tools/cli/commands/"
-    pattern: "exports {name, description, options, action}"
-    refactor_opportunity: "Consider TypeScript for type safety"
-
-  - name: lib_utilities
-    location: "packages/cli/tools/cli/lib/"
-    pattern: "Shared modules with explicit exports"
-    observation: "Well-organized, minimal duplication"
-
-  - name: content_structure
-    locations:
-      - "commands/ - {{COMMAND_COUNT}} .md files"
-      - "agents/ - {{AGENT_COUNT}} .md files"
-      - "experts/ - {{SKILL_COUNT}} directories"
-      - "skills/ - {{SKILL_COUNT}} directories"
-    observation: "Consistent patterns across all content types"
-
-patterns:
-  - name: Dynamic Content Injection
-    description: "Placeholders replaced at install time"
-    location: "lib/content-injector.js"
-    placeholders:
-      - "{{COMMAND_COUNT}} - Number of commands"
-      - "{{AGENT_COUNT}} - Number of agents"
-      - "{{SKILL_COUNT}} - Number of skills"
-      - "{{VERSION}} - AgileFlow version"
-      - "{{INSTALL_DATE}} - Installation date"
-      - "<!-- {{AGENT_LIST}} --> - Full agent list"
-      - "<!-- {{COMMAND_LIST}} --> - Full command list"
-    benefit: "Zero maintenance for lists and counts"
-
-  - name: IDE-Specific Installers
-    description: "Separate installer per IDE"
-    location: "installers/ide/"
-    ides: ["claude-code", "cursor", "windsurf"]
-    benefit: "Easy to add new IDEs"
-
-  - name: Frontmatter Metadata
-    description: "YAML frontmatter in markdown files"
-    used_in: ["commands", "agents", "skills"]
-    fields: ["name", "description", "tools", "model"]
-
-  - name: Shell Script Automation
-    description: "Bash scripts for common operations"
-    location: "scripts/"
-    pattern: "Colored output, clear usage instructions"
-
-conventions:
-  - "CLI commands use Commander.js with async actions"
-  - "Shared utilities in lib/ with clear exports"
-  - "Content files use markdown with YAML frontmatter"
-  - "Shell scripts in scripts/ with colored output"
-  - "Dynamic content injection for lists"
-  - "IDE installers are pluggable"
-  - "Monorepo structure: packages/cli/ contains npm package"
-
-# Learned from AgileFlow codebase exploration
-learnings:
-  - date: 2025-12-21
-    context: "Analyzed CLI code organization"
-    insight: "Well-structured with commands/, lib/, installers/ separation; each command is self-contained"
-    source: "packages/cli/tools/cli/"
-
-  - date: 2025-12-21
-    context: "Analyzed content structure"
-    insight: "Consistent patterns: {{COMMAND_COUNT}} commands, {{AGENT_COUNT}} agents, {{SKILL_COUNT}} experts, {{SKILL_COUNT}} skills - all use frontmatter markdown"
-    source: "packages/cli/src/core/"
-
-  - date: 2025-12-21
-    context: "Analyzed dynamic content injection"
-    insight: "content-injector.js replaces placeholders like {{AGENT_LIST}} at install time - zero maintenance"
-    source: "packages/cli/tools/cli/lib/content-injector.js"
-
-  - date: 2025-12-21
-    context: "Analyzed refactoring opportunities"
-    insight: "Code is well-organized; potential improvements: TypeScript migration, unit tests, linting"
-    source: "packages/cli/"

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

@@ -1,41 +0,0 @@
----
-description: Ask questions about refactoring - uses expertise for fast, accurate answers
-argument-hint: <your question>
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/refactor/expertise.yaml
----
-
-# Refactor Expert - Question
-
-You are an expert on the refactoring domain for this codebase.
-
-## CRITICAL: Expertise-First Workflow
-
-### Step 1: Load Your Expertise
-Read `{{EXPERTISE_FILE}}` FIRST.
-
-This contains:
-- Code quality configurations
-- Known code smells and patterns
-- Refactoring conventions
-- Recent learnings
-
-### Step 2: Validate Against Actual Code
-Check if quality configs exist at expected locations.
-Note any discrepancies for self-improve.
-
-### Step 3: Answer the Question
-- Reference exact file paths
-- Include refactoring examples
-- If expertise was wrong, note it
-
-## Common Questions I Can Answer
-- What code smells exist in this file?
-- How should I refactor this function?
-- Where is the technical debt tracked?
-- What's the complexity of this module?
-- How do I safely rename this symbol?
-
-## Question
-
-{{argument}}

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

@@ -1,45 +0,0 @@
----
-description: Update refactor expertise after making changes
-argument-hint: [optional context about what changed]
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/refactor/expertise.yaml
----
-
-# Refactor Expert - Self-Improve
-
-Update your expertise file after refactoring changes.
-
-## Workflow
-
-### Step 1: Read Current Expertise
-Load `{{EXPERTISE_FILE}}`.
-
-### Step 2: Analyze What Changed
-```bash
-git diff HEAD~1 --stat
-```
-
-### Step 3: Update Expertise
-
-**Update `files` if:** New quality configs, test locations changed
-**Update `relationships` if:** New code smell patterns discovered
-**Update `patterns` if:** New refactoring patterns used
-**Update `conventions` if:** Refactoring rules changed
-
-### Step 4: Add Learnings Entry
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Refactored [what] using [pattern]"
-    files_affected: [list]
-    context: "{{argument}}"
-```
-
-### Step 5: Validate and Save
-- [ ] All paths exist
-- [ ] `last_updated` current
-- [ ] No duplicates
-
-## Context
-
-{{argument}}

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

@@ -1,57 +0,0 @@
----
-description: Plan, build, and improve refactoring with expertise-driven workflow
-argument-hint: <refactoring task description>
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/refactor/expertise.yaml
----
-
-# Refactor Expert: Plan → Build → Self-Improve
-
-## Step 1: PLAN
-
-### 1.1 Load Expertise
-Read `{{EXPERTISE_FILE}}` - know code smells, patterns, conventions.
-
-### 1.2 Validate
-- Run tests first (must pass before refactoring)
-- Measure current complexity
-
-### 1.3 Create Plan
-```markdown
-## Refactoring Plan
-- Code smell identified: [type]
-- Refactoring pattern: [name]
-- Files affected: [list]
-- Risk level: [low/medium/high]
-```
-
-## Step 2: BUILD
-
-### 2.1 Execute Plan
-- Apply refactoring pattern
-- Keep tests green throughout
-- Make atomic commits
-
-### 2.2 Capture Changes
-```bash
-git diff --stat
-```
-
-### 2.3 Validate
-- All tests pass
-- Complexity reduced
-- No behavior change
-
-## Step 3: SELF-IMPROVE
-
-### 3.1 Update Expertise
-- Note new code smells found
-- Document successful patterns
-- Add learnings
-
-### 3.2 Save
-Update `{{EXPERTISE_FILE}}` with learnings.
-
-## Refactoring Request
-
-{{argument}}

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

@@ -1,143 +0,0 @@
-# Research Expert - Domain Knowledge
-# This file is the agent's "mental model" of the research domain
-# AUTO-UPDATED by self-improve.md after completing work
-
-domain: research
-last_updated: 2025-12-21
-version: 1.1
-
-# AgileFlow-specific research patterns (learned from actual codebase)
-files:
-  research_notes:
-    - path: docs/10-research/
-      purpose: "Technical research notes"
-      conventions: "YYYYMMDD-slug.md naming (e.g., 20251216-agent-experts-self-improving-agents.md)"
-      current_notes:
-        - "20251216-agent-experts-self-improving-agents.md"
-        - "20251216-mermaid-js-diagramming.md"
-        - "20251217-mermaid-svg-styling.md"
-        - "20251216-agent-expert-pilot-retro.md"
-    - path: docs/10-research/README.md
-      purpose: "Research index (newest first)"
-
-  templates:
-    - path: docs/00-meta/templates/research-template.md
-      purpose: "Research note template with standard sections"
-
-  sources:
-    - path: docs/10-research/sources/
-      purpose: "Saved source materials (if needed)"
-
-  coordination:
-    - path: docs/09-agents/bus/log.jsonl
-      purpose: "Research requests from other agents"
-    - path: docs/05-epics/
-      purpose: "Epics reference research notes"
-
-relationships:
-  - parent: research_notes
-    child: epics
-    type: informs
-    notes: "Research informs epic planning (EP-0001 references agent-experts research)"
-  - parent: research_notes
-    child: adrs
-    type: informs
-    notes: "Research informs ADR alternatives"
-  - parent: retro_notes
-    child: improvements
-    type: drives
-    notes: "Retrospectives drive next iteration improvements"
-
-patterns:
-  - name: Research Note Naming
-    description: "YYYYMMDD-slug.md format with descriptive slug"
-    location: docs/10-research/
-    examples:
-      - "20251216-agent-experts-self-improving-agents.md"
-      - "20251216-mermaid-js-diagramming.md"
-      - "20251216-agent-expert-pilot-retro.md"
-
-  - name: Research Note Structure
-    description: "Standard sections for comprehensive research"
-    location: docs/10-research/
-    sections:
-      - "TL;DR (executive summary)"
-      - "Problem/Goal"
-      - "Approaches Considered"
-      - "Pros/Cons Analysis"
-      - "Recommendation"
-      - "Implementation Steps"
-      - "References"
-
-  - name: Retrospective Notes
-    description: "Post-implementation learnings"
-    location: docs/10-research/
-    example: "20251216-agent-expert-pilot-retro.md"
-    sections:
-      - "What Worked"
-      - "What Didn't"
-      - "Lessons Learned"
-      - "Next Steps"
-
-  - name: Epic Research Link
-    description: "Epics reference research via relative links"
-    location: docs/05-epics/
-    example: "See [Research](../10-research/20251216-agent-experts-self-improving-agents.md)"
-
-  - name: Context Export
-    description: "/agileflow:research:ask for external AI research prompts"
-    command: "/agileflow:research:ask TOPIC=<topic>"
-    purpose: "Generate prompt for ChatGPT/external AI with project context"
-
-conventions:
-  - "Check existing research before starting new"
-  - "Use YYYYMMDD-slug.md naming for all research notes"
-  - "Update docs/10-research/README.md index after creating note"
-  - "Reference research from epics with relative links"
-  - "Include TL;DR at top for quick scanning"
-  - "Flag research >90 days old as potentially stale"
-  - "Create retrospective notes after major implementations"
-  - "Use /agileflow:research:ask for external AI research prompts prompts"
-
-research_categories:
-  - "Technology evaluation (framework, library)"
-  - "Architecture patterns (Agent Expert system)"
-  - "Best practices (testing, security)"
-  - "Implementation retrospectives"
-  - "Diagramming/visualization (Mermaid)"
-  - "Compliance requirements"
-
-prompt_sections:
-  - "TL;DR summary"
-  - "Step-by-step implementation"
-  - "Code snippets"
-  - "Configuration"
-  - "Error handling"
-  - "Tests (unit, integration, E2E)"
-  - "Security considerations"
-  - "ADR draft"
-  - "Story breakdown"
-  - "Rollback plan"
-  - "Risks and gotchas"
-
-# Learned from AgileFlow codebase exploration
-learnings:
-  - date: 2025-12-21
-    context: "Analyzed research directory contents"
-    insight: "4 research notes exist with YYYYMMDD-slug.md naming; topics include agent experts, mermaid diagramming, pilot retro"
-    source: "docs/10-research/"
-
-  - date: 2025-12-21
-    context: "Analyzed epic-research relationship"
-    insight: "EP-0001 references research note with relative link (../10-research/20251216-agent-experts-self-improving-agents.md)"
-    source: "docs/05-epics/ep-0001-agent-expert-pilot.md"
-
-  - date: 2025-12-21
-    context: "Analyzed retrospective pattern"
-    insight: "Post-implementation retros capture What Worked, What Didn't, Lessons Learned, Next Steps (see pilot retro)"
-    source: "docs/10-research/20251216-agent-expert-pilot-retro.md"
-
-  - date: 2025-12-21
-    context: "Analyzed context command"
-    insight: "/agileflow:research:ask generates external AI prompts with project context for deep research"
-    source: "packages/cli/src/core/commands/context.md"

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