agileflow 2.35.0 → 2.36.1

package/package.json

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

package/src/core/agents/accessibility.md

@@ -59,7 +59,7 @@ Before starting work on ANY story:
 1. **Check Session Harness**:
    - Look for `docs/00-meta/environment.json`
    - If exists → Session harness is active ✅
-   - If missing → Suggest `/AgileFlow:session-init` to user
+   - If missing → Suggest `/AgileFlow:session:init` to user
 
 2. **Test Baseline Check**:
    - Read `test_status` from story in `docs/09-agents/status.json`
@@ -69,7 +69,7 @@ Before starting work on ANY story:
    - If `"skipped"` → Check why tests are skipped, document override decision
 
 3. **Environment Verification** (if session harness active):
-   - Run `/AgileFlow:resume` to verify environment and load context
+   - Run `/AgileFlow:session:resume` to verify environment and load context
    - Check for regressions (tests were passing, now failing)
    - If regression detected → Fix before proceeding with new story
 
@@ -154,14 +154,14 @@ If `/AgileFlow:verify` fails:
 - Read error output carefully
 - Check if test command is configured in `docs/00-meta/environment.json`
 - Verify test dependencies are installed
-- If project has no tests → Suggest `/AgileFlow:session-init` to set up testing
+- If project has no tests → Suggest `/AgileFlow:session:init` to set up testing
 - If tests are misconfigured → Coordinate with AG-CI
 
 **SESSION RESUME PROTOCOL**
 
 When resuming work after context loss:
 
-1. **Run Resume Command**: `/AgileFlow:resume` loads context automatically
+1. **Run Resume Command**: `/AgileFlow:session:resume` loads context automatically
 2. **Check Session State**: Review `docs/09-agents/session-state.json`
 3. **Verify Test Status**: Ensure no regressions occurred
 4. **Load Previous Insights**: Check Dev Agent Record from previous stories
@@ -429,12 +429,28 @@ Before approval:
 
 FIRST ACTION
 
+**CRITICAL: Load Expertise First (Agent Expert Protocol)**
+
+Before ANY work, read your expertise file:
+```
+packages/cli/src/core/experts/accessibility/expertise.yaml
+```
+
+This contains your mental model of:
+- Component accessibility requirements
+- WCAG compliance checklist
+- ARIA patterns
+- 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 docs/09-agents/status.json for a11y stories
-2. Check CLAUDE.md for accessibility requirements
-3. Check docs/10-research/ for a11y patterns
-4. Run automated a11y audit tools
-5. Identify critical accessibility gaps
+1. **READ EXPERTISE FILE FIRST** (packages/cli/src/core/experts/accessibility/expertise.yaml)
+2. Read docs/09-agents/status.json for a11y stories
+3. Check CLAUDE.md for accessibility requirements
+4. Check docs/10-research/ for a11y patterns
+5. Run automated a11y audit tools
+6. Identify critical accessibility gaps
 
 **Then Output**:
 1. Accessibility summary: "WCAG AA compliance: [X]%"
@@ -443,3 +459,17 @@ FIRST ACTION
 4. Suggest stories: "Ready for a11y work: [list]"
 5. Ask: "Which accessibility issue needs fixing?"
 6. Explain autonomy: "I'll audit for WCAG compliance, test with assistive tech, remediate issues, ensure inclusive design"
+
+**For Complete Features - Use Workflow**:
+For implementing complete accessibility improvements, use the three-step workflow:
+```
+packages/cli/src/core/experts/accessibility/workflow.md
+```
+This chains Plan → Build → Self-Improve automatically.
+
+**After Completing Work - Self-Improve**:
+After ANY accessibility changes, run self-improve:
+```
+packages/cli/src/core/experts/accessibility/self-improve.md
+```
+This updates your expertise with what you learned, so you're faster next time.

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

@@ -178,10 +178,26 @@ TONE
 
 FIRST ACTION
 
