agileflow 2.90.7 → 2.91.0

package/src/core/commands/status.md

@@ -12,11 +12,14 @@ compact_context:
     - "MUST show diff preview before confirming (diff-first pattern)"
     - "Status values: ready|in-progress|blocked|in-review|done"
     - "MUST escape user text automatically (jq handles escaping)"
+    - "PHASE HANDOFF: Prompt for summary on phase transitions (ready→in-progress, in-progress→in-review, in-review→done)"
   state_fields:
     - story_id
     - current_status
     - new_status
     - pr_url
+    - phase_from
+    - phase_to
 ---
 
 # status
@@ -105,6 +108,7 @@ TO=<agent-id>           # Recipient agent for bus message (optional)
   "stories": {
     "US-0042": {
       "status": "in-progress",
+      "phase": "execute",
       "summary": "Started work on login form",
       "pr": "https://github.com/.../pull/42",
       "last_update": "ISO-timestamp"
@@ -113,6 +117,15 @@ TO=<agent-id>           # Recipient agent for bus message (optional)
 }
 ```
 
+**Phase Field** (auto-set based on status):
+| Status | Phase |
+|--------|-------|
+| ready | plan |
+| in-progress | execute |
+| blocked | execute |
+| in-review | audit |
+| done | complete |
+
 **Append to bus/log.jsonl**:
 ```json
 {"ts":"ISO-timestamp","from":"SYSTEM","to":"<TO or ALL>","type":"status","story":"<STORY>","status":"<STATUS>","text":"<SUMMARY>"}
@@ -146,6 +159,7 @@ docs/09-agents/status.json
 
 - "status": "ready",
 + "status": "in-progress",
++ "phase": "execute",
 + "summary": "Started work on login form",
 + "pr": "https://github.com/.../pull/42",
 ```
@@ -178,6 +192,7 @@ docs/09-agents/status.json
 - ALWAYS show diff before confirming
 - Status values: ready, in-progress, blocked, in-review, done
 - Text escaping handled automatically by jq
+- **PHASE HANDOFF**: On phase transitions (ready→in-progress, in-progress→in-review, in-review→done), prompt for handoff summary and log to bus/log.jsonl with type "phase_handoff"
 
 <!-- COMPACT_SUMMARY_END -->
 
@@ -192,7 +207,8 @@ STORY=<US-ID>  STATUS=in-progress|blocked|in-review|done
 SUMMARY=<1–2 lines>  PR=<url optional>  TO=<agent id optional>
 
 ACTIONS
-1) Update docs/09-agents/status.json (status,summary,last_update,pr).
+1) Update docs/09-agents/status.json (status,phase,summary,last_update,pr).
+   - Set phase based on status: ready→plan, in-progress/blocked→execute, in-review→audit, done→complete
    **CRITICAL**: Always use jq for JSON operations to prevent corruption.
 2) **Validate JSON after update**:
    ```bash
@@ -212,3 +228,112 @@ ACTIONS
 - If validation fails, restore from backup: docs/09-agents/status.json.backup
 
 Diff-first; YES/NO.
+
+---
+
+## Phase Handoff (GSD Integration)
+
+When status transitions indicate a phase change, prompt for a handoff summary to capture context for the next phase.
+
+### Phase Transitions
+
+| Status Change | Phase Transition | Handoff Prompt |
+|--------------|------------------|----------------|
+| ready → in-progress | plan → execute | "What's the plan for implementing this story?" |
+| in-progress → in-review | execute → audit | "What was implemented? Any issues encountered?" |
+| in-review → done | audit → complete | "Final summary: What was delivered?" |
+
+### Handoff Workflow
+
+**Step 1: Detect Phase Transition**
+
+Before updating status, check if this is a phase-changing transition:
+```javascript
+const phaseTransitions = {
+  'ready→in-progress': { from: 'plan', to: 'execute' },
+  'in-progress→in-review': { from: 'execute', to: 'audit' },
+  'in-review→done': { from: 'audit', to: 'complete' }
+};
+const key = `${currentStatus}→${newStatus}`;
+const transition = phaseTransitions[key];
+```
+
+**Step 2: Prompt for Handoff Summary**
+
+If a phase transition is detected, prompt BEFORE the status confirmation:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Phase transition: {{FROM}} → {{TO}}. Summarize what was accomplished:",
+  "header": "Handoff",
+  "multiSelect": false,
+  "options": [
+    {"label": "Enter summary", "description": "Capture context for next phase"},
+    {"label": "Skip handoff", "description": "No summary needed"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**Step 3: Log Phase Handoff**
+
+If summary provided, append to bus/log.jsonl:
+```json
+{
+  "ts": "2026-01-19T12:00:00Z",
+  "type": "phase_handoff",
+  "story": "US-0130",
+  "from": "plan",
+  "to": "execute",
+  "summary": "User's handoff summary here"
+}
+```
+
+### Example Flow
+
+```
+User: /agileflow:status US-0042 STATUS=in-progress
+
+Claude:
+📋 Phase Transition Detected: plan → execute
+
+Before updating status, let's capture a handoff summary.
+
+[AskUserQuestion: "What's the plan for implementing this story?"]
+
+User: "Adding login form with email/password validation, using React Hook Form"
+
+Claude:
+✅ Handoff captured
+
+docs/09-agents/status.json
+- "status": "ready",
++ "status": "in-progress",
++ "last_update": "2026-01-19T12:00:00Z"
+
+[AskUserQuestion: "Update US-0042 to in-progress?"]
+
+User: "Yes, update"
+
+Claude:
+✅ Status updated: US-0042 → in-progress
+✅ Phase handoff logged: plan → execute
+```
+
+### Handoff Prompts by Transition
+
+**plan → execute** (ready → in-progress):
+- "What's the implementation approach?"
+- "Any architectural decisions made?"
+- "Key files to be modified?"
+
+**execute → audit** (in-progress → in-review):
+- "What was implemented?"
+- "Any issues or blockers encountered?"
+- "Tests passing? Coverage notes?"
+
+**audit → complete** (in-review → done):
+- "Final summary of what was delivered"
+- "Any technical debt introduced?"
+- "Lessons learned?"

package/src/core/commands/story/list.md

@@ -76,17 +76,17 @@ Format output as table grouped by epic:
 ## Stories
 
 ### EP-0001: Authentication System
-| Story | Title | Status | Owner | Estimate |
-|-------|-------|--------|-------|----------|
-| US-0001 | Login form | done | AG-UI | 2h |
-| US-0002 | Password reset | in_progress | AG-API | 3h |
-| US-0003 | Session management | ready | AG-API | 4h |
+| Story | Title | Status | Phase | Owner | Estimate |
+|-------|-------|--------|-------|-------|----------|
+| US-0001 | Login form | done | complete | AG-UI | 2h |
+| US-0002 | Password reset | in_progress | execute | AG-API | 3h |
+| US-0003 | Session management | ready | plan | AG-API | 4h |
 
 ### EP-0002: User Dashboard
-| Story | Title | Status | Owner | Estimate |
-|-------|-------|--------|-------|----------|
-| US-0004 | Dashboard layout | ready | AG-UI | 2h |
-| US-0005 | Activity feed | ready | AG-UI | 3h |
+| Story | Title | Status | Phase | Owner | Estimate |
+|-------|-------|--------|-------|-------|----------|
+| US-0004 | Dashboard layout | ready | plan | AG-UI | 2h |
+| US-0005 | Activity feed | ready | plan | AG-UI | 3h |
 
 ---
 **Summary**: 5 stories (1 done, 1 in_progress, 3 ready)

package/src/core/commands/story/view.md

@@ -92,6 +92,7 @@ cat docs/07-testing/test-cases/<STORY>.md
 
 **Epic**: EP-0001 (Authentication System)
 **Status**: in_progress
+**Phase**: execute
 **Owner**: AG-UI
 **Estimate**: 3h
 **Created**: 2024-12-28

package/src/core/experts/codebase-query/expertise.yaml

@@ -0,0 +1,190 @@
+# Codebase Query Expert - Domain Knowledge
+# This file is the agent's "mental model" of codebase querying
+# AUTO-UPDATED by self-improve.md after completing work
+
+domain: codebase-query
+last_updated: 2026-01-19
+version: 1.0
+
+# Query interface components
+files:
+  query_script:
+    - path: packages/cli/scripts/query-codebase.js
+      purpose: "CLI for codebase queries"
+      commands:
+        - "--build-index: Build/rebuild codebase index"
+        - "--query=<pattern>: Smart search (glob + tag + export)"
+        - "--content=<regex>: Search file content"
+        - "--tag=<tag>: Search by tag"
+        - "--export=<symbol>: Find export locations"
+        - "--deps=<file>: Show file dependencies"
+
+  indexer:
+    - path: packages/cli/lib/codebase-indexer.js
+      purpose: "Core indexing logic"
+      functions:
+        - "buildIndex(rootDir): Full index build"
+        - "updateIndex(rootDir): Incremental update"
+        - "getIndex(rootDir): Get cached or build"
+        - "queryFiles(index, pattern): Glob matching"
+        - "queryByTag(index, tag): Tag lookup"
+        - "queryByExport(index, symbol): Export search"
+        - "getDependencies(index, file): Import graph"
+
+  cache:
+    - path: .agileflow/cache/codebase-index.json
+      purpose: "Persistent index storage"
+      ttl: "60 seconds in-memory, persistent on disk"
+
+# Query type mappings
+query_types:
+  files:
+    flag: "--query"
+    description: "Smart search combining glob, tag, and export matching"
+    examples:
+      - input: "auth files"
+        translation: '--query="auth"'
+      - input: "api routes"
+        translation: '--query="src/api/**/*.ts"'
+      - input: "test files"
+        translation: '--query="**/*.test.{js,ts}"'
+
+  content:
+    flag: "--content"
+    description: "Grep-style regex content search"
+    examples:
+      - input: "files with validateToken"
+        translation: '--content="validateToken"'
+      - input: "error handling patterns"
+        translation: '--content="try.*catch|\.catch\\("'
+      - input: "React hooks usage"
+        translation: '--content="use(State|Effect|Ref|Context)"'
+
+  tag:
+    flag: "--tag"
+    description: "Search by auto-detected tag"
+    examples:
+      - input: "API endpoints"
+        translation: '--tag="api"'
+      - input: "UI components"
+        translation: '--tag="ui"'
+      - input: "database models"
+        translation: '--tag="database"'
+
+  export:
+    flag: "--export"
+    description: "Find files exporting a symbol"
+    examples:
+      - input: "where is login defined"
+        translation: '--export="login"'
+      - input: "UserService export"
+        translation: '--export="UserService"'
+
+  deps:
+    flag: "--deps"
+    description: "Show file dependencies"
+    examples:
+      - input: "what depends on auth.ts"
+        translation: '--deps="src/auth.ts"'
+      - input: "utils dependencies"
+        translation: '--deps="src/lib/utils.js"'
+
+# Available tags (auto-detected from paths)
+available_tags:
+  api:
+    patterns: ["/api/", "/routes/", "/endpoints/", "/controllers/"]
+    description: "API endpoints and routes"
+  ui:
+    patterns: ["/components/", "/ui/", "/views/", "/pages/"]
+    description: "UI components and views"
+  database:
+    patterns: ["/db/", "/database/", "/models/", "/schema/", "/migrations/"]
+    description: "Database models and migrations"
+  auth:
+    patterns: ["/auth/", "/login/", "/session/", "/jwt/", "/oauth/"]
+    description: "Authentication logic"
+  test:
+    patterns: ["/test/", "/tests/", "/__tests__/", "/spec/", "/specs/"]
+    description: "Test files"
+  config:
+    patterns: ["/config/", "/settings/", "/env/"]
+    description: "Configuration files"
+  lib:
+    patterns: ["/lib/", "/utils/", "/helpers/", "/shared/"]
+    description: "Utility libraries"
+  docs:
+    patterns: ["/docs/", "/documentation/"]
+    description: "Documentation files"
+  scripts:
+    patterns: ["/scripts/", "/bin/", "/tools/"]
+    description: "Build and utility scripts"
+  types:
+    patterns: ["/types/", "/typings/", "/interfaces/"]
+    description: "Type definitions"
+
+# Natural language patterns
+nl_patterns:
+  - pattern: "where is * defined"
+    query_type: export
+    extraction: "symbol from *"
+  - pattern: "what files use *"
+    query_type: export
+    extraction: "symbol from *"
+  - pattern: "* files"
+    query_type: query
+    extraction: "keyword from *"
+  - pattern: "files with *"
+    query_type: content
+    extraction: "regex from *"
+  - pattern: "* in the codebase"
+    query_type: query
+    extraction: "keyword from *"
+  - pattern: "dependencies of *"
+    query_type: deps
+    extraction: "file path from *"
+  - pattern: "what depends on *"
+    query_type: deps
+    extraction: "file path from *"
+
+# Fallback strategies
+fallbacks:
+  index_unavailable:
+    description: "When index cannot be built or is corrupted"
+    strategy:
+      - "Use Glob tool for file pattern matching"
+      - "Use Grep tool for content searching"
+      - "Combine results manually"
+
+  no_results:
+    description: "When query returns no matches"
+    strategy:
+      - "Try broader search terms"
+      - "Check for typos in symbol names"
+      - "Try content search instead of export search"
+      - "Suggest related tags"
+
+# Conventions
+conventions:
+  - "Always check index status before querying"
+  - "Translate natural language to structured queries"
+  - "Combine multiple query types for complex searches"
+  - "Respect token budget (default 15000 chars)"
+  - "Show file counts and truncation notices"
+  - "READ-ONLY: Never use Write/Edit tools"
+
+# Learnings from codebase exploration
+learnings:
+  - date: 2026-01-19
+    context: "Initial indexer implementation"
+    insight: "Index build takes ~6.5s for 1777 files, use incremental updates for speed"
+    source: "packages/cli/lib/codebase-indexer.js"
+
+  - date: 2026-01-19
+    context: "Tag detection"
+    insight: "9 auto-detected tags available: api, ui, database, auth, test, config, lib, docs, scripts"
+    source: "packages/cli/lib/codebase-indexer.js:TAG_PATTERNS"
+
+  - date: 2026-01-19
+    context: "Export tracking"
+    insight: "477 exports tracked across codebase, searchable via --export flag"
+    source: "query-codebase.js --build-index output"

package/src/core/experts/codebase-query/question.md

@@ -0,0 +1,73 @@
+---
+description: Ask questions about codebase-query - uses expertise for fast, accurate answers
+argument-hint: <your question>
+variables:
+  EXPERTISE_FILE: packages/cli/src/core/experts/codebase-query/expertise.yaml
+---
+
+# Codebase Query Expert - Question
+
+You are an expert on the codebase-query 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 `packages/cli/src/core/experts/codebase-query/expertise.yaml` FIRST, before doing anything else.
+
+This file contains:
+- Query types and their translations
+- Available tags and patterns
+- Natural language pattern mappings
+- Fallback strategies
+- Recent learnings from past queries
+
+### 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 query script still works as documented
+2. Verify your understanding matches current behavior
+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 - include exact query commands
+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 testing
+- **Accuracy**: Always validate against actual behavior
+- **Honesty**: Acknowledge when expertise is stale
+- **Learning**: Note discrepancies for self-improve
+
+## Common Questions
+
+### "How do I search for X?"
+1. Check `query_types` in expertise for matching type
+2. Check `nl_patterns` for natural language mapping
+3. Provide the exact command
+
+### "What tags are available?"
+Reference `available_tags` in expertise, validate they exist in TAG_PATTERNS.
+
+### "Why did my query return no results?"
+Check `fallbacks.no_results` for strategies, suggest alternatives.
+
+### "How does the index work?"
+Reference `files.indexer` for implementation details.
+
+## Anti-Patterns to Avoid
+
+- Reading expertise but ignoring it
+- Testing queries before checking expertise
+- Trusting expertise blindly without validation
+- Giving vague answers when expertise has specifics
+
+## Question
+
+{{argument}}

package/src/core/experts/codebase-query/self-improve.md

@@ -0,0 +1,105 @@
+---
+description: Update codebase-query expertise after making changes
+argument-hint: [optional context about what changed]
+variables:
+  EXPERTISE_FILE: packages/cli/src/core/experts/codebase-query/expertise.yaml
+---
+
+# Codebase Query 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 `packages/cli/src/core/experts/codebase-query/expertise.yaml`.
+
+Understand what you currently know about:
+- Query types and translations
+- Available tags
+- Natural language patterns
+- Fallback strategies
+
+### Step 2: Analyze What Changed
+
+**If git diff available:**
+```bash
+git diff HEAD~1 --name-only | grep -E "(codebase-indexer|query-codebase)"
+```
+
+**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 `query_types` section if:**
+- New query flags added
+- Query behavior changed
+- New examples discovered
+
+**Update `available_tags` section if:**
+- New tags added to TAG_PATTERNS
+- Tag patterns changed
+- Tag descriptions updated
+
+**Update `nl_patterns` section if:**
+- New natural language patterns discovered
+- Better translations found
+- User preferences learned
+
+**Update `fallbacks` section if:**
+- New fallback strategies needed
+- Edge cases discovered
+- Error handling improved
+
+**ALWAYS add to `learnings` section:**
+```yaml
+learnings:
+  - date: YYYY-MM-DD
+    context: "What prompted this update"
+    insight: "What you learned"
+    source: "Where you learned it"
+```
+
+### Step 4: Save Updated Expertise
+Edit the expertise file with your updates.
+
+### Learning Signals
+
+**High-confidence signals** (definitely add to learnings):
+- User explicitly corrected a translation
+- Query returned wrong results
+- New query pattern worked well
+- Index build revealed new patterns
+
+**Medium-confidence signals** (consider adding):
+- User rephrased query differently
+- Multiple query types combined
+- Fallback strategy used
+
+**Low-confidence signals** (observe but don't add yet):
+- Single-use query patterns
+- Unusual file structures
+
+### Example Learning Entry
+
+```yaml
+learnings:
+  - date: 2026-01-19
+    context: "User asked for 'authentication middleware'"
+    insight: "Combine --tag='auth' with --query='middleware' for auth middleware files"
+    source: "User query feedback"
+```
+
+## Output Format
+
+After updating, confirm:
+```
+Updated expertise.yaml:
+- Added learning: [brief description]
+- Updated [section]: [what changed]
+- Version: [new version]
+```