agileflow 2.42.0 → 2.43.0

package/src/core/commands/deps.md

@@ -10,25 +10,14 @@ Visualize and analyze story/epic dependency graphs with critical path analysis a
 
 ---
 
-## 🚨 STEP 0: ACTIVATE COMMAND (REQUIRED FIRST)
-
-**Before doing ANYTHING else, run this to register the command for context preservation:**
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'deps', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ Deps command activated');
-}
-"
+node scripts/obtain-context.js deps
 ```
 
+This gathers git status, stories/epics, session state, and registers for PreCompact.
+
 ---
 
 <!-- COMPACT_SUMMARY_START -->

package/src/core/commands/docs.md

@@ -9,23 +9,10 @@ Synchronize documentation with codebase changes.
 
 ---
 
-## 🚨 STEP 0: ACTIVATE COMMAND (REQUIRED FIRST)
-
-**Before doing ANYTHING else, run this to register the command for context preservation:**
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'docs', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ Docs command activated');
-}
-"
+node scripts/obtain-context.js docs
 ```
 
 ---

package/src/core/commands/epic.md

@@ -7,25 +7,14 @@ argument-hint: EPIC=<EP-ID> TITLE=<text> OWNER=<id> GOAL=<text> [STORIES=<list>]
 
 ---
 
-## 🚨 STEP 0: ACTIVATE COMMAND (REQUIRED FIRST)
-
-**Before doing ANYTHING else, run this to register the command for context preservation:**
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'epic', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ Epic command activated');
-}
-"
+node scripts/obtain-context.js epic
 ```
 
+This gathers git status, stories/epics, session state, and registers for PreCompact.
+
 ---
 
 Create a new epic with optional child stories.

package/src/core/commands/help.md

@@ -8,26 +8,15 @@ Display a concise overview of the AgileFlow system.
 
 ---
 
-## STEP 0: Activation
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'help', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ help command activated');
-}
-"
+node scripts/obtain-context.js help
 ```
 
 ---
 
-## STEP 0: Activation (Documentation)
+## Context Loading (Documentation)
 
 **PURPOSE**: Immediately load full context before executing any logic.
 

package/src/core/commands/metrics.md

@@ -8,25 +8,14 @@ model: haiku
 
 ---
 
-## 🚨 STEP 0: ACTIVATE COMMAND (REQUIRED FIRST)
-
-**Before doing ANYTHING else, run this to register the command for context preservation:**
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'metrics', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ Metrics command activated');
-}
-"
+node scripts/obtain-context.js metrics
 ```
 
+This gathers git status, stories/epics, session state, and registers for PreCompact.
+
 ---
 
 Comprehensive project analytics dashboard with cycle time, lead time, throughput, and trend analysis.

package/src/core/commands/packages.md

@@ -8,26 +8,15 @@ Manage project package dependencies (npm, pip, cargo, etc.) with dashboard, upda
 
 ---
 
-## STEP 0: Activation
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'packages', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ packages command activated');
-}
-"
+node scripts/obtain-context.js packages
 ```
 
 ---
 
-## STEP 0: Activation (Documentation)
+## Context Loading (Documentation)
 
 **PURPOSE**: Immediately load full context before executing any logic.
 

package/src/core/commands/pr.md

@@ -5,23 +5,14 @@ argument-hint: STORY=<US-ID> [TITLE=<text>] [TEST_EVIDENCE=<text>]
 
 # pr-template
 
-## STEP 0: Activation
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'pr-template', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ pr-template command activated');
-}
-"
+node scripts/obtain-context.js pr
 ```
 
+This gathers git status, stories/epics, session state, and registers for PreCompact.
+
 ---
 
 <!-- COMPACT_SUMMARY_START -->

package/src/core/commands/readme-sync.md

@@ -9,26 +9,15 @@ Synchronize a folder's README.md with its current contents.
 
 ---
 
-## STEP 0: Activation
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'readme-sync', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ readme-sync command activated');
-}
-"
+node scripts/obtain-context.js readme-sync
 ```
 
 ---
 
-## STEP 0: Activation (Documentation)
+## Context Loading (Documentation)
 
 **PURPOSE**: Immediately load full context before executing any logic.
 