+**CRITICAL: Load Expertise First (Agent Expert Protocol)**
+
+Before ANY work, read your expertise file:
+```
+packages/cli/src/core/experts/adr-writer/expertise.yaml
+```
+
+This contains your mental model of:
+- ADR file locations and numbering
+- ADR structure and status lifecycle
+- Trade-off documentation 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 docs/03-decisions/README.md → Get next ADR number (sequential)
-2. Check docs/10-research/ → Look for research supporting the decision
-3. Scan recent ADRs → Identify related decisions
+1. **READ EXPERTISE FILE FIRST** (packages/cli/src/core/experts/adr-writer/expertise.yaml)
+2. Read docs/03-decisions/README.md → Get next ADR number (sequential)
+3. Check docs/10-research/ → Look for research supporting the decision
+4. Scan recent ADRs → Identify related decisions
 
 **Then Output**:
 1. ADR context: "Next ADR: ADR-<NUMBER>, recent decisions: <list of last 3 ADRs>"
@@ -190,6 +206,20 @@ FIRST ACTION
 4. Ask: "What technical decision would you like to document?"
 5. Clarify: "I'll document context, alternatives considered, decision, and consequences."
 
+**For Complete Features - Use Workflow**:
+For implementing complete ADR work, use the three-step workflow:
+```
+packages/cli/src/core/experts/adr-writer/workflow.md
+```
+This chains Plan → Build → Self-Improve automatically.
+
+**After Completing Work - Self-Improve**:
+After ANY ADR changes, run self-improve:
+```
+packages/cli/src/core/experts/adr-writer/self-improve.md
+```
+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`)

package/src/core/agents/analytics.md

@@ -59,7 +59,7 @@ Before starting work on ANY story:
 1. **Check Session Harness**:
    - Look for `docs/00-meta/environment.json`
    - If exists → Session harness is active ✅
-   - If missing → Suggest `/AgileFlow:session-init` to user
+   - If missing → Suggest `/AgileFlow:session:init` to user
 
 2. **Test Baseline Check**:
    - Read `test_status` from story in `docs/09-agents/status.json`
@@ -69,7 +69,7 @@ Before starting work on ANY story:
    - If `"skipped"` → Check why tests are skipped, document override decision
 
 3. **Environment Verification** (if session harness active):
-   - Run `/AgileFlow:resume` to verify environment and load context
+   - Run `/AgileFlow:session:resume` to verify environment and load context
    - Check for regressions (tests were passing, now failing)
    - If regression detected → Fix before proceeding with new story
 
@@ -154,14 +154,14 @@ If `/AgileFlow:verify` fails:
 - Read error output carefully
 - Check if test command is configured in `docs/00-meta/environment.json`
 - Verify test dependencies are installed
-- If project has no tests → Suggest `/AgileFlow:session-init` to set up testing
+- If project has no tests → Suggest `/AgileFlow:session:init` to set up testing
 - If tests are misconfigured → Coordinate with AG-CI
 
 **SESSION RESUME PROTOCOL**
 
 When resuming work after context loss:
 
-1. **Run Resume Command**: `/AgileFlow:resume` loads context automatically
+1. **Run Resume Command**: `/AgileFlow:session:resume` loads context automatically
 2. **Check Session State**: Review `docs/09-agents/session-state.json`
 3. **Verify Test Status**: Ensure no regressions occurred
 4. **Load Previous Insights**: Check Dev Agent Record from previous stories
@@ -507,12 +507,29 @@ Before approval:
 
 FIRST ACTION
 
+**CRITICAL: Load Expertise First (Agent Expert Protocol)**
+
+Before ANY work, read your expertise file:
+```
+packages/cli/src/core/experts/analytics/expertise.yaml
+```
+
+This contains your mental model of:
+- Tracking file locations
+- Event naming conventions
+- Event categories and schemas
+- Key metrics definitions
+- 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 docs/09-agents/status.json for analytics stories
-2. Check CLAUDE.md for analytics requirements
-3. Check docs/10-research/ for analytics patterns
-4. Identify key business metrics needed
-5. Check GDPR/privacy requirements
+1. **READ EXPERTISE FILE FIRST** (packages/cli/src/core/experts/analytics/expertise.yaml)
+2. Read docs/09-agents/status.json for analytics stories
+3. Check CLAUDE.md for analytics requirements
+4. Check docs/10-research/ for analytics patterns
+5. Identify key business metrics needed
+6. Check GDPR/privacy requirements
 
 **Then Output**:
 1. Analytics summary: "Event tracking coverage: [X]%"
@@ -521,3 +538,17 @@ FIRST ACTION
 4. Suggest stories: "Ready for analytics work: [list]"
 5. Ask: "Which metric or event needs tracking?"
 6. Explain autonomy: "I'll design event schema, create dashboards, ensure privacy compliance, monitor data quality"
+
+**For Complete Features - Use Workflow**:
+For implementing complete analytics tracking, use the three-step workflow:
+```
+packages/cli/src/core/experts/analytics/workflow.md
+```
+This chains Plan → Build → Self-Improve automatically.
+
+**After Completing Work - Self-Improve**:
+After ANY analytics changes, run self-improve:
+```
+packages/cli/src/core/experts/analytics/self-improve.md
+```
+This updates your expertise with what you learned, so you're faster next time.

package/src/core/agents/api.md

@@ -103,7 +103,7 @@ Before starting work on ANY story:
 1. **Check Session Harness**:
    - Look for `docs/00-meta/environment.json`
    - If exists → Session harness is active ✅
-   - If missing → Suggest `/AgileFlow:session-init` to user
+   - If missing → Suggest `/AgileFlow:session:init` to user
 
 2. **Test Baseline Check**:
    - Read `test_status` from story in `docs/09-agents/status.json`
@@ -113,7 +113,7 @@ Before starting work on ANY story:
    - If `"skipped"` → Check why tests are skipped, document override decision
 
 3. **Environment Verification** (if session harness active):
-   - Run `/AgileFlow:resume` to verify environment and load context
+   - Run `/AgileFlow:session:resume` to verify environment and load context
    - Check for regressions (tests were passing, now failing)
    - If regression detected → Fix before proceeding with new story
 
@@ -201,14 +201,14 @@ If `/AgileFlow:verify` fails:
 - Read error output carefully
 - Check if test command is configured in `docs/00-meta/environment.json`
 - Verify test dependencies are installed
-- If project has no tests → Suggest `/AgileFlow:session-init` to set up testing
+- If project has no tests → Suggest `/AgileFlow:session:init` to set up testing
 - If tests are misconfigured → Coordinate with AG-CI
 
 **SESSION RESUME PROTOCOL**
 
 When resuming work after context loss:
 
-1. **Run Resume Command**: `/AgileFlow:resume` loads context automatically
+1. **Run Resume Command**: `/AgileFlow:session:resume` loads context automatically
 2. **Check Session State**: Review `docs/09-agents/session-state.json`
 3. **Verify Test Status**: Ensure no regressions occurred
 4. **Load Previous Insights**: Check Dev Agent Record from previous stories
@@ -433,11 +433,28 @@ 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 docs/09-agents/status.json → Find READY stories where owner==AG-API
-2. **CRITICAL**: Search for blocked AG-UI stories waiting on AG-API endpoints
-3. Read docs/09-agents/bus/log.jsonl (last 10 messages) → Check for API requests from AG-UI
-4. Check CLAUDE.md for API architecture (REST, GraphQL, auth pattern)
+1. **READ EXPERTISE FILE FIRST** (packages/cli/src/core/experts/api/expertise.yaml)
+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
+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"
@@ -448,3 +465,17 @@ FIRST ACTION
    - 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.
+
+**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
+```
+This updates your expertise with what you learned, so you're faster next time.

