agileflow 2.33.1 → 2.35.0

package/src/core/commands/context.md

@@ -1,5 +1,6 @@
 ---
 description: Generate context export for web AI tools
+argument-hint: [MODE=full|export|note|research] [NOTE=<text>] [TOPIC=<text>] [DETAILS=<text>]
 allowed-tools: Bash, Read, Edit, Write, Glob, Grep
 ---
 

package/src/core/commands/deps.md

@@ -1,6 +1,8 @@
 ---
 description: Visualize dependency graph with critical path detection
+argument-hint: [SCOPE=story|epic|all] [EPIC=<id>] [STORY=<id>] [FORMAT=ascii|mermaid|graphviz|json] [ANALYSIS=critical-path|circular|blocking|all]
 allowed-tools: Bash, Read, Edit, Write, Glob, Grep
+model: haiku
 ---
 
 # dependencies

package/src/core/commands/diagnose.md

@@ -30,8 +30,6 @@ JSON_FILES=(
   "docs/00-meta/agileflow-metadata.json"
   "docs/09-agents/status.json"
   "docs/09-agents/status-archive.json"
-  "docs/08-project/github-sync-map.json"
-  "docs/08-project/notion-sync-map.json"
   ".claude/settings.json"
 )
 
@@ -162,45 +160,6 @@ fi
 
 echo ""
 
-# Check 5: MCP Integration
-echo "🔌 MCP Integration"
-echo "------------------"
-
-if [ -f .mcp.json ]; then
-  if jq empty .mcp.json 2>/dev/null; then
-    echo "  ✅ .mcp.json is valid JSON"
-
-    # Check if in .gitignore
-    if grep -q "^\\.mcp\\.json$" .gitignore 2>/dev/null; then
-      echo "  ✅ .mcp.json is in .gitignore (secure)"
-    else
-      echo "  ⚠️  WARNING: .mcp.json is NOT in .gitignore"
-      echo "     This is a SECURITY RISK - add it immediately!"
-      JSON_ERRORS=$((JSON_ERRORS + 1))
-    fi
-  else
-    echo "  ❌ .mcp.json is INVALID JSON"
-    JSON_ERRORS=$((JSON_ERRORS + 1))
-  fi
-else
-  echo "  ℹ️  MCP not configured (.mcp.json not found)"
-fi
-
-if [ -f .env ]; then
-  # Check if in .gitignore
-  if grep -q "^\\.env$" .gitignore 2>/dev/null; then
-    echo "  ✅ .env is in .gitignore (secure)"
-  else
-    echo "  ⚠️  WARNING: .env is NOT in .gitignore"
-    echo "     This is a SECURITY RISK - add it immediately!"
-    JSON_ERRORS=$((JSON_ERRORS + 1))
-  fi
-else
-  echo "  ℹ️  .env not found (optional if MCP not configured)"
-fi
-
-echo ""
-
 # Final Summary
 echo "📊 Diagnostic Summary"
 echo "====================="

package/src/core/commands/epic.md

@@ -1,5 +1,6 @@
 ---
 description: Create a new epic with stories
+argument-hint: EPIC=<EP-ID> TITLE=<text> OWNER=<id> GOAL=<text> [STORIES=<list>]
 allowed-tools: Bash, Read, Edit, Write, Glob, Grep
 ---
 
@@ -11,6 +12,9 @@ Create a new epic with optional child stories.
 
 ROLE: Epic Creator
 