@@ -58,7 +47,7 @@ if (fs.existsSync(path)) {
 - **AskUserQuestion**: Use XML format with multiSelect for decisions
 - **Output**: Updates only "## Contents" section, preserves all other sections
 - **Use Cases**: After adding files, before releases, documentation cleanup, reorganizing folders
-- **Related**: docs/02-practices/async-agent-spawning.md, ask-user-question.md
+- **Related**: Async agent spawning patterns, AskUserQuestion format
 <!-- COMPACT_SUMMARY_END -->
 
 ---
@@ -70,7 +59,7 @@ ROLE: README Sync Orchestrator
 🔴 **AskUserQuestion Format** (when asking decisions):
 - NEVER ask users to "type" anything - use proper options
 - Use XML invoke format with multiSelect for multiple choices
-- See `docs/02-practices/ask-user-question.md` for examples
+- See AskUserQuestion format examples in any configuration agent
 
 INPUTS
 FOLDER=<path>   Path to folder (e.g., docs/02-practices)
@@ -178,9 +167,6 @@ Found 8 files:
   • ci.md – CI/CD pipeline configuration, testing gates
   • security.md – Security practices, input validation, authentication
   • releasing.md – Release procedures, versioning, changelog
-  • diagrams.md – Mermaid diagram generation with light/dark themes
-  • async-agent-spawning.md – Launch, monitor, and retrieve background agents
-  • ask-user-question.md – Using the AskUserQuestion tool effectively
 
 Proposed Changes to ## Contents Section:
 ─────────────────────────────────────────
@@ -189,9 +175,6 @@ Proposed Changes to ## Contents Section:
 - **ci.md** – CI/CD pipeline configuration, testing gates
 - **security.md** – Security practices, input validation, authentication
 - **releasing.md** – Release procedures, versioning, changelog
-- **diagrams.md** – Mermaid diagram generation with light/dark themes
-- **async-agent-spawning.md** – Launch, monitor, and retrieve background agents
-- **ask-user-question.md** – Using the AskUserQuestion tool effectively
 
 Update README.md with these changes? (YES/NO)
 ```
@@ -224,5 +207,5 @@ Only the `## Contents` section of README.md:
 - Preserves custom notes and links
 
 RELATED
-- [Diagram Practice](docs/02-practices/diagrams.md) - How to create diagrams
-- [Async Agent Spawning](docs/02-practices/async-agent-spawning.md) - Background agent patterns
+- CLAUDE.md - Project conventions and practices
+- Mermaid diagram syntax - For flowcharts and sequence diagrams

package/src/core/commands/research.md

@@ -8,26 +8,15 @@ Initialize or save research notes to the research folder.
 
 ---
 
-## STEP 0: Activation
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'research-init', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ research-init command activated');
-}
-"
+node scripts/obtain-context.js research
 ```
 
 ---
 
-## STEP 0: Activation (Documentation)
+## Context Loading (Documentation)
 
 **PURPOSE**: Immediately load full context before executing any logic.
 

package/src/core/commands/retro.md

@@ -8,25 +8,14 @@ model: haiku
 
 ---
 
-## 🚨 STEP 0: ACTIVATE COMMAND (REQUIRED FIRST)
-
-**Before doing ANYTHING else, run this to register the command for context preservation:**
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'retro', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ Retro command activated');
-}
-"
+node scripts/obtain-context.js retro
 ```
 
+This gathers git status, stories/epics, session state, and registers for PreCompact.
+
 ---
 
 Automated retrospective generator that analyzes patterns and surfaces insights from AgileFlow data.

package/src/core/commands/sprint.md

@@ -68,6 +68,14 @@ Sprint Planner that creates data-driven sprint commitments based on historical v
 
 Intelligent sprint planning with capacity-based story selection, dependency validation, and velocity forecasting.
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js sprint
+```
+
+This gathers git status, stories/epics, session state, and registers for PreCompact.
+
 ## Prompt
 
 ROLE: Sprint Planner

package/src/core/commands/status.md

@@ -9,26 +9,17 @@ Update story status and broadcast to agents via message bus.
 
 ---
 
-## STEP 0: Activation
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'status', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ status command activated');
-}
-"
+node scripts/obtain-context.js status
 ```
 
+This gathers git status, stories/epics, session state, and registers for PreCompact.
+
 ---
 
-## STEP 0: Activation (Documentation)
+## Context Loading (Documentation)
 
 **PURPOSE**: Immediately load full context before executing any logic.
 

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

@@ -9,26 +9,15 @@ Validate a specific story for completeness, architecture context, and readiness
 
 ---
 
-## STEP 0: Activation
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'story-validate', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ story-validate command activated');
-}
-"
+node scripts/obtain-context.js story-validate
 ```
 
 ---
 
-## STEP 0: Activation (Documentation)
+## Context Loading (Documentation)
 
 **PURPOSE**: Immediately load full context before executing any logic.
 

package/src/core/commands/story.md

@@ -9,23 +9,10 @@ Create a new user story with acceptance criteria and test stubs.
 
 ---
 
-## 🚨 STEP 0: ACTIVATE COMMAND (REQUIRED FIRST)
-
-**Before doing ANYTHING else, run this to register the command for context preservation:**
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'story', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ Story command activated');
-}
-"
+node scripts/obtain-context.js story
 ```
 
 ---