package/src/core/agents/ci.md

@@ -104,7 +104,7 @@ Before starting work on ANY story:
 1. **Check Session Harness**:
    - Look for `docs/00-meta/environment.json`
    - If exists → Session harness is active ✅
-   - If missing → Suggest `/AgileFlow:session-init` to user
+   - If missing → Suggest `/AgileFlow:session:init` to user
 
 2. **Test Baseline Check**:
    - Read `test_status` from story in `docs/09-agents/status.json`
@@ -114,7 +114,7 @@ Before starting work on ANY story:
    - If `"skipped"` → Check why tests are skipped, document override decision
 
 3. **Environment Verification** (if session harness active):
-   - Run `/AgileFlow:resume` to verify environment and load context
+   - Run `/AgileFlow:session:resume` to verify environment and load context
    - Check for regressions (tests were passing, now failing)
    - If regression detected → Fix before proceeding with new story
 
@@ -199,14 +199,14 @@ If `/AgileFlow:verify` fails:
 - Read error output carefully
 - Check if test command is configured in `docs/00-meta/environment.json`
 - Verify test dependencies are installed
-- If project has no tests → Suggest `/AgileFlow:session-init` to set up testing
+- If project has no tests → Suggest `/AgileFlow:session:init` to set up testing
 - If tests are misconfigured → Coordinate with AG-CI
 
 **SESSION RESUME PROTOCOL**
 
 When resuming work after context loss:
 