+OBJECTIVE
+Analyze feature requirements and create structured epics with associated stories. Evaluate story breakdown, assess dependencies, and consider implementation sequencing to ensure comprehensive planning.
+
 TODO LIST TRACKING
 **CRITICAL**: Immediately create a todo list using TodoWrite tool to track epic creation:
 ```
@@ -31,6 +35,10 @@ OWNER=<name or agent id>
 GOAL=<outcome/metric>
 STORIES=<optional> comma-separated "<US_ID>|<short title>|<owner>"
 
+TEMPLATE
+Use the following epic template structure:
+@packages/cli/src/core/templates/epic-template.md
+
 ACTIONS
 1) Create docs/05-epics/<EPIC>.md from epic-template.md (status=active; created/updated=now).
 2) For each story, create docs/06-stories/<EPIC>/<US_ID>-<slug>.md from story-template.md (status=ready; estimate=0.5d; deps=[]).

package/src/core/commands/handoff.md

@@ -26,6 +26,10 @@ INPUTS
 STORY=<US-ID>  FROM=<id>  TO=<id>
 SUMMARY=<what changed>  BLOCKERS=<optional list>
 
+TEMPLATE
+Use the following comms note template:
+@packages/cli/src/core/templates/comms-note-template.md
+
 ACTIONS
 1) Create docs/09-agents/comms/<STORY>-<YYYYMMDD>-handoff.md from comms-note-template.md.
 2) Append bus line type="handoff".

package/src/core/commands/impact.md

@@ -12,7 +12,7 @@ Analyze the impact of code changes on other parts of the codebase.
 ROLE: Impact Analyzer
 
 OBJECTIVE
-Identify which files, tests, and features are affected by code changes to prevent regressions.
+Analyze and identify which files, tests, and features are affected by code changes to prevent regressions. Evaluate dependencies comprehensively, assess risk levels, and consider indirect impacts across the codebase.
 
 INPUTS (optional)
 - FILES=<comma-separated paths> (default: auto-detect from git diff)

package/src/core/commands/metrics.md

@@ -1,6 +1,8 @@
 ---
 description: Analytics dashboard with cycle time and throughput
+argument-hint: [TIMEFRAME=7d|30d|90d|all] [EPIC=<id>] [OWNER=<id>] [FORMAT=ascii|json|csv] [METRIC=cycle-time|lead-time|throughput|all]
 allowed-tools: Bash, Read, Edit, Write, Glob, Grep
+model: haiku
 ---
 
 # metrics
@@ -14,6 +16,14 @@ ROLE: Metrics & Analytics Specialist
 OBJECTIVE
 Generate comprehensive project metrics from AgileFlow data sources (status.json, bus/log.jsonl, story files) to enable data-driven decision making.
 
+CONTEXT
+
+Live repository state:
+- Current branch: !`git branch --show-current`
+- Recent commits: !`git log --since="30 days ago" --oneline | wc -l`
+- Active stories: !`grep -c '"status":"in-progress"' docs/09-agents/status.json 2>/dev/null || echo "0"`
+- Bus log entries: !`wc -l < docs/09-agents/bus/log.jsonl 2>/dev/null || echo "0"`
+
 INPUTS (optional)
 - TIMEFRAME=7d|30d|90d|all (default: 30d)
 - EPIC=<EP_ID> (filter by specific epic)

package/src/core/commands/research.md

@@ -11,6 +11,9 @@ Initialize or save research notes to the research folder.
 
 ROLE: Research Initializer
 
+OBJECTIVE
+Evaluate and organize research findings with structured analysis. Assess relevance, consider key insights, and examine sources to create comprehensive research documentation.
+
 TODO LIST TRACKING
 **CRITICAL**: Immediately create a todo list using TodoWrite tool to track research initialization:
 ```

package/src/core/commands/retro.md

@@ -1,6 +1,8 @@
 ---
 description: Generate retrospective with Start/Stop/Continue format
+argument-hint: [TIMEFRAME=sprint|2weeks|30d|90d] [EPIC=<id>] [FORMAT=ascii|markdown|html] [SAVE=true|false]
 allowed-tools: Bash, Read, Edit, Write, Glob, Grep
+model: haiku
 ---
 
 # retro
@@ -30,6 +32,14 @@ Mark each step complete as you finish it. This ensures comprehensive retrospecti
 OBJECTIVE
 Automatically generate retrospective insights by analyzing bus/log.jsonl, status.json, and story data to surface what went well, what needs improvement, and actionable next steps.
 
+CONTEXT
+
+Live repository state:
+- Current branch: !`git branch --show-current`
+- Sprint activity: !`git log --since="14 days ago" --oneline | wc -l`
+- Contributors: !`git log --since="14 days ago" --format='%an' | sort -u`
+- Recent completions: !`tail -10 docs/09-agents/bus/log.jsonl 2>/dev/null | grep -c '"status":"done"' || echo "0"`
+
 INPUTS (optional)
 - TIMEFRAME=sprint|2weeks|30d|90d (default: 2weeks)
 - EPIC=<EP_ID> (retrospective for specific epic)
@@ -516,7 +526,7 @@ USAGE EXAMPLES
 /AgileFlow:retro SAVE=false
 ```
 
-### Export as markdown for Notion
+### Export as markdown
 ```bash
 /AgileFlow:retro FORMAT=markdown > retro.md
 ```

package/src/core/commands/sprint.md

@@ -1,6 +1,8 @@
 ---
 description: Data-driven sprint planning with velocity forecasting
+argument-hint: [SPRINT=<id>] [DURATION=<days>] [AGENTS=<list>] [MODE=suggest|commit] [FOCUS_EPIC=<id>]
 allowed-tools: Bash, Read, Edit, Write, Glob, Grep
+model: haiku
 ---
 
 # sprint-plan
@@ -470,7 +472,6 @@ ${MODE == "commit" && "1. ✅ Sprint committed! Stories updated in status.json"}
 2. Assign first stories: /AgileFlow:assign STORY=US-0043 (highest priority)
 3. Monitor progress: /AgileFlow:board
 4. Track blockers: /AgileFlow:blockers
-5. Sync to external systems: /AgileFlow:github-sync or /AgileFlow:notion
 ```
 
 RULES

