agileflow 2.90.7 → 2.92.0

package/src/core/commands/story.md

@@ -1,6 +1,6 @@
 ---
 description: Create a user story with acceptance criteria
-argument-hint: EPIC=<EP-ID> STORY=<US-ID> TITLE=<text> OWNER=<id> [ESTIMATE=<pts>] [AC=<list>]
+argument-hint: EPIC=<EP-ID> STORY=<US-ID> TITLE=<text> OWNER=<id> [ESTIMATE=<pts>] [AC=<list>] [TDD=true]
 compact_context:
   priority: high
   preserve_rules:
@@ -12,12 +12,17 @@ compact_context:
     - "MUST use AskUserQuestion for user confirmation (YES/NO/CANCEL format)"
     - "MUST create test stub in docs/07-testing/test-cases/<STORY>.md referencing AC"
     - "AC format: Given/When/Then bullets (user story format)"
+    - "TDD=true: Generate framework-specific test code BEFORE implementation"
+    - "TDD=true: Parse Given/When/Then into describe/it blocks (Jest) or test functions (pytest)"
+    - "TDD=true: All tests start as .skip or @pytest.mark.skip (pending)"
+    - "TDD=true: Add tdd_mode:true and test_file fields to status.json entry"
   state_fields:
     - story_id
     - epic_id
     - owner
     - estimate
     - ac_count
+    - tdd_mode
 ---
 
 # story-new
@@ -44,7 +49,7 @@ node .agileflow/scripts/obtain-context.js story
 
 ### 🚨 RULE #1: ALWAYS Create TodoWrite Task List FIRST
 
-Create a 6-step task list IMMEDIATELY:
+Create a task list IMMEDIATELY (7 steps if TDD=true, 6 steps otherwise):
 ```xml
 <invoke name="TodoWrite">
 <parameter name="content">1. Parse inputs (EPIC, STORY, TITLE, OWNER, ESTIMATE, AC)
@@ -94,7 +99,45 @@ Test stub MUST reference AC:
 - Map each test to an AC bullet
 - Use BDD format (describe, test cases for each AC)
 
-### 🚨 RULE #5: NEVER Use echo/cat > For JSON Operations
+### 🚨 RULE #5: TDD MODE (Smart Defaults)
+
+**Smart TDD defaults based on OWNER:**
+| Owner | Default | Rationale |
+|-------|---------|-----------|
+| AG-API, AG-UI, AG-DATABASE | TDD=true | Code-focused, tests critical |
+| AG-TESTING, AG-SECURITY, AG-PERFORMANCE | TDD=true | Quality-focused |
+| AG-DOCUMENTATION, AG-RESEARCH, AG-PRODUCT | TDD=false | Non-code work |
+| AG-DEVOPS, AG-CI | TDD=false | Infrastructure, config |
+| Other/Custom | TDD=false | Explicit opt-in |
+
+**Override:** User can always specify `TDD=true` or `TDD=false` explicitly.
+
+When TDD mode is active, generate framework-specific test code:
+
+**Workflow:**
+1. Detect test framework from `environment.json` or `package.json`
+2. Parse AC into Given/When/Then structure
+3. Generate test file using `tdd-test-template.js`
+4. Create test in `__tests__/<STORY>.test.ts` (Jest) or `tests/test_<STORY>.py` (pytest)
+5. All tests start as `.skip` (pending)
+6. Add `tdd_mode: true` and `test_file` to status.json entry
+7. Add TDD badge to story file
+
+**Test File Location:**
+- Jest/Vitest: `__tests__/<STORY_ID>.test.ts`
+- pytest: `tests/test_<STORY_ID>.py`
+- Go: `<package>/<STORY_ID>_test.go`
+
+**Status.json Entry (TDD mode):**
+```json
+{
+  "tdd_mode": true,
+  "test_file": "__tests__/US-0042.test.ts",
+  "test_status": "not_run"
+}
+```
+
+### 🚨 RULE #6: NEVER Use echo/cat > For JSON Operations
 
 **ALWAYS use**:
 - Edit tool for small changes
@@ -114,6 +157,7 @@ OWNER=<id>                 # Agent or person name (required)
 ESTIMATE=<time>            # e.g., 0.5d, 2h (optional, default: 1d)
 AC=<bullets>               # Given/When/Then format (optional)
 DEPENDENCIES=[<list>]      # Dependent story IDs (optional)
+TDD=true|false             # TDD mode (smart default: true for code owners, false for docs/research)
 ```
 
 **Output Files Created**:
@@ -121,6 +165,7 @@ DEPENDENCIES=[<list>]      # Dependent story IDs (optional)
 |------|---------|----------|
 | docs/06-stories/EP-<ID>/US-<ID>-<slug>.md | Story with AC | story-template.md |
 | docs/07-testing/test-cases/US-<ID>.md | Test stub | BDD format |
+| __tests__/US-<ID>.test.ts | TDD test code (if TDD=true) | tdd-test-template.js |
 | docs/09-agents/status.json | Story entry | jq merge |
 | docs/09-agents/bus/log.jsonl | Assign event | JSONL line |
 