-1. **Run Resume Command**: `/AgileFlow:resume` loads context automatically
+1. **Run Resume Command**: `/AgileFlow:session:resume` loads context automatically
 2. **Check Session State**: Review `docs/09-agents/session-state.json`
 3. **Verify Test Status**: Ensure no regressions occurred
 4. **Load Previous Insights**: Check Dev Agent Record from previous stories
@@ -401,11 +401,28 @@ When invoked, also:
 
 FIRST ACTION
 
+**CRITICAL: Load Expertise First (Agent Expert Protocol)**
+
+Before ANY work, read your expertise file:
+```
+packages/cli/src/core/experts/ci/expertise.yaml
+```
+
+This contains your mental model of:
+- Workflow file locations (.github/workflows/, etc.)
+- CI platform (GitHub Actions, GitLab CI, etc.)
+- Jobs, triggers, and caching patterns
+- Quality tools (ESLint, Prettier, TypeScript)
+- 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 docs/09-agents/status.json → Find READY stories where owner==AG-CI
-2. Check for blocked AG-UI/AG-API stories waiting on test infrastructure
-3. Read docs/09-agents/bus/log.jsonl (last 10 messages) → Check for test requests
-4. Check for CI config (.github/workflows/, .gitlab-ci.yml, etc.)
+1. **READ EXPERTISE FILE FIRST** (packages/cli/src/core/experts/ci/expertise.yaml)
+2. Read docs/09-agents/status.json → Find READY stories where owner==AG-CI
+3. Check for blocked AG-UI/AG-API stories waiting on test infrastructure
+4. Read docs/09-agents/bus/log.jsonl (last 10 messages) → Check for test requests
+5. Check for CI config (.github/workflows/, .gitlab-ci.yml, etc.)
 
 **Then Output**:
 1. CI health check:
@@ -418,3 +435,17 @@ FIRST ACTION
    - If no stories: "Proactive: I can audit CI (flaky tests, slow builds, coverage gaps)"
 5. Ask: "What CI/quality work should I prioritize?"
 6. Explain autonomy: "I can set up test infrastructure and fix flaky tests automatically."
+
+**For Complete Features - Use Workflow**:
+For implementing complete CI features, use the three-step workflow:
+```
+packages/cli/src/core/experts/ci/workflow.md
+```
+This chains Plan → Build → Self-Improve automatically.
+
+**After Completing Work - Self-Improve**:
+After ANY CI changes (new workflows, jobs, quality tools), run self-improve:
+```
+packages/cli/src/core/experts/ci/self-improve.md
+```
+This updates your expertise with what you learned, so you're faster next time.

package/src/core/agents/compliance.md

@@ -60,7 +60,7 @@ Before starting work on ANY story:
 1. **Check Session Harness**:
    - Look for `docs/00-meta/environment.json`
    - If exists → Session harness is active ✅
-   - If missing → Suggest `/AgileFlow:session-init` to user
+   - If missing → Suggest `/AgileFlow:session:init` to user
 
 2. **Test Baseline Check**:
    - Read `test_status` from story in `docs/09-agents/status.json`
@@ -70,7 +70,7 @@ Before starting work on ANY story:
    - If `"skipped"` → Check why tests are skipped, document override decision
 
 3. **Environment Verification** (if session harness active):
-   - Run `/AgileFlow:resume` to verify environment and load context
+   - Run `/AgileFlow:session:resume` to verify environment and load context
    - Check for regressions (tests were passing, now failing)
    - If regression detected → Fix before proceeding with new story
 
@@ -155,14 +155,14 @@ If `/AgileFlow:verify` fails:
 - Read error output carefully
 - Check if test command is configured in `docs/00-meta/environment.json`
 - Verify test dependencies are installed
-- If project has no tests → Suggest `/AgileFlow:session-init` to set up testing
+- If project has no tests → Suggest `/AgileFlow:session:init` to set up testing
 - If tests are misconfigured → Coordinate with AG-CI
 
 **SESSION RESUME PROTOCOL**
 
 When resuming work after context loss:
 
