agileflow 3.4.2 → 4.0.0-alpha.1

package/src/core/council/shared_reasoning.template.md

@@ -1,106 +0,0 @@
-# AI Council Deliberation
-
-## Session Info
-- **Session ID**: {{session_id}}
-- **Created**: {{timestamp}}
-- **Mode**: {{mode}} (parallel | debate)
-- **Rounds**: {{rounds}}
-
----
-
-## Question/Proposal
-
-{{question}}
-
----
-
-## Council Perspectives
-
-### Round 1
-
-#### Optimist Strategist
-<!-- council-optimist writes here -->
-
-[Awaiting optimist perspective...]
-
----
-
-#### Devil's Advocate
-<!-- council-advocate writes here -->
-
-[Awaiting advocate perspective...]
-
----
-
-#### Neutral Analyst
-<!-- council-analyst writes here -->
-
-[Awaiting analyst perspective...]
-
----
-
-{{#if debate_mode}}
-### Round {{round_number}}
-
-#### Optimist Response
-<!-- Responds to other perspectives -->
-
-[Awaiting optimist response...]
-
----
-
-#### Advocate Response
-<!-- Responds to other perspectives -->
-
-[Awaiting advocate response...]
-
----
-
-#### Analyst Synthesis
-<!-- Synthesizes debate -->
-
-[Awaiting analyst synthesis...]
-
----
-{{/if}}
-
-## Final Synthesis
-
-### Common Ground (All Agree)
-- [To be synthesized after all perspectives received]
-
-### Opportunities (Optimist Unique)
-- [From optimist perspective]
-
-### Risks (Advocate Unique)
-- [From advocate perspective]
-
-### Trade-offs (Analyst Assessment)
-- [From analyst perspective]
-
-### Recommendation
-**Decision**: [To be determined]
-**Confidence**: [High/Medium/Low]
-**Reasoning**: [Summary of key factors]
-
-### Next Steps
-1. [Action item]
-2. [Action item]
-3. [Action item]
-
----
-
-## Metadata
-
-```json
-{
-  "session_id": "{{session_id}}",
-  "question": "{{question}}",
-  "mode": "{{mode}}",
-  "rounds": {{rounds}},
-  "agents": ["council-optimist", "council-advocate", "council-analyst"],
-  "status": "in_progress",
-  "created_at": "{{timestamp}}",
-  "completed_at": null
-}
-```

package/src/core/experts/README.md

@@ -1,236 +0,0 @@
-# Agent Experts
-
-**Self-improving agents that maintain domain expertise over time.**
-
-## What Are Agent Experts?
-
-Agent Experts are specialized agents that:
-1. **Remember** - Maintain expertise files (mental models) of their domain
-2. **Validate** - Check their understanding against actual code
-3. **Learn** - Update expertise after making changes
-4. **Accelerate** - Work faster by skipping unnecessary exploration
-
-### Generic Agent vs Agent Expert
-
-| Aspect | Generic Agent | Agent Expert |
-|--------|---------------|--------------|
-| Knowledge | Starts fresh each session | Loads expertise file first |
-| Search behavior | Explores/searches codebase | Knows where things are |
-| Learning | None - forgets everything | Updates expertise after tasks |
-| Domain focus | General purpose | Specialized (database, api, ui) |
-| Execution speed | Slower (must discover) | Faster (pre-loaded knowledge) |
-
-## Directory Structure
-
-```
-experts/
-├── README.md              # This file
-├── templates/
-│   ├── expertise-template.yaml   # Schema for expertise files
-│   ├── question-template.md      # Template for question prompts
-│   ├── self-improve-template.md  # Template for self-improve prompts
-│   └── workflow-template.md      # Template for Plan→Build→Self-Improve workflow
-│
-│  # Pilot Phase (EP-0001)
-├── database/              # Database specialist
-├── api/                   # API/backend specialist
-├── ui/                    # UI/frontend specialist
-│
-│  # Phase 1 Rollout
-├── testing/               # Testing specialist
-├── ci/                    # CI/CD specialist
-├── devops/                # DevOps specialist
-├── security/              # Security specialist
-│
-│  # Phase 2 Rollout
-├── documentation/         # Documentation specialist
-├── refactor/              # Refactoring specialist
-├── performance/           # Performance specialist
-├── accessibility/         # Accessibility specialist
-│
-│  # Phase 3 Rollout
-├── mobile/                # Mobile specialist
-├── integrations/          # Integrations specialist
-├── analytics/             # Analytics specialist
-├── monitoring/            # Monitoring specialist
-│
-│  # Phase 4 Rollout
-├── product/               # Product specialist
-├── qa/                    # QA specialist
-├── design/                # Design specialist
-├── compliance/            # Compliance specialist
-├── datamigration/         # Data migration specialist
-├── mentor/                # Mentor/orchestration specialist
-├── epic-planner/          # Epic planning specialist
-├── adr-writer/            # ADR writing specialist
-├── research/              # Research specialist
-└── readme-updater/        # README updating specialist
-```
-
-**Each expert directory contains:**
-- `expertise.yaml` - Domain mental model (files, relationships, patterns)
-- `question.md` - Q&A workflow with expertise-first approach
-- `self-improve.md` - Auto-update expertise after changes
-- `workflow.md` - Complete Plan→Build→Self-Improve chain
-
-## The Three-Step Workflow
-
-Agent Experts follow **Plan → Build → Self-Improve**:
-
-### Step 1: Plan (with Expertise)
-```
-Read expertise file → Validate against code → Create detailed plan
-```
-
-### Step 2: Build (Execute Plan)
-```
-Execute plan changes → Update source code → Generate diff
-```
-
-### Step 3: Self-Improve (Update Expertise)
-```
-Analyze what changed → Update expertise file → Sync mental model
-```
-
-This creates a **closed loop** where the agent's knowledge evolves with the codebase.
-
-### Using Workflow Prompts
-
-Each expert has a `workflow.md` that chains all three steps together:
-
-```bash
-# For complete feature implementation
-# 1. Read the workflow prompt for your domain
-packages/cli/src/core/experts/database/workflow.md  # Database features
-packages/cli/src/core/experts/api/workflow.md       # API features
-packages/cli/src/core/experts/ui/workflow.md        # UI features
-```
-
-The workflow prompt:
-1. **Loads expertise** before planning
-2. **Validates** assumptions against codebase
-3. **Creates detailed plan** with exact file paths
-4. **Executes the plan** with proper error handling
-5. **Captures diff** of all changes
-6. **Updates expertise** with new learnings
-
-### Individual Prompts
-
-For specific tasks, use individual prompts:
-
-| Prompt | Use When |
-|--------|----------|
-| `question.md` | You need information from the domain |
-| `self-improve.md` | You made changes and need to update expertise |
-| `workflow.md` | You're implementing a complete feature |
-
-**Example - Asking a question:**
-```
-Read packages/cli/src/core/experts/database/question.md
-Then ask: "Where is the users schema defined?"
-```
-
-**Example - Full feature workflow:**
-```
-Read packages/cli/src/core/experts/database/workflow.md
-Then request: "Add a sessions table to track user logins"
-```
-
-## Creating a New Agent Expert
-
-### 1. Create Domain Directory
-```bash
-mkdir -p experts/{domain}
-```
-
-### 2. Copy and Customize Templates
-```bash
-# Copy templates
-cp templates/expertise-template.yaml {domain}/expertise.yaml
-cp templates/question-template.md {domain}/question.md
-cp templates/self-improve-template.md {domain}/self-improve.md
-
-# Replace placeholders
-# {{DOMAIN}} → your domain name (e.g., "database")
-# {{DOMAIN_TITLE}} → title case (e.g., "Database")
-# {{DOMAIN_PATTERN}} → file pattern (e.g., "db|database|schema")
-# {{ISO_DATE}} → current date (e.g., "2025-12-16")
-```
-
-### 3. Populate Initial Expertise
-Edit `expertise.yaml` with initial domain knowledge:
-- File locations the expert needs to know
-- Relationships between entities
-- Patterns and conventions
-- Leave `learnings` empty (self-improve populates it)
-
-### 4. Update Main Agent
-Modify the main agent file (e.g., `agents/database.md`) to:
-- Read expertise file in FIRST ACTION section
-- Run self-improve after completing work
-
-## Expertise File Schema
-
-```yaml
-domain: string           # Domain identifier (database, api, ui)
-last_updated: ISO-date   # When expertise was last updated
-version: string          # Schema version
-
-files:                   # Key files the expert needs to know
-  category:
-    - path: string       # File or directory path
-      purpose: string    # What this file/dir contains
-      key_exports: []    # Important exports (optional)
-      conventions: ""    # Naming/structure conventions (optional)
-
-relationships: []        # How entities relate to each other
-  # - parent: string
-  #   child: string
-  #   type: string       # one-to-many, many-to-many, etc.
-
-patterns: []             # Recurring approaches in this domain
-  # - name: string
-  #   description: string
-  #   location: string
-
-conventions: []          # Rules the agent should follow
-  # - "Convention description"
-
-learnings: []            # AUTO-UPDATED by self-improve
-  # - date: ISO-date
-  #   insight: string
-  #   files_affected: []
-  #   context: string
-```
-
-## Key Principles
-
-### 1. Expertise is NOT Source of Truth
-The code is always the source of truth. Expertise is a mental model - like an engineer's understanding - that must be validated against actual code.
-
-### 2. Validate Before Acting
-Always compare expertise against the codebase before relying on it. Code changes, expertise may be stale.
-
-### 3. Learn Automatically
-Self-improve runs after successful builds. The agent updates its own expertise - no manual maintenance.
-
-### 4. Stay Focused
-Each expert focuses on ONE domain. Don't create "Frontend Expert" - create "React Component Expert" or "Form Validation Expert".
-
-### 5. Keep It Small
-Expertise files should be <200 lines. If larger, the domain is too broad. Split into sub-domains.
-
-## Anti-Patterns to Avoid
-
-1. **Treating Expertise as Source of Truth** - Always validate against code
-2. **Global Expertise Files** - Each domain needs its own focused file
-3. **Manual Expertise Updates** - Let self-improve handle it
-4. **Skipping Validation** - Never trust expertise blindly
-5. **Over-broad Domains** - Keep domains focused and specific
-
-## Research Reference
-
-This system is based on the Agent Expert pattern from:
-- **Source**: IndyDevDan's Tactical Agentic Coding Course
-- **Lesson**: 13 - Agent Experts: Finally, Agents That Actually Learn
-- **Research**: See `docs/10-research/20251216-agent-experts-self-improving-agents.md`

package/src/core/experts/_core-expertise.yaml

@@ -1,105 +0,0 @@
-# Core Expertise - Always-Loaded AgileFlow Knowledge
-# These 3 curated modules contain high-value cross-cutting patterns.
-# Loaded by all agents. Domain-specific files are reference-only (loaded on demand).
-
-version: 1.0
-last_updated: 2026-02-26
-
-# Module 1: CLI Architecture Patterns
-cli_architecture:
-  structure:
-    source: packages/cli/src/core/
-    commands: "src/core/commands/*.md - Slash commands with frontmatter"
-    agents: "src/core/agents/*.md - Spawnable agents with frontmatter"
-    experts: "src/core/experts/*/expertise.yaml - Domain knowledge"
-    skills: "src/core/skills/ - Skill learnings and marketplace (browse via /skill:recommend)"
-
-  content_injection:
-    description: "Source files use placeholders replaced at install time"
-    placeholders:
-      - "<!-- {{AGENT_LIST}} --> - Current agent list"
-      - "<!-- {{COMMAND_LIST}} --> - Current command list"
-      - "<!-- {{SKILL_LIST}} --> - Current skill list"
-    pipeline: "content-injector.js -> content-transformer.js -> IDE installer"
-
-  installers:
-    core: "tools/cli/installers/core/installer.js - Copies agents, commands, scripts"
-    ide_base: "tools/cli/installers/ide/_base-ide.js - Shared IDE setup logic"
-    claude_code: "tools/cli/installers/ide/claude-code.js - Claude Code specific (hooks, agents)"
-
-  key_conventions:
-    - "Commands: frontmatter with description, optional argument-hint"
-    - "Agents: frontmatter with name, description, tools, model (no agileflow- prefix in filename)"
-    - "Scripts in packages/cli/scripts/ are PUBLISHED (copied to user projects)"
-    - "Scripts in root scripts/ are dev-only (NOT published)"
-    - "Dynamic counts: run npm run sync-counts after adding commands/agents"
-
-# Module 2: Testing Conventions
-testing:
-  framework:
-    runner: "Jest (packages/cli/__tests__/)"
-    command: "npm test from packages/cli/"
-    total_tests: "~4373+ tests across 161+ suites"
-
-  patterns:
-    - "Tests mirror source structure: __tests__/lib/ for tools/cli/lib/"
-    - "Use jest.mock() for fs, child_process dependencies"
-    - "Expertise validation: scripts/validate-expertise.sh"
-    - "Story test tracking: status.json test_status field (passing/failing/not_run)"
-
-  quality_gates:
-    - "All tests must pass before commit"
-    - "Session Harness: /agileflow:verify runs tests for current story"
-    - "/agileflow:baseline marks verified state"
-    - "Logic audit: 5 analyzers check edge cases, race conditions, type bugs"
-
-  known_issues:
-    - "api-server port 3456 conflict causes ~10 test failures (pre-existing)"
-    - "--legacy-peer-deps required for TensorFlow.js version conflicts"
-
-# Module 3: Security Guidelines
-security:
-  commit_policy:
-    - "NO AI attribution in commits (forbidden: Co-Authored-By AI, emoji robots)"
-    - "Clean conventional commits only (feat/fix/chore/docs)"
-
-  secrets:
-    gitignored: [".npmrc", "CLAUDE.md"]
-    storage: "NPM_TOKEN in GitHub Secrets, never committed"
-
-  code_patterns:
-    - "Use execFileSync(cmd, [args]) not execSync(`cmd ${var}`) to prevent injection"
-    - "Validate PIDs are numeric, ports are numbers, paths don't traverse"
-    - "Damage control hooks guard Bash/Edit/Write via PreToolUse"
-    - "patterns.yaml defines blocked commands, read-only paths, zero-access paths"
-
-  hooks:
-    exit_codes: "0=allow, 1=error (fail-open), 2=block"
-    files:
-      - "damage-control/bash-tool-damage-control.js"
-      - "damage-control/edit-tool-damage-control.js"
-      - "damage-control/write-tool-damage-control.js"
-      - "lib/damage-control-utils.js - Shared validation logic"
-
-# Data Stores (cross-cutting knowledge)
-data_stores:
-  status_json:
-    path: "docs/09-agents/status.json"
-    schema: "epics (EP-ID keys), stories (US-ID keys)"
-    operations: "Read-modify-write with updated timestamp"
-  session_state:
-    path: "docs/09-agents/session-state.json"
-    purpose: "Active command, loop state, smart-detect results"
-  archive:
-    path: "docs/09-agents/archive/YYYY-MM.json"
-    policy: "Completed stories >7 days auto-archived"
-  metadata:
-    path: "docs/00-meta/agileflow-metadata.json"
-    purpose: "Config schema version, feature toggles, profiles"
-
-# Release Process
-release:
-  command: "./scripts/release.sh <version> <title>"
-  version_files: ["packages/cli/package.json", "package.json"]
-  ci: ".github/workflows/npm-publish.yml triggered by v*.*.* tags"
-  brand_color: "#e8683a"

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

@@ -1,115 +0,0 @@
-domain: accessibility
-last_updated: 2025-12-21
-version: 1.1
-
-files:
-  components:
-    - path: src/components/
-      purpose: UI components to audit
-    - path: src/components/ui/
-      purpose: Base UI components (buttons, inputs, etc.)
-
-  config:
-    - path: .axerc
-      purpose: Axe accessibility config
-    - path: jest.config.js
-      purpose: Jest with jest-axe setup
-
-  docs:
-    - path: docs/accessibility/
-      purpose: Accessibility documentation
-    - path: ACCESSIBILITY.md
-      purpose: Accessibility statement
-
-  cli:
-    - path: packages/cli/src/core/
-      purpose: CLI commands and agents (primary accessibility focus for AgileFlow)
-    - path: packages/cli/tools/
-      purpose: CLI tools and installers
-
-relationships:
-  - component_type: form
-    requirements: [labels, error_messages, focus_management]
-    aria: [aria-describedby, aria-invalid, aria-required]
-  - component_type: modal
-    requirements: [focus_trap, escape_close, aria-modal]
-    aria: [role=dialog, aria-labelledby]
-  - component_type: navigation
-    requirements: [keyboard_nav, skip_links, landmarks]
-    aria: [role=navigation, aria-current]
-  - component_type: cli_prompt
-    requirements: [clear_instructions, keyboard_only, error_feedback]
-    libraries: [inquirer, chalk, ora]
-
-patterns:
-  - name: Focus Management
-    description: "Manage focus for SPAs and modals"
-    implementation: "Focus first focusable on open, restore on close"
-  - name: Keyboard Navigation
-    description: "All interactive elements keyboard accessible"
-    implementation: "Tab, Enter, Space, Escape, Arrow keys"
-  - name: Screen Reader Labels
-    description: "All elements have accessible names"
-    implementation: "aria-label, aria-labelledby, visible text"
-  - name: Color Contrast
-    description: "4.5:1 for text, 3:1 for large text"
-    implementation: "Use contrast checker tools"
-  - name: CLI Semantic Colors
-    description: "Terminal colors convey meaning consistently"
-    implementation: "Green=success, Red=error, Yellow=warning, Cyan=info, no color-only indicators"
-  - name: CLI Progress Feedback
-    description: "Visual feedback for long-running operations"
-    implementation: "Ora spinners with descriptive text, percentage indicators where applicable"
-  - name: CLI Error Messages
-    description: "Clear, actionable error messages"
-    implementation: "Context + problem + solution, colored output with chalk, exit codes for automation"
-
-conventions:
-  - "WCAG 2.1 AA minimum, AAA preferred"
-  - "Test with screen readers (NVDA, VoiceOver)"
-  - "All images have alt text"
-  - "Form inputs have associated labels"
-  - "Color never sole indicator of meaning"
-  - "Motion respects prefers-reduced-motion"
-  - "Skip links for keyboard users"
-  - "CLI: Always provide text with colored output (never color-only)"
-  - "CLI: All prompts keyboard-navigable (arrow keys, tab, enter)"
-  - "CLI: Error messages include context and next steps"
-  - "CLI: Progress indicators have descriptive text"
-
-wcag_checklist:
-  perceivable:
-    - "1.1.1 Non-text Content (A)"
-    - "1.3.1 Info and Relationships (A)"
-    - "1.4.3 Contrast Minimum (AA)"
-    - "1.4.11 Non-text Contrast (AA)"
-  operable:
-    - "2.1.1 Keyboard (A)"
-    - "2.1.2 No Keyboard Trap (A)"
-    - "2.4.1 Bypass Blocks (A)"
-    - "2.4.7 Focus Visible (AA)"
-  understandable:
-    - "3.1.1 Language of Page (A)"
-    - "3.2.1 On Focus (A)"
-    - "3.3.1 Error Identification (A)"
-  robust:
-    - "4.1.1 Parsing (A)"
-    - "4.1.2 Name, Role, Value (A)"
-
-learnings:
-  - date: 2025-12-21
-    context: "AgileFlow CLI accessibility patterns"
-    insight: "AgileFlow is a CLI tool, not a web application. Accessibility focuses on terminal UX: clear error messages with semantic colors (chalk), keyboard-friendly prompts (inquirer), progress indicators (ora spinners), and consistent color conventions (green=success, red=error, yellow=warning)."
-    impact: "Shifted accessibility focus from WCAG web patterns to CLI usability patterns. All user-facing output should be screen-reader friendly by always pairing colors with descriptive text."
-  - date: 2025-12-21
-    context: "CLI semantic color system"
-    insight: "Terminal colors must never be the sole indicator of meaning. Always include descriptive text alongside colored output. Example: '✓ Success: Installation complete' (green) vs just green checkmark."
-    impact: "Ensures CLI output is accessible to users with color blindness or screen readers. All installers (ui.js, docs-setup.js) follow this pattern."
-  - date: 2025-12-21
-    context: "Interactive prompts accessibility"
-    insight: "All CLI prompts use inquirer library which provides built-in keyboard navigation (arrow keys, tab, enter, escape). Prompts always include clear instructions and validation error messages."
-    impact: "Users can navigate all AgileFlow prompts without mouse. Validation errors are actionable and specific (e.g., 'Please enter a valid directory path' vs 'Invalid input')."
-  - date: 2025-12-21
-    context: "Long-running operation feedback"
-    insight: "AgileFlow uses ora spinners for operations >1 second. Spinners always have descriptive text explaining current action (e.g., 'Installing dependencies...' not just spinner). Completion shows success/failure with clear messaging."
-    impact: "Users always know what's happening during installs, setups, and file operations. No silent failures or mysterious waiting periods. Screen readers can announce status changes."

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

@@ -1,41 +0,0 @@
----
-description: Ask questions about accessibility - uses expertise for fast, accurate answers
-argument-hint: <your question>
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/accessibility/expertise.yaml
----
-
-# Accessibility Expert - Question
-
-You are an expert on the accessibility domain for this codebase.
-
-## CRITICAL: Expertise-First Workflow
-
-### Step 1: Load Your Expertise
-Read `{{EXPERTISE_FILE}}` FIRST.
-
-This contains:
-- Component accessibility requirements
-- WCAG compliance checklist
-- ARIA patterns
-- Accessibility conventions
-
-### Step 2: Validate Against Actual Code
-Check if accessibility configs exist.
-Note any discrepancies for self-improve.
-
-### Step 3: Answer the Question
-- Reference WCAG criteria
-- Include ARIA examples
-- If expertise was wrong, note it
-
-## Common Questions I Can Answer
-- Is this component accessible?
-- What ARIA attributes are needed?
-- Does this meet WCAG AA?
-- How do I add keyboard navigation?
-- What's the color contrast requirement?
-
-## Question
-
-{{argument}}

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

@@ -1,45 +0,0 @@
----
-description: Update accessibility expertise after making changes
-argument-hint: [optional context about what changed]
-variables:
-  EXPERTISE_FILE: packages/cli/src/core/experts/accessibility/expertise.yaml
----
-
-# Accessibility Expert - Self-Improve
-
-Update your expertise file after accessibility changes.
-
-## Workflow
-
-### Step 1: Read Current Expertise
-Load `{{EXPERTISE_FILE}}`.
-
-### Step 2: Analyze What Changed
-```bash
-git diff HEAD~1 --name-only | grep -E "(component|a11y|aria|accessibility)"
-```
-
-### Step 3: Update Expertise
-
-**Update `files` if:** New components, a11y configs added
-**Update `relationships` if:** New component types with a11y requirements
-**Update `patterns` if:** New accessibility patterns
-**Update `wcag_checklist` if:** Compliance status changed
-
-### Step 4: Add Learnings Entry
-```yaml
-learnings:
-  - date: 2025-12-16
-    insight: "Added [a11y feature] for [WCAG criterion]"
-    files_affected: [list]
-    context: "{{argument}}"
-```
-
-### Step 5: Validate and Save
-- [ ] All paths exist
-- [ ] `last_updated` current
-- [ ] No duplicates
-
-## Context
-
-{{argument}}