agileflow 2.74.0 → 2.75.0

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 [![npm version](https://img.shields.io/npm/v/agileflow?color=brightgreen)](https://www.npmjs.com/package/agileflow)
-[![Commands](https://img.shields.io/badge/commands-53-blue)](docs/04-architecture/commands.md)
+[![Commands](https://img.shields.io/badge/commands-58-blue)](docs/04-architecture/commands.md)
 [![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-27-orange)](docs/04-architecture/subagents.md)
 [![Skills](https://img.shields.io/badge/skills-dynamic-purple)](docs/04-architecture/skills.md)
 
@@ -65,7 +65,7 @@ AgileFlow combines three proven methodologies:
 
 | Component | Count | Description |
 |-----------|-------|-------------|
-| [Commands](docs/04-architecture/commands.md) | 53 | Slash commands for agile workflows |
+| [Commands](docs/04-architecture/commands.md) | 58 | Slash commands for agile workflows |
 | [Agents/Experts](docs/04-architecture/subagents.md) | 27 | Specialized agents with self-improving knowledge bases |
 | [Skills](docs/04-architecture/skills.md) | Dynamic | Generated on-demand with `/agileflow:skill:create` |
 
@@ -76,7 +76,7 @@ AgileFlow combines three proven methodologies:
 Full documentation lives in [`docs/04-architecture/`](docs/04-architecture/):
 
 ### Reference
-- [Commands](docs/04-architecture/commands.md) - All 53 slash commands
+- [Commands](docs/04-architecture/commands.md) - All 58 slash commands
 - [Agents/Experts](docs/04-architecture/subagents.md) - 27 specialized agents with self-improving knowledge
 - [Skills](docs/04-architecture/skills.md) - Dynamic skill generator with MCP integration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.74.0",
+  "version": "2.75.0",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",

package/src/core/agents/accessibility.md

@@ -428,7 +428,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research accessibility best practices
+- `/agileflow:research:ask TOPIC=...` → Research accessibility best practices
 - `/agileflow:ai-code-review` → Review code for accessibility issues
 - `/agileflow:adr-new` → Document accessibility decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/adr-writer.md

@@ -43,7 +43,7 @@ node .agileflow/scripts/obtain-context.js adr-writer
 
 **Workflow**:
 1. Load expertise: `packages/cli/src/core/experts/adr-writer/expertise.yaml`
-2. Check docs/10-research/ for existing research (or invoke `/agileflow:context MODE=research`)
+2. Check docs/10-research/ for existing research (or invoke `/agileflow:research:ask`)
 3. Check docs/03-decisions/ for related ADRs
 4. Get next ADR number from docs/03-decisions/README.md (sequential: 0001, 0002, etc.)
 5. Gather decision context and alternatives
@@ -135,13 +135,13 @@ Create an ADR when deciding:
 SLASH COMMANDS (Proactive Use)
 
 **Research**:
-- `/agileflow:context MODE=research TOPIC=...` → Generate research for alternatives before writing ADR
+- `/agileflow:research:ask TOPIC=...` → Generate research for alternatives before writing ADR
 
 RESEARCH INTEGRATION
 
 **Before Writing ADR**:
 1. Check docs/10-research/ for existing research on the decision topic
-2. If research is missing or stale, invoke `/agileflow:context MODE=research TOPIC=...`
+2. If research is missing or stale, invoke `/agileflow:research:ask TOPIC=...`
 3. Research should cover all alternatives with pros/cons, benchmarks, trade-offs
 
 **After User Provides Research**:
@@ -151,7 +151,7 @@ RESEARCH INTEGRATION
 
 WORKFLOW
 1. **[KNOWLEDGE LOADING]** Before writing:
-   - Check docs/10-research/ for relevant research (or invoke `/agileflow:context MODE=research`)
+   - Check docs/10-research/ for relevant research (or invoke `/agileflow:research:ask`)
    - Check existing ADRs in docs/03-decisions/ for related decisions
    - Check CLAUDE.md for current architecture context
 2. Ask for decision context (what's being decided and why now?)
@@ -268,7 +268,7 @@ This contains your mental model of:
 **Then Output**:
 1. ADR context: "Next ADR: ADR-<NUMBER>, recent decisions: <list of last 3 ADRs>"
 2. If research exists: "Found research: <topic> (docs/10-research/<file>)"
-3. If no research: "No research found. I can invoke `/agileflow:context MODE=research` to gather alternatives."
+3. If no research: "No research found. I can invoke `/agileflow:research:ask` to gather alternatives."
 4. Ask: "What technical decision would you like to document?"
 5. Clarify: "I'll document context, alternatives considered, decision, and consequences."
 
@@ -288,7 +288,7 @@ This updates your expertise with what you learned, so you're faster next time.
 
 **After User Describes Decision**:
 1. Clarify context (why now? what forces?)
-2. Check docs/10-research/ for supporting research (or invoke `/agileflow:context MODE=research`)
+2. Check docs/10-research/ for supporting research (or invoke `/agileflow:research:ask`)
 3. Identify 2-5 alternatives with pros/cons
 4. Propose ADR structure (show preview)
 5. Get approval (YES/NO)

package/src/core/agents/analytics.md

@@ -514,7 +514,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research analytics best practices
+- `/agileflow:research:ask TOPIC=...` → Research analytics best practices
 - `/agileflow:ai-code-review` → Review analytics implementation for data quality
 - `/agileflow:adr-new` → Document analytics decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/api.md

@@ -369,7 +369,7 @@ SLASH COMMANDS (Proactive Use)
 AG-API can directly invoke AgileFlow commands to streamline workflows:
 
 **Research & Planning**:
-- `/agileflow:context MODE=research TOPIC=...` → Research API patterns, database strategies, integration approaches
+- `/agileflow:research:ask TOPIC=...` → Research API patterns, database strategies, integration approaches
 
 **Quality & Review**:
 - `/agileflow:ai-code-review` → Review API code before marking in-review
@@ -407,7 +407,7 @@ AGENT COORDINATION
   - Performance issues → Request impact analysis
 
 - **RESEARCH** (Technical research):
-  - Unfamiliar pattern → Request research via `/agileflow:context MODE=research`
+  - Unfamiliar pattern → Request research via `/agileflow:research:ask`
   - Check docs/10-research/ for existing API/database research before starting
 
 - **MENTOR** (Guidance):
@@ -424,7 +424,7 @@ RESEARCH INTEGRATION
 **Before Starting Implementation**:
 1. Check docs/10-research/ for relevant API/database/integration research
 2. Search for topics: API patterns, database design, ORM usage, authentication, external integrations
-3. If no research exists or research is stale (>90 days), suggest: `/agileflow:context MODE=research TOPIC=...`
+3. If no research exists or research is stale (>90 days), suggest: `/agileflow:research:ask TOPIC=...`
 
 **After User Provides Research**:
 - Offer to save to docs/10-research/<YYYYMMDD>-<slug>.md
@@ -530,49 +530,138 @@ AG-UI stories frequently block waiting for API endpoints. Always check for block
 
 FIRST ACTION
 
-**CRITICAL: Load Expertise First (Agent Expert Protocol)**
-
-Before ANY work, read your expertise file:
-```
-packages/cli/src/core/experts/api/expertise.yaml
-```
-
-This contains your mental model of:
-- Route/controller file locations
-- Middleware structure
-- Endpoint registry
-- Auth and validation patterns
-- Recent learnings from past work
-
-**Validate expertise against actual code** - expertise is your memory, code is the source of truth.
-
-**Proactive Knowledge Loading** (do this BEFORE asking user):
-1. **READ EXPERTISE FILE FIRST** (packages/cli/src/core/experts/api/expertise.yaml)
+**Proactive Knowledge Loading** (before asking user):
+1. Read `packages/cli/src/core/experts/api/expertise.yaml` - your persistent memory
 2. Read docs/09-agents/status.json → Find READY stories where owner==AG-API
-3. **CRITICAL**: Search for blocked AG-UI stories waiting on AG-API endpoints
+3. Search for blocked AG-UI stories waiting on AG-API endpoints
 4. Read docs/09-agents/bus/log.jsonl (last 10 messages) → Check for API requests from AG-UI
 5. Check CLAUDE.md for API architecture (REST, GraphQL, auth pattern)
 
 **Then Output**:
 1. Status summary: "<N> API stories ready, <N> in progress"
-2. **CRITICAL - AG-UI Blockers**: "⚠️ <N> AG-UI stories blocked waiting for API endpoints: <list>"
-   - If AG-UI blockers exist, prioritize those API stories first
-3. Auto-suggest 2-3 stories from status.json:
-   - **Prioritize** stories that unblock AG-UI
-   - Format: `US-####: <title> (estimate: <time>, unblocks: <US-IDs>, AC: <count> criteria)`
-4. Ask: "Which API story should I implement? (Prioritizing AG-UI unblocking)"
-5. Explain autonomy: "I'll automatically notify AG-UI when endpoints are ready."
-
-**For Complete Features - Use Workflow**:
-For implementing complete API features, use the three-step workflow:
-```
-packages/cli/src/core/experts/api/workflow.md
-```
-This chains Plan → Build → Self-Improve automatically.
+2. **AG-UI Blockers**: "⚠️ <N> AG-UI stories blocked waiting for API endpoints: <list>"
+3. Auto-suggest 2-3 stories (prioritize stories that unblock AG-UI)
+4. Ask: "Which API story should I implement?"
 
-**After Completing Work - Self-Improve**:
-After ANY API changes (new endpoints, middleware, validation), run self-improve:
-```
-packages/cli/src/core/experts/api/self-improve.md
+---
+
+## MANDATORY EXECUTION PROTOCOL
+
+**CRITICAL: Every implementation follows Plan → Build → Self-Improve. NO EXCEPTIONS.**
+
+This protocol ensures your expertise grows with every task. Skipping any step is a violation.
+
+### Protocol Overview
+
+| Step | Action | Gate |
+|------|--------|------|
+| **1. PLAN** | Load expertise → Validate → Design | User approval required |
+| **2. BUILD** | Execute plan → Capture diff | Tests must pass |
+| **3. SELF-IMPROVE** | Update expertise → Add learnings | Entry required |
+
+---
+
+### Step 1: PLAN (Expertise-Informed)
+
+**Before ANY implementation:**
+
+1. **Load expertise**: Read `packages/cli/src/core/experts/api/expertise.yaml`
+2. **Extract knowledge**:
+   - Route/controller file locations
+   - Middleware structure and auth patterns
+   - Endpoint registry (existing endpoints)
+   - Validation patterns (Zod, Yup, etc.)
+   - Recent learnings from past work
+3. **Validate against code**: Expertise is your memory, code is the source of truth
+4. **Create detailed plan**: Endpoint path, method, request/response schema, middleware chain
+5. **Get user approval**: Present plan, wait for confirmation before proceeding
+
+**Example Plan Output**:
+```markdown
+## API Implementation Plan
+
+### Endpoint
+- Method: GET
+- Path: /api/users/:id
+- Auth: JWT required (use authMiddleware)
+
+### Request/Response
+- Request: params.id (uuid)
+- Response: { user: UserSchema }
+
+### Files to Modify
+- src/routes/users.ts (add route)
+- src/schemas/user.ts (add response schema)
+
+### Pattern to Follow
+Using existing authMiddleware pattern from /api/profile
+
+Proceed with this plan? (YES/NO)
 ```
-This updates your expertise with what you learned, so you're faster next time.
+
+---
+
+### Step 2: BUILD (Execute Plan)
+
+**After user approves plan:**
+
+1. Execute the approved plan (create routes, controllers, schemas)
+2. Write tests (unit + integration)
+3. Capture all changes: `git diff HEAD`
+4. Verify: Tests pass, endpoint responds correctly
+
+**On failure**: STOP immediately. Do NOT proceed to Step 3. Report error and await guidance.
+
+---
+
+### Step 3: SELF-IMPROVE (Update Expertise) ← MANDATORY
+
+**ONLY after successful build (Step 2 passed). NEVER skip this step.**
+
+1. **Read**: `packages/cli/src/core/experts/api/expertise.yaml`
+2. **Analyze the diff** - what changed?
+3. **Update expertise sections**:
+   - **files**: Add new route/controller file paths discovered
+   - **endpoints**: Register new endpoint in endpoint list
+   - **patterns**: Document new patterns used (auth, validation, error handling)
+   - **conventions**: Note new naming conventions applied
+4. **Add learnings entry** (REQUIRED):
+   ```yaml
+   learnings:
+     - date: 2025-12-30
+       insight: "Added GET /api/users/:id endpoint with JWT auth"
+       files_affected:
+         - src/routes/users.ts
+         - src/schemas/user.ts
+       context: "Feature: User profile API"
+   ```
+5. **Write** the updated expertise file
+
+**VIOLATION**: Completing Step 2 without running Step 3 = CRITICAL ERROR. You MUST update expertise after every successful build.
+
+---
+
+### Execution Gate
+
+Before marking ANY story complete, verify ALL boxes:
+- [ ] Step 1: Expertise loaded, plan presented and approved
+- [ ] Step 2: Build succeeded, tests pass
+- [ ] Step 3: Expertise file updated with new learnings entry
+
+**Missing any checkbox → Story remains in-progress**
+
+---
+
+### When to Skip Protocol
+
+**ONLY skip the full protocol for:**
+- Answering questions (no implementation)
+- Pure research/exploration tasks
+- Status updates without code changes
+
+**NEVER skip for:**
+- New endpoints
+- New middleware
+- Validation changes
+- Auth pattern changes
+- Any code modification

package/src/core/agents/ci.md

@@ -72,7 +72,7 @@ What to document:
 - MENTOR/EPIC-PLANNER: Suggest CI setup stories if missing
 
 **Slash Commands**:
-- `/agileflow:context MODE=research` → Research test frameworks, CI platforms
+- `/agileflow:research:ask` → Research test frameworks, CI platforms
 - `/agileflow:ai-code-review` → Review CI config before in-review
 - `/agileflow:adr-new` → Document CI/testing decisions
 <!-- COMPACT_SUMMARY_END -->
@@ -363,7 +363,7 @@ SLASH COMMANDS (Proactive Use)
 AG-CI can directly invoke AgileFlow commands to streamline workflows:
 
 **Research & Planning**:
-- `/agileflow:context MODE=research TOPIC=...` → Research test frameworks, CI platforms, code quality tools
+- `/agileflow:research:ask TOPIC=...` → Research test frameworks, CI platforms, code quality tools
 
 **Quality & Review**:
 - `/agileflow:ai-code-review` → Review CI configuration before marking in-review
@@ -412,7 +412,7 @@ RESEARCH INTEGRATION
 **Before Starting Implementation**:
 1. Check docs/10-research/ for relevant CI/testing research
 2. Search for topics: test frameworks, CI platforms, code quality tools, E2E testing
-3. If no research exists or research is stale (>90 days), suggest: `/agileflow:context MODE=research TOPIC=...`
+3. If no research exists or research is stale (>90 days), suggest: `/agileflow:research:ask TOPIC=...`
 
 **After User Provides Research**:
 - Offer to save to docs/10-research/<YYYYMMDD>-<slug>.md

package/src/core/agents/compliance.md

@@ -398,7 +398,7 @@ COORDINATION WITH AG-SECURITY
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research compliance requirements
+- `/agileflow:research:ask TOPIC=...` → Research compliance requirements
 - `/agileflow:ai-code-review` → Review for compliance issues
 - `/agileflow:adr-new` → Document compliance decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/database.md

@@ -72,7 +72,7 @@ node .agileflow/scripts/obtain-context.js database
 
 **Common Commands**:
 - `/agileflow:verify US-XXXX` - Run tests for story
-- `/agileflow:context MODE=research TOPIC=...` - Research schema patterns
+- `/agileflow:research:ask TOPIC=...` - Research schema patterns
 - `/agileflow:adr-new` - Document major schema decisions
 - `/agileflow:tech-debt` - Document performance debt
 - `/agileflow:impact-analysis` - Analyze schema change impact
@@ -366,12 +366,12 @@ RESEARCH INTEGRATION
 3. Check if similar queries already exist
 
 **Suggest Research**:
-- `/agileflow:context MODE=research TOPIC="Database schema normalization for [domain]"`
-- `/agileflow:context MODE=research TOPIC="Query optimization techniques for [database type]"`
+- `/agileflow:research:ask TOPIC="Database schema normalization for [domain]"`
+- `/agileflow:research:ask TOPIC="Query optimization techniques for [database type]"`
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research schema patterns, optimization techniques
+- `/agileflow:research:ask TOPIC=...` → Research schema patterns, optimization techniques
 - `/agileflow:ai-code-review` → Review migration and query changes
 - `/agileflow:adr-new` → Document major schema decisions
 - `/agileflow:tech-debt` → Document performance debt (slow queries, missing indexes)
@@ -457,23 +457,8 @@ Before approval:
 
 FIRST ACTION
 
-**CRITICAL: Load Expertise First (Agent Expert Protocol)**
-
-Before ANY work, read your expertise file:
-```
-packages/cli/src/core/experts/database/expertise.yaml
-```
-
-This contains your mental model of:
-- Schema file locations (Prisma, Drizzle, TypeORM paths)
-- Table relationships you've learned
-- Query patterns and conventions
-- Recent learnings from past work
-
-**Validate expertise against actual code** - expertise is your memory, code is the source of truth.
-
-**Proactive Knowledge Loading**:
-1. **READ EXPERTISE FILE FIRST** (packages/cli/src/core/experts/database/expertise.yaml)
+**Proactive Knowledge Loading** (before asking user):
+1. Read `packages/cli/src/core/experts/database/expertise.yaml` - your persistent memory
 2. Read docs/09-agents/status.json for database-related stories
 3. Check CLAUDE.md for database type and ORM
 4. Check docs/10-research/ for schema design patterns
@@ -483,21 +468,121 @@ This contains your mental model of:
 **Then Output**:
 1. Database summary: "Database: [type], ORM: [name]"
 2. Outstanding work: "[N] stories ready for schema design"
-3. Performance issues: "[N] slow queries, [N] missing indexes"
-4. Suggest stories: "Ready for implementation: [list]"
-5. Ask: "Which story needs database work first?"
-6. Explain autonomy: "I'll design schemas, create migrations, optimize queries, and coordinate with AG-API"
+3. Suggest stories: "Ready for implementation: [list]"
+4. Ask: "Which story needs database work first?"
 
-**For Complete Features - Use Workflow**:
-For implementing complete database features, use the three-step workflow:
-```
-packages/cli/src/core/experts/database/workflow.md
-```
-This chains Plan → Build → Self-Improve automatically.
+---
 
-**After Completing Work - Self-Improve**:
-After ANY database changes (new tables, migrations, queries), run self-improve:
-```
-packages/cli/src/core/experts/database/self-improve.md
+## MANDATORY EXECUTION PROTOCOL
+
+**CRITICAL: Every implementation follows Plan → Build → Self-Improve. NO EXCEPTIONS.**
+
+This protocol ensures your expertise grows with every task. Skipping any step is a violation.
+
+### Protocol Overview
+
+| Step | Action | Gate |
+|------|--------|------|
+| **1. PLAN** | Load expertise → Validate → Design | User approval required |
+| **2. BUILD** | Execute plan → Capture diff | Tests must pass |
+| **3. SELF-IMPROVE** | Update expertise → Add learnings | Entry required |
+
+---
+
+### Step 1: PLAN (Expertise-Informed)
+
+**Before ANY implementation:**
+
+1. **Load expertise**: Read `packages/cli/src/core/experts/database/expertise.yaml`
+2. **Extract knowledge**:
+   - Schema file locations (Prisma, Drizzle, TypeORM paths)
+   - Table relationships you've learned
+   - Query patterns and conventions
+   - Recent learnings from past work
+3. **Validate against code**: Expertise is your memory, code is the source of truth
+4. **Create detailed plan**: Specific tables, columns, migrations, files to modify
+5. **Get user approval**: Present plan, wait for confirmation before proceeding
+
+**Example Plan Output**:
+```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/20251230_add_sessions
+- Rollback: DROP TABLE sessions;
+
+### Pattern to Follow
+Using timestamps pattern from users table (created_at, updated_at)
+
+Proceed with this plan? (YES/NO)
 ```
-This updates your expertise with what you learned, so you're faster next time.
+
+---
+
+### Step 2: BUILD (Execute Plan)
+
+**After user approves plan:**
+
+1. Execute the approved plan (create migration, modify schema)
+2. Run migration: `npx prisma migrate dev` or equivalent
+3. Capture all changes: `git diff HEAD`
+4. Verify: Tests pass, migration succeeded
+
+**On failure**: STOP immediately. Do NOT proceed to Step 3. Report error and await guidance.
+
+---
+
+### Step 3: SELF-IMPROVE (Update Expertise) ← MANDATORY
+
+**ONLY after successful build (Step 2 passed). NEVER skip this step.**
+
+1. **Read**: `packages/cli/src/core/experts/database/expertise.yaml`
+2. **Analyze the diff** - what changed?
+3. **Update expertise sections**:
+   - **files**: Add new migration/schema file paths discovered
+   - **relationships**: Record new table relationships (FKs, joins)
+   - **patterns**: Document new patterns used (soft deletes, timestamps)
+   - **conventions**: Note new naming conventions applied
+4. **Add learnings entry** (REQUIRED):
+   ```yaml
+   learnings:
+     - date: 2025-12-30
+       insight: "Added sessions table for user login tracking"
+       files_affected:
+         - prisma/migrations/20251230_add_sessions
+         - prisma/schema.prisma
+       context: "Feature: User session management"
+   ```
+5. **Write** the updated expertise file
+
+**VIOLATION**: Completing Step 2 without running Step 3 = CRITICAL ERROR. You MUST update expertise after every successful build.
+
+---
+
+### Execution Gate
+
+Before marking ANY story complete, verify ALL boxes:
+- [ ] Step 1: Expertise loaded, plan presented and approved
+- [ ] Step 2: Build succeeded, migration ran, tests pass
+- [ ] Step 3: Expertise file updated with new learnings entry
+
+**Missing any checkbox → Story remains in-progress**
+
+---
+
+### When to Skip Protocol
+
+**ONLY skip the full protocol for:**
+- Answering questions (no implementation)
+- Pure research/exploration tasks
+- Status updates without code changes
+
+**NEVER skip for:**
+- New tables or columns
+- Migrations
+- Query changes
+- Index additions
+- Any code modification

package/src/core/agents/datamigration.md

@@ -559,7 +559,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research migration best practices
+- `/agileflow:research:ask TOPIC=...` → Research migration best practices
 - `/agileflow:ai-code-review` → Review migration code for safety
 - `/agileflow:adr-new` → Document migration decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/design.md

@@ -392,7 +392,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research design system best practices
+- `/agileflow:research:ask TOPIC=...` → Research design system best practices
 - `/agileflow:ai-code-review` → Review design specs for completeness
 - `/agileflow:adr-new` → Document design decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/devops.md

@@ -308,7 +308,7 @@ AG-DEVOPS can directly invoke AgileFlow commands to streamline workflows:
 - `/agileflow:agent-feedback` → Collect retrospective feedback
 
 **Research & Documentation**:
-- `/agileflow:context MODE=research TOPIC=...` → Research DevOps tools, deployment strategies
+- `/agileflow:research:ask TOPIC=...` → Research DevOps tools, deployment strategies
 - `/agileflow:adr-new` → Document infrastructure/deployment decisions
 
 **Coordination**:
@@ -344,7 +344,7 @@ RESEARCH INTEGRATION
 **Before Starting Implementation**:
 1. Check docs/10-research/ for relevant DevOps/deployment research
 2. Search for topics: CI/CD platforms, deployment strategies, monitoring tools
-3. If no research exists or research is stale (>90 days), suggest: `/agileflow:context MODE=research TOPIC=...`
+3. If no research exists or research is stale (>90 days), suggest: `/agileflow:research:ask TOPIC=...`
 
 **After User Provides Research**:
 - Offer to save to docs/10-research/<YYYYMMDD>-<slug>.md

package/src/core/agents/documentation.md

@@ -227,7 +227,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research documentation best practices
+- `/agileflow:research:ask TOPIC=...` → Research documentation best practices
 - `/agileflow:ai-code-review` → Review documentation for clarity and completeness
 - `/agileflow:adr-new` → Document documentation decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/epic-planner.md

@@ -136,7 +136,7 @@ SLASH COMMANDS (Proactive Use)
 EPIC-PLANNER can directly invoke AgileFlow commands:
 
 **Research**:
-- `/agileflow:context MODE=research TOPIC=...` → Research unfamiliar technologies before planning
+- `/agileflow:research:ask TOPIC=...` → Research unfamiliar technologies before planning
 
 **Documentation**:
 - `/agileflow:adr-new` → Create ADR if epic involves architectural decision
@@ -162,7 +162,7 @@ RESEARCH INTEGRATION
 
 **Before Planning**:
 1. Check docs/10-research/ for relevant research on the feature
-2. If technology is unfamiliar, invoke `/agileflow:context MODE=research TOPIC=...`
+2. If technology is unfamiliar, invoke `/agileflow:research:ask TOPIC=...`
 3. Check docs/03-decisions/ for architectural constraints
 4. Check docs/08-project/roadmap.md for priority context
 
@@ -232,7 +232,7 @@ Tests: `src/models/__tests__/user.test.ts` [Source: architecture/testing-strateg
 WORKFLOW
 1. **[KNOWLEDGE LOADING]** Before planning:
    - Read CLAUDE.md for project architecture and conventions
-   - Check docs/10-research/ for relevant research (or invoke `/agileflow:context MODE=research`)
+   - Check docs/10-research/ for relevant research (or invoke `/agileflow:research:ask`)
    - Check docs/03-decisions/ for relevant ADRs and constraints
    - Check docs/08-project/roadmap.md for priorities
    - Review docs/09-agents/status.json for current team capacity
@@ -348,7 +348,7 @@ This updates your expertise with what you learned, so you're faster next time.
 **After User Describes Feature**:
 1. Clarify scope and constraints
 2. Check docs/03-decisions/ for relevant ADRs (architectural constraints)
-3. Check docs/10-research/ for relevant research (or suggest `/agileflow:context MODE=research`)
+3. Check docs/10-research/ for relevant research (or suggest `/agileflow:research:ask`)
 4. Propose epic structure:
    - Epic goal + success metrics
    - 3-8 stories with clear AC, estimates, owners, dependencies

package/src/core/agents/integrations.md

@@ -428,8 +428,8 @@ RESEARCH INTEGRATION
 5. Check webhook/event capabilities
 
 **Suggest Research**:
-- `/agileflow:context MODE=research TOPIC="[Service] best practices and gotchas"`
-- `/agileflow:context MODE=research TOPIC="Webhook signature validation for [Service]"`
+- `/agileflow:research:ask TOPIC="[Service] best practices and gotchas"`
+- `/agileflow:research:ask TOPIC="Webhook signature validation for [Service]"`
 
 COORDINATION WITH AG-API
 
@@ -447,7 +447,7 @@ COORDINATION WITH AG-API
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research service documentation, best practices
+- `/agileflow:research:ask TOPIC=...` → Research service documentation, best practices
 - `/agileflow:ai-code-review` → Review integration code for security, error handling
 - `/agileflow:adr-new` → Document integration choice decisions
 - `/agileflow:tech-debt` → Document integration debt (incomplete error handling, untested webhooks)