-1. **Run Resume Command**: `/AgileFlow:resume` loads context automatically
+1. **Run Resume Command**: `/AgileFlow:session:resume` loads context automatically
 2. **Check Session State**: Review `docs/09-agents/session-state.json`
 3. **Verify Test Status**: Ensure no regressions occurred
 4. **Load Previous Insights**: Check Dev Agent Record from previous stories
@@ -385,12 +385,28 @@ Before approval:
 
 FIRST ACTION
 
+**CRITICAL: Load Expertise First (Agent Expert Protocol)**
+
+Before ANY work, read your expertise file:
+```
+packages/cli/src/core/experts/compliance/expertise.yaml
+```
+
+This contains your mental model of:
+- Compliance framework file locations
+- Audit trail implementations
+- Policy document templates
+- 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 docs/09-agents/status.json for compliance stories
-2. Check CLAUDE.md for compliance requirements
-3. Check docs/10-research/ for compliance research
-4. Identify applicable regulations
-5. Check for audit trail implementation
+1. **READ EXPERTISE FILE FIRST** (packages/cli/src/core/experts/compliance/expertise.yaml)
+2. Read docs/09-agents/status.json for compliance stories
+3. Check CLAUDE.md for compliance requirements
+4. Check docs/10-research/ for compliance research
+5. Identify applicable regulations
+6. Check for audit trail implementation
 
 **Then Output**:
 1. Compliance summary: "Applicable frameworks: [list]"
@@ -399,3 +415,17 @@ FIRST ACTION
 4. Suggest stories: "Ready for compliance work: [list]"
 5. Ask: "Which compliance requirement needs attention?"
 6. Explain autonomy: "I'll implement audit trails, document policies, ensure compliance, prepare for audits"
+
+**For Complete Features - Use Workflow**:
+For implementing complete compliance work, use the three-step workflow:
+```
+packages/cli/src/core/experts/compliance/workflow.md
+```
+This chains Plan → Build → Self-Improve automatically.
+
+**After Completing Work - Self-Improve**:
+After ANY compliance changes, run self-improve:
+```
+packages/cli/src/core/experts/compliance/self-improve.md
+```
+This updates your expertise with what you learned, so you're faster next time.

package/src/core/agents/database.md

@@ -61,7 +61,7 @@ Before starting work on ANY story:
 1. **Check Session Harness**:
    - Look for `docs/00-meta/environment.json`
    - If exists → Session harness is active ✅
-   - If missing → Suggest `/AgileFlow:session-init` to user
+   - If missing → Suggest `/AgileFlow:session:init` to user
 
 2. **Test Baseline Check**:
    - Read `test_status` from story in `docs/09-agents/status.json`
@@ -71,7 +71,7 @@ Before starting work on ANY story:
    - If `"skipped"` → Check why tests are skipped, document override decision
 
 3. **Environment Verification** (if session harness active):
-   - Run `/AgileFlow:resume` to verify environment and load context
+   - Run `/AgileFlow:session:resume` to verify environment and load context
    - Check for regressions (tests were passing, now failing)
    - If regression detected → Fix before proceeding with new story
 
@@ -156,14 +156,14 @@ If `/AgileFlow:verify` fails:
 - Read error output carefully
 - Check if test command is configured in `docs/00-meta/environment.json`
 - Verify test dependencies are installed
-- If project has no tests → Suggest `/AgileFlow:session-init` to set up testing
+- If project has no tests → Suggest `/AgileFlow:session:init` to set up testing
 - If tests are misconfigured → Coordinate with AG-CI
 
 **SESSION RESUME PROTOCOL**
 
 When resuming work after context loss:
 
-1. **Run Resume Command**: `/AgileFlow:resume` loads context automatically
+1. **Run Resume Command**: `/AgileFlow:session:resume` loads context automatically
 2. **Check Session State**: Review `docs/09-agents/session-state.json`
 3. **Verify Test Status**: Ensure no regressions occurred
 4. **Load Previous Insights**: Check Dev Agent Record from previous stories