package/src/core/commands/status.md

@@ -1,5 +1,6 @@
 ---
 description: Update story status and progress
+argument-hint: STORY=<US-ID> STATUS=<status> [SUMMARY=<text>] [PR=<url>] [TO=<agent-id>]
 allowed-tools: Bash, Read, Edit, Write, Glob, Grep
 ---
 

package/src/core/commands/story-validate.md

@@ -26,7 +26,7 @@ TODO LIST TRACKING
 Mark each step complete as you finish it. This ensures thorough validation.
 
 OBJECTIVE
-Validate that a story is complete, well-structured, and ready for implementation. Check for:
+Comprehensively analyze and validate that a story is complete, well-structured, and ready for implementation. Evaluate each aspect critically and assess readiness:
 1. All required sections present (per story template)
 2. Architecture Context populated with source citations
 3. Clear, testable Acceptance Criteria

package/src/core/commands/story.md

@@ -19,7 +19,7 @@ TODO LIST TRACKING
 3. Create docs/07-testing/test-cases/<STORY>.md stub
 4. Merge into docs/09-agents/status.json
 5. Append assign line to bus/log.jsonl
-6. Show preview and wait for YES/NO confirmation
+6. Show preview and confirm with AskUserQuestion
 ```
 
 Mark each step complete as you finish it. This ensures nothing is forgotten.
@@ -30,9 +30,36 @@ OWNER=<name or agent id>  ESTIMATE=<e.g., 0.5d>
 DEPENDENCIES=[US-000X,...] (optional)
 AC=<Given/When/Then bullets>
 
+TEMPLATE
+Use the following template structure:
+@packages/cli/src/core/templates/story-template.md
+
 ACTIONS
 1) Create docs/06-stories/<EPIC>/<STORY>-<slug>.md from story-template.md with frontmatter & AC.
 2) Create docs/07-testing/test-cases/<STORY>.md (stub referencing AC).
 3) Merge into docs/09-agents/status.json; append "assign" line to bus/log.jsonl.
 
-Diff-first; YES/NO.
+**Show diff-first, then confirm with AskUserQuestion**:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Create story <STORY>: <TITLE> with these files?",
+  "header": "Create story",
+  "multiSelect": false,
+  "options": [
+    {
+      "label": "Yes, create story",
+      "description": "Write story file, test stub, and update status.json (Recommended)"
+    },
+    {
+      "label": "No, revise first",
+      "description": "I want to modify the content before creating"
+    },
+    {
+      "label": "Cancel",
+      "description": "Don't create this story"
+    }
+  ]
+}]</parameter>
+</invoke>
+```

package/src/core/commands/template.md

@@ -31,6 +31,14 @@ AgileFlow includes default templates in `docs/00-meta/templates/`:
 - `research-template.md` - Research notes
 - `README-template.md` - Folder READMEs
 
+**Built-in Template References** (view actual templates):
+- Story Template: @packages/cli/src/core/templates/story-template.md
+- Epic Template: @packages/cli/src/core/templates/epic-template.md
+- ADR Template: @packages/cli/src/core/templates/adr-template.md
+- Agent Profile: @packages/cli/src/core/templates/agent-profile-template.md
+- Comms Note: @packages/cli/src/core/templates/comms-note-template.md
+- Research: @packages/cli/src/core/templates/research-template.md
+
 Users can create custom templates for:
 - Meeting notes
 - Sprint retrospectives

package/src/core/commands/update.md

@@ -265,7 +265,7 @@ FORMAT VARIATIONS
 Plain text or HTML email ready to send
 
 ### Markdown
-For posting to internal wikis, Notion, etc.
+For posting to internal wikis, documentation platforms, etc.
 
 ### Slides
 Generate slide deck outline:

package/src/core/commands/velocity.md

@@ -1,6 +1,7 @@
 ---
 description: Track velocity and forecast sprint capacity
 allowed-tools: Bash, Read, Edit, Write, Glob, Grep
+model: haiku
 ---
 
 # velocity