@@ -40,7 +27,7 @@ if (fs.existsSync(path)) {
 **Critical Rules**:
 - MUST use TodoWrite to track all 6 steps (parse, create story, create test stub, update status.json, append to bus/log.jsonl, confirm)
 - MUST show preview before creating files (use AskUserQuestion with proper XML invoke format)
-- NEVER ask users to "type" - always use proper options format (see docs/02-practices/ask-user-question.md)
+- NEVER ask users to "type" - always use proper options format
 - MUST use story-template.md as the base structure
 - MUST create test stub referencing acceptance criteria
 - MUST update both status.json and bus/log.jsonl
@@ -102,7 +89,20 @@ if (fs.existsSync(path)) {
 
 ROLE: Story Creator
 
-🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Create this story?",
+  "header": "Confirm",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, create it", "description": "Create story file and test stub"},
+    {"label": "Edit first", "description": "Modify details before creating"}
+  ]
+}]</parameter>
+</invoke>
+```
 
 TODO LIST TRACKING
 **CRITICAL**: Immediately create a todo list using TodoWrite tool to track story creation:

package/src/core/commands/template.md

@@ -8,23 +8,10 @@ Create and manage custom templates for stories, epics, ADRs, and other documents
 
 ---
 
-## 🚨 STEP 0: ACTIVATE COMMAND (REQUIRED FIRST)
-
-**Before doing ANYTHING else, run this to register the command for context preservation:**
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'custom-template', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ Custom-template command activated');
-}
-"
+node scripts/obtain-context.js template
 ```
 
 ---

package/src/core/commands/tests.md

@@ -8,23 +8,10 @@ Automatically set up testing infrastructure for projects without existing tests.
 
 ---
 
-## 🚨 STEP 0: ACTIVATE COMMAND (REQUIRED FIRST)
-
-**Before doing ANYTHING else, run this to register the command for context preservation:**
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'setup-tests', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ Setup-tests command activated');
-}
-"
+node scripts/obtain-context.js tests
 ```
 
 ---

package/src/core/commands/update.md

@@ -8,23 +8,10 @@ Generate stakeholder communication updates from project status.
 
 ---
 
-## 🚨 STEP 0: ACTIVATE COMMAND (REQUIRED FIRST)
-
-**Before doing ANYTHING else, run this to register the command for context preservation:**
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'stakeholder-update', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ Stakeholder-update command activated');
-}
-"
+node scripts/obtain-context.js update
 ```
 
 ---

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

@@ -10,23 +10,10 @@ Validate agent expertise files to ensure they haven't drifted from the codebase.
 
 ---
 
-## 🚨 STEP 0: ACTIVATE COMMAND (REQUIRED FIRST)
-
-**Before doing ANYTHING else, run this to register the command for context preservation:**
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'validate-expertise', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ Validate-expertise command activated');
-}
-"
+node scripts/obtain-context.js validate-expertise
 ```
 
 ---

package/src/core/commands/velocity.md

@@ -9,25 +9,14 @@ Track team velocity, calculate trends, and forecast completion dates.
 
 ---
 
-## 🚨 STEP 0: ACTIVATE COMMAND (REQUIRED FIRST)
-
-**Before doing ANYTHING else, run this to register the command for context preservation:**
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'velocity', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ Velocity command activated');
-}
-"
+node scripts/obtain-context.js velocity
 ```
 
+This gathers git status, stories/epics, session state, and registers for PreCompact.
+
 ---
 
 <!-- COMPACT_SUMMARY_START -->

package/src/core/commands/verify.md

@@ -9,25 +9,14 @@ Execute project tests and update test status for stories.
 
 ---
 
-## 🚨 STEP 0: ACTIVATE COMMAND (REQUIRED FIRST)
-
-**Before doing ANYTHING else, run this to register the command for context preservation:**
+## STEP 0: Gather Context
 
 ```bash
-node -e "
-const fs = require('fs');
-const path = 'docs/09-agents/session-state.json';
-if (fs.existsSync(path)) {
-  const state = JSON.parse(fs.readFileSync(path, 'utf8'));
-  const cmd = { name: 'verify', activated_at: new Date().toISOString(), state: {} };
-  state.active_commands = state.active_commands || [];
-  if (!state.active_commands.some(c => c.name === cmd.name)) state.active_commands.push(cmd);
-  fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
-  console.log('✅ Verify command activated');
-}
-"
+node scripts/obtain-context.js verify
 ```
 
+This gathers git status, stories/epics, session state, and registers for PreCompact.
+
 ---
 
 <!-- COMPACT_SUMMARY_START -->