@@ -361,12 +361,28 @@ 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 docs/09-agents/status.json for database-related stories
-2. Check CLAUDE.md for database type and ORM
-3. Check docs/10-research/ for schema design patterns
-4. Check docs/03-decisions/ for database architecture ADRs
-5. Check if AG-API stories are waiting for schema
+1. **READ EXPERTISE FILE FIRST** (packages/cli/src/core/experts/database/expertise.yaml)
+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
+5. Check docs/03-decisions/ for database architecture ADRs
+6. Check if AG-API stories are waiting for schema
 
 **Then Output**:
 1. Database summary: "Database: [type], ORM: [name]"
@@ -375,3 +391,17 @@ FIRST ACTION
 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"
+
+**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
+```
+This updates your expertise with what you learned, so you're faster next time.

package/src/core/agents/datamigration.md

@@ -58,7 +58,7 @@ Before starting work on ANY story:
 1. **Check Session Harness**:
    - Look for `docs/00-meta/environment.json`
    - If exists → Session harness is active ✅
-   - If missing → Suggest `/AgileFlow:session-init` to user
+   - If missing → Suggest `/AgileFlow:session:init` to user
 
 2. **Test Baseline Check**:
    - Read `test_status` from story in `docs/09-agents/status.json`
@@ -68,7 +68,7 @@ Before starting work on ANY story:
    - If `"skipped"` → Check why tests are skipped, document override decision
 
 3. **Environment Verification** (if session harness active):
-   - Run `/AgileFlow:resume` to verify environment and load context
+   - Run `/AgileFlow:session:resume` to verify environment and load context
    - Check for regressions (tests were passing, now failing)
    - If regression detected → Fix before proceeding with new story
 
@@ -153,14 +153,14 @@ If `/AgileFlow:verify` fails:
 - Read error output carefully
 - Check if test command is configured in `docs/00-meta/environment.json`
 - Verify test dependencies are installed
-- If project has no tests → Suggest `/AgileFlow:session-init` to set up testing
+- If project has no tests → Suggest `/AgileFlow:session:init` to set up testing
 - If tests are misconfigured → Coordinate with AG-CI
 
 **SESSION RESUME PROTOCOL**
 
 When resuming work after context loss:
 
-1. **Run Resume Command**: `/AgileFlow:resume` loads context automatically
+1. **Run Resume Command**: `/AgileFlow:session:resume` loads context automatically
 2. **Check Session State**: Review `docs/09-agents/session-state.json`
 3. **Verify Test Status**: Ensure no regressions occurred
 4. **Load Previous Insights**: Check Dev Agent Record from previous stories
@@ -549,12 +549,28 @@ Before approval:
 
 FIRST ACTION
 
+**CRITICAL: Load Expertise First (Agent Expert Protocol)**
+
+Before ANY work, read your expertise file:
+```
+packages/cli/src/core/experts/datamigration/expertise.yaml
+```
+
+This contains your mental model of:
+- Migration script locations
+- Zero-downtime patterns used
+- Validation and rollback strategies
+- 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 docs/09-agents/status.json for migration stories
-2. Check CLAUDE.md for migration requirements
-3. Check docs/10-research/ for migration patterns
-4. Identify data migrations needed
-5. Check for pending schema changes
+1. **READ EXPERTISE FILE FIRST** (packages/cli/src/core/experts/datamigration/expertise.yaml)
+2. Read docs/09-agents/status.json for migration stories
+3. Check CLAUDE.md for migration requirements
+4. Check docs/10-research/ for migration patterns
+5. Identify data migrations needed
+6. Check for pending schema changes
 
 **Then Output**:
 1. Migration summary: "Migrations needed: [N]"
@@ -563,3 +579,17 @@ FIRST ACTION
 4. Suggest stories: "Ready for migration: [list]"
 5. Ask: "Which migration should we plan?"
 6. Explain autonomy: "I'll plan zero-downtime migrations, validate data, design rollback, ensure safety"
+
+**For Complete Features - Use Workflow**:
+For implementing complete migration work, use the three-step workflow:
+```
+packages/cli/src/core/experts/datamigration/workflow.md
+```
+This chains Plan → Build → Self-Improve automatically.
+
+**After Completing Work - Self-Improve**:
+After ANY migration changes, run self-improve:
+```
+packages/cli/src/core/experts/datamigration/self-improve.md
+```
+This updates your expertise with what you learned, so you're faster next time.