@@ -14,6 +15,14 @@ ROLE: Velocity Analyst & Forecaster
 OBJECTIVE
 Calculate team velocity from completed stories, identify trends, and forecast epic/milestone completion dates.
 
+CONTEXT
+
+Live repository state:
+- Current branch: !`git branch --show-current`
+- Commits this week: !`git log --since="7 days ago" --oneline | wc -l`
+- Bus log activity: !`tail -5 docs/09-agents/bus/log.jsonl 2>/dev/null || echo "No bus log found"`
+- Stories completed recently: !`grep -c '"status":"done"' docs/09-agents/status.json 2>/dev/null || echo "0"`
+
 INPUTS (optional)
 - PERIOD=week|sprint|month|all (default: sprint - last 2 weeks)
 - FORECAST=<EPIC_ID or milestone> (predict completion date)

package/src/core/commands/verify.md

@@ -11,6 +11,12 @@ You are running the `/AgileFlow:verify` command to execute project tests and upd
 
 Execute project tests and update `test_status` for stories in `docs/09-agents/status.json`. This is a core component of the **Session Harness System** (introduced in v2.24.0) that ensures test verification before and after implementation work.
 
+## Context
+
+- Current branch: !`git branch --show-current`
+- Git status: !`git status --short`
+- Last commit: !`git log -1 --oneline`
+
 ## TODO LIST TRACKING
 
 **CRITICAL**: Immediately create a todo list using TodoWrite tool to track test verification:

package/src/core/templates/validate-tokens.sh

@@ -49,21 +49,6 @@ else
   echo "ℹ️  NOTION_TOKEN not found in .env (optional if Notion not enabled)"
 fi
 
-echo ""
-
-# Check Context7 token (secure - doesn't print value)
-if grep -q "^CONTEXT7_API_KEY=" .env && ! grep -q "CONTEXT7_API_KEY=$" .env; then
-  TOKEN_VALUE=$(grep "^CONTEXT7_API_KEY=" .env | cut -d'=' -f2)
-  if [ -z "$TOKEN_VALUE" ] || [ "$TOKEN_VALUE" = "your_key_here" ] || [[ "$TOKEN_VALUE" == *"placeholder"* ]]; then
-    echo "⚠️  CONTEXT7_API_KEY is set but appears to be placeholder"
-    echo "    → Replace with real key (optional for higher rate limits)"
-  else
-    echo "✅ CONTEXT7_API_KEY is set (length: ${#TOKEN_VALUE})"
-  fi
-else
-  echo "ℹ️  CONTEXT7_API_KEY not found in .env (optional)"
-fi
-
 echo ""
 echo "🔒 Security Check:"
 

package/src/core/templates/worktrees-guide.md

@@ -178,10 +178,6 @@ git branch -d feature/new-feature
 
 AgileFlow's message bus (`docs/09-agents/bus/log.jsonl`) is shared across all worktrees. The bus is append-only (JSONL), so concurrent appends are generally safe. However, **status.json** uses read-modify-write, so avoid concurrent edits to the same stories.
 
-### GitHub & Notion Sync
-
-If you have GitHub or Notion MCP integration enabled, each worktree can sync independently. Both updates go to the same GitHub repo/Notion workspace (shared .git).
-
 ## Troubleshooting
 
 ### "fatal: 'branch' is already checked out"

package/tools/agileflow-npx.js

@@ -7,7 +7,7 @@
  * It preserves the user's working directory when spawning the CLI.
  */
 
-const { execSync } = require('node:child_process');
+const { spawnSync } = require('node:child_process');
 const path = require('node:path');
 const fs = require('node:fs');
 
@@ -25,15 +25,27 @@ if (isNpxExecution) {
     process.exit(1);
   }
 
-  try {
-    // Execute CLI from user's working directory (process.cwd()), not npm cache
-    execSync(`node "${cliPath}" ${args.join(' ')}`, {
-      stdio: 'inherit',
-      cwd: process.cwd(),
-    });
-  } catch (error) {
-    process.exit(error.status || 1);
+  // Execute CLI from user's working directory (process.cwd()), not npm cache
+  const result = spawnSync(process.execPath, [cliPath, ...args], {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+  });
+
+  if (result.error) {
+    console.error('Error: Failed to run AgileFlow CLI:', result.error.message);
+    process.exit(1);
+  }
+
+  if (result.signal) {
+    try {
+      process.kill(process.pid, result.signal);
+    } catch {
+      process.exit(1);
+    }
+    process.exit(1);
   }
+
+  process.exit(result.status ?? 0);
 } else {
   // Local execution - use require
   require('./cli/agileflow-cli.js');