@@ -202,8 +247,9 @@ DEPENDENCIES=[<list>]      # Dependent story IDs (optional)
 - ALWAYS create test stub referencing AC
 - ALWAYS preview before confirming (prevents mistakes)
 - ALWAYS validate JSON after merge (prevents corruption)
-- Use TodoWrite for step tracking (6 steps)
+- Use TodoWrite for step tracking (6 steps, or 7 if TDD=true)
 - Files: story file, test file, status.json, bus/log.jsonl
+- **TDD=true**: Also create framework-specific test code in `__tests__/` with pending tests
 
 <!-- COMPACT_SUMMARY_END -->
 
@@ -324,3 +370,96 @@ After successfully creating the story, offer next steps:
 - `/agileflow:story-validate` - Validate story completeness
 - `/agileflow:status` - Update story status
 - `/agileflow:epic` - Create parent epic
+
+---
+
+## Expected Output
+
+### Successful Story Creation
+
+```
+📝 Creating Story: US-0042
+
+Epic: EP-0010
+Title: Login Form with Validation
+Owner: AG-UI
+Estimate: 2h
+TDD Mode: true (smart default for AG-UI)
+
+Files to create:
+───────────────────────────
+1. docs/06-stories/EP-0010/US-0042-login-form-validation.md
+   - Story file with 3 acceptance criteria
+
+2. docs/07-testing/test-cases/US-0042.md
+   - Test stub referencing AC
+
+3. __tests__/US-0042.test.ts (TDD mode)
+   - 3 pending test cases from AC
+
+4. docs/09-agents/status.json (merge)
+   + "US-0042": {
+   +   "id": "US-0042",
+   +   "epic": "EP-0010",
+   +   "owner": "AG-UI",
+   +   "status": "ready",
+   +   "estimate": "2h",
+   +   "tdd_mode": true,
+   +   "test_file": "__tests__/US-0042.test.ts"
+   + }
+
+5. docs/09-agents/bus/log.jsonl (append)
+   + {"ts":"...","type":"assign","from":"SYSTEM","to":"AG-UI","story":"US-0042"}
+
+[AskUserQuestion: "Create story US-0042: Login Form with Validation?"]
+
+✅ Story US-0042 created successfully!
+✅ Test stub created: docs/07-testing/test-cases/US-0042.md
+✅ TDD tests created: __tests__/US-0042.test.ts (3 pending)
+✅ Bus message sent: assign → AG-UI
+
+[AskUserQuestion: "What would you like to do next?"]
+```
+
+### Story with Dependencies
+
+```
+📝 Creating Story: US-0043
+
+Dependencies: US-0042 (Login Form)
+
+⚠️ Dependency Status:
+  • US-0042: ready (not yet done)
+
+[AskUserQuestion: "Create story with pending dependency?"]
+  - Yes, create anyway (dependency will block)
+  - No, wait for US-0042
+
+✅ Story US-0043 created
+⚠️ Status set to 'blocked' (waiting on US-0042)
+```
+
+### Validation Error
+
+```
+❌ Invalid Input
+
+Missing required parameters:
+  • EPIC - Parent epic ID (e.g., EP-0010)
+  • TITLE - Story title
+
+Usage:
+/agileflow:story EPIC=EP-0010 STORY=US-0042 TITLE="Login Form" OWNER=AG-UI
+```
+
+### TDD Mode Detection
+
+```
+📝 Story Creation
+
+Owner: AG-DOCUMENTATION
+TDD Mode: false (smart default - documentation work)
+
+ℹ️ To enable TDD mode, add TDD=true to the command:
+   /agileflow:story ... TDD=true
+```

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]
+```

package/src/core/templates/agileflow-metadata.json

@@ -1,8 +1,61 @@
 {
+  "schema_version": "2.0.0",
+  "config_schema_version": "2.92.0",
+  "active_profile": null,
   "agileflow": {
     "version": "2.28.0",
-    "setupDate": "TIMESTAMP_PLACEHOLDER",
-    "lastValidated": null,
+    "setup_date": "TIMESTAMP_PLACEHOLDER",
+    "last_validated": null,
+    "config_options": {
+      "claudeMdReinforcement": {
+        "available_since": "2.92.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Add /babysit AskUserQuestion rules to CLAUDE.md"
+      },
+      "sessionStartHook": {
+        "available_since": "2.35.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Welcome display with project status on session start"
+      },
+      "precompactHook": {
+        "available_since": "2.40.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Context preservation when conversation compacts"
+      },
+      "damageControlHooks": {
+        "available_since": "2.50.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Block destructive commands, protect sensitive paths"
+      },
+      "statusLine": {
+        "available_since": "2.35.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Custom status bar showing story/epic info"
+      },
+      "autoArchival": {
+        "available_since": "2.35.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Auto-archive completed stories older than threshold"
+      },
+      "autoUpdate": {
+        "available_since": "2.70.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Automatically update AgileFlow on session start"
+      },
+      "ralphLoop": {
+        "available_since": "2.60.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Autonomous story processing with test verification"
+      }
+    },
     "features": {
       "epics": true,
       "stories": true,