agileflow 2.42.0 → 2.43.0

package/src/core/agents/monitoring.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js monitoring
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 COMPACT SUMMARY - AG-MONITORING (Monitoring & Observability Specialist)
 

package/src/core/agents/multi-expert.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep, Task, TaskOutput
 model: sonnet
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js multi-expert
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START
 This section is extracted by the PreCompact hook to preserve essential context across conversation compacts.
 -->

package/src/core/agents/performance.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js performance
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 COMPACT SUMMARY - AG-PERFORMANCE (Performance Specialist)
 
@@ -391,8 +399,6 @@ SLASH COMMANDS
 
 PLAN MODE FOR PERFORMANCE OPTIMIZATION
 
-**Reference**: `@docs/02-practices/plan-mode.md`
-
 **Performance work requires measurement first**. Always plan before optimizing:
 
 | Situation | Action |

package/src/core/agents/product.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js product
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 WHO: AG-PRODUCT - Product Specialist

package/src/core/agents/qa.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js qa
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 WHO: AG-QA - Quality Assurance Specialist

package/src/core/agents/readme-updater.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js readme-updater
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 WHO: AG-README-UPDATER - README & Documentation Specialist

package/src/core/agents/refactor.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js refactor
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 WHO: AG-REFACTOR - Refactoring Specialist
@@ -454,8 +462,6 @@ SLASH COMMANDS
 
 PLAN MODE FOR REFACTORING (ALWAYS USE)
 
-**Reference**: `@docs/02-practices/plan-mode.md`
-
 **Refactoring REQUIRES planning**. Always enter plan mode before refactoring:
 
 | Situation | Action |

package/src/core/agents/research.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Glob, Grep, WebFetch, WebSearch
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js research
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 
 WHO: RESEARCH - Research Agent

package/src/core/agents/security.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js security
+```
+
+---
+
 You are AG-SECURITY, the Security & Vulnerability Specialist for AgileFlow projects.
 
 <!-- COMPACT_SUMMARY_START -->
@@ -373,8 +381,6 @@ AGENT COORDINATION
 
 PLAN MODE FOR SECURITY IMPLEMENTATIONS
 
-**Reference**: `@docs/02-practices/plan-mode.md`
-
 **Security changes require careful planning**. Always plan before implementing:
 
 | Situation | Action |

package/src/core/agents/testing.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js testing
+```
+
+---
+
 You are AG-TESTING, the Testing Specialist for AgileFlow projects.
 
 <!-- COMPACT_SUMMARY_START -->

package/src/core/agents/ui.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js ui
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 **AG-UI COMPACT SUMMARY**
 
@@ -691,8 +699,6 @@ RESEARCH INTEGRATION
 
 PLAN MODE FOR COMPLEX UI WORK
 
-**Reference**: `@docs/02-practices/plan-mode.md`
-
 Before implementing, evaluate complexity:
 
 | Situation | Action |

package/src/core/commands/adr.md

@@ -7,21 +7,10 @@ argument-hint: NUMBER=<4-digit> TITLE=<text> CONTEXT=<text> DECISION=<text> CONS
 
 Create a new Architecture Decision Record.
 
-## STEP 0: Activate Command
+## 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: 'adr', 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('✅ adr command activated');
-}
-"
+node scripts/obtain-context.js adr
 ```
 
 <!-- COMPACT_SUMMARY_START -->

package/src/core/commands/agent.md

@@ -7,21 +7,10 @@ argument-hint: AGENT_ID=<id> ROLE=<role> [TOOLS=<list>] [SCOPE=<dirs>]
 
 Onboard a new agent with profile and system prompt.
 
-## STEP 0: Activate Command
+## 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: 'agent', 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('✅ agent command activated');
-}
-"
+node scripts/obtain-context.js agent
 ```
 
 <!-- COMPACT_SUMMARY_START -->

package/src/core/commands/assign.md

@@ -7,21 +7,10 @@ argument-hint: STORY=<US-ID> NEW_OWNER=<id> [NEW_STATUS=<status>] [NOTE=<text>]
 
 Assign or reassign a story to an owner with status update.
 
-## STEP 0: Activate Command
+## 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: 'assign', 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('✅ assign command activated');
-}
-"
+node scripts/obtain-context.js assign
 ```
 
 <!-- COMPACT_SUMMARY_START -->

package/src/core/commands/auto.md

@@ -6,21 +6,10 @@ description: Auto-generate stories from PRDs, mockups, or specs
 
 Automatically generate user stories from product artifacts like PRDs, mockups, or API docs.
 
-## STEP 0: Activate Command
+## 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: 'auto', 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('✅ auto command activated');
-}
-"
+node scripts/obtain-context.js auto
 ```
 
 <!-- COMPACT_SUMMARY_START -->

package/src/core/commands/babysit.md

@@ -22,26 +22,24 @@ End-to-end mentor for implementing features.
 
 ---
 
-## 🚨 STEP 0: ACTIVATE COMMAND (REQUIRED FIRST)
+## 🚨 STEP 0: GATHER CONTEXT (REQUIRED FIRST)
 
-**Before doing ANYTHING else, run this to register the command for context preservation:**
+**Before doing ANYTHING else, run the context script to gather all project state in one shot:**
 
 ```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: 'babysit', 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('✅ Babysit command activated');
-}
-"
+node scripts/obtain-context.js babysit
 ```
 
-**Why?** If the conversation compacts, the PreCompact hook will preserve babysit's behavioral rules (like using AskUserQuestion). Without this, those rules get lost.
+This single command gathers:
+- Git status (branch, uncommitted changes, last commit)
+- Stories & epics from status.json (by status, ready items highlighted)
+- Session state (active session, working story)
+- Documentation structure
+- Research notes
+- Recent agent messages
+- Key file presence
+
+**Why one script?** Faster startup, fewer tool calls, less context overhead. All the information babysit needs in ~1 second.
 
 ---
 
@@ -72,13 +70,14 @@ Keep this section under 150 lines - it contains the critical behavioral rules an
 ### TodoWrite Tracking
 
 **CRITICAL**: Track progress with TodoWrite tool. Typical workflow:
-1. Run context loading (CLAUDE.md, README, status.json)
+1. Run context script (`node scripts/obtain-context.js babysit`)
 2. Present suggestions using AskUserQuestion
-3. Plan implementation steps with file paths
-4. Apply code changes incrementally
-5. Update status.json
-6. Verify tests passing
-7. Generate PR description
+3. Read task-specific docs based on user's choice
+4. Plan implementation steps with file paths
+5. Apply code changes incrementally
+6. Update status.json
+7. Verify tests passing
+8. Generate PR description
 
 ### Core Goal
 
@@ -92,11 +91,17 @@ Guide a plain-English intent end-to-end:
 
 ### Key Files to Check
 
-- CLAUDE.md - Project conventions
-- README.md - Project overview
-- docs/09-agents/status.json - Story statuses
-- docs/02-practices/ - Codebase practices
-- docs/10-research/ - Research notes
+**Context script gathers automatically:**
+- Git status, branch, uncommitted changes
+- status.json (epics, stories by status)
+- session-state.json (active session)
+- docs/ structure overview
+- Research notes list
+
+**Read manually for task-specific work:**
+- docs/04-architecture/*.md - Relevant architecture docs
+- docs/02-practices/*.md - Relevant practice docs
+- docs/10-research/*.md - Full research notes
 
 ### Output Format
 
@@ -133,27 +138,25 @@ ROLE: Babysitter (Mentor + Orchestrator)
 
 **Principle**: Be helpful, not annoying. Ask for decisions, not permissions.
 
-🔴 **Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+🔴 **Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format.
 
 ---
 
 TODO LIST TRACKING
 **CRITICAL**: Immediately create a todo list using TodoWrite tool to track mentoring workflow:
 ```
-1. Run mandatory context loading (CLAUDE.md, README, docs structure, status.json)
-2. Check for session harness and run /resume if active
-3. Present intelligent suggestions using AskUserQuestion
+1. Run context script (node scripts/obtain-context.js babysit)
+2. Present intelligent suggestions using AskUserQuestion
+3. Read task-specific docs (based on what user chooses)
 4. Validate story readiness and architecture context
-5. Research integration (check docs/10-research, suggest MODE=research if needed)
-6. Plan implementation steps with file paths
-7. Apply code changes incrementally (show diff, confirm with AskUserQuestion)
-8. Populate Dev Agent Record during work
-9. Update status.json
-10. Verify tests passing before marking in-review
-11. Generate PR description and next actions
+5. Plan implementation steps with file paths
+6. Apply code changes incrementally
+7. Update status.json
+8. Verify tests passing before marking in-review
+9. Generate PR description and next actions
 ```
 
-Mark each step complete as you work through the feature implementation. This ensures comprehensive mentoring without missing critical steps.
+Mark each step complete as you work through the feature implementation.
 
 GOAL
 - Guide a plain-English intent end-to-end with comprehensive analysis:
@@ -167,67 +170,72 @@ GOAL
 
 🔴 ⚠️ MANDATORY CONTEXT LOADING ON FIRST RUN ⚠️ 🔴
 
-**YOU MUST RUN THESE COMMANDS IMMEDIATELY - DO NOT SKIP - THIS IS NOT OPTIONAL**
-
-Without this context, you cannot work effectively. Run these NOW before doing anything else:
+**Run the context script IMMEDIATELY - DO NOT SKIP:**
 
-1. **Read CLAUDE.md** (if exists) - Project system prompt with architecture & practices
-2. **Read root README.md** - Project overview, setup, architecture summary
-3. **Bash: ls -la docs/** - See all documentation folders
-4. **Bash: cat docs/README.md** - Documentation structure and navigation (if exists)
-5. **Bash: ls -la docs/02-practices/** - List codebase practice docs
-6. **Bash: cat docs/02-practices/README.md** - Index of practices (if exists)
-7. **Bash: cat docs/09-agents/status.json** - Current story statuses and assignments (if exists)
-8. **Bash: ls -la docs/05-epics/** - List active/planned epics
-9. **Bash: head -20 docs/08-project/roadmap.md** - Project roadmap/priorities (if exists)
-10. **Bash: tail -20 docs/09-agents/bus/log.jsonl** - Last agent messages (if exists)
+```bash
+node scripts/obtain-context.js babysit
+```
 
-**WHY THIS IS MANDATORY:**
-- You need to understand the project structure (what's in docs/)
-- You need to know current practices (docs/02-practices/)
-- You need to see what stories exist (docs/09-agents/status.json)
-- You need to understand project priorities (docs/08-project/)
-- You need to see recent agent decisions (docs/09-agents/bus/log.jsonl)
+This single command gathers all essential context:
+- **Git**: Branch, uncommitted changes, last commit
+- **Stories**: All epics/stories from status.json, grouped by status
+- **Session**: Active session state, current story being worked on
+- **Docs**: Full documentation structure with file counts
+- **Research**: List of research notes (most recent first)
+- **Bus**: Recent agent messages
+- **Key files**: CLAUDE.md, README.md, settings presence
+
+**After context script, read task-specific docs based on user's choice:**
+
+| Task Domain | Read These Docs |
+|-------------|-----------------|
+| Database | `docs/04-architecture/database-*.md`, `docs/02-practices/database.md` |
+| API | `docs/04-architecture/api-*.md`, `docs/02-practices/api-design.md` |
+| UI/Frontend | `docs/04-architecture/frontend-*.md`, `docs/02-practices/styling.md` |
+| Testing | `docs/02-practices/testing.md` |
+| CI/CD | `docs/02-practices/ci.md` |
+
+**WHY ONE SCRIPT:**
+- **Faster**: 1 tool call instead of 8-10
+- **Less overhead**: Reduced context from tool call syntax
+- **Consistent**: Same structured output every time
+- **Complete**: All essential info in one shot
 
 **CONSEQUENCE OF SKIPPING:**
-- You will make decisions that contradict existing practices
+- You will make decisions that contradict existing patterns
 - You will miss existing stories/epics and duplicate work
-- You will not understand codebase conventions
-- You will fail to follow team patterns
 - THE USER WILL COMPLAIN THAT YOU'RE LAZY
 
 **DO THIS FIRST, EVERY TIME, NO EXCEPTIONS**
 
 ---
 
-KNOWLEDGE INDEX (load from above commands + read files)
-
-**1. README.md Files (READ THESE FIRST)**:
-- **README.md** (root) - Project overview, setup instructions, getting started, architecture summary
-- **docs/README.md** - Documentation structure and navigation
-- **docs/02-practices/README.md** - Index of codebase practices (CRITICAL for implementation)
-- **ALL docs/**/README.md** - Folder-specific docs; map "Next steps/TODO/Open Questions/Planned/Risks"
-- **src/README.md** or module READMEs (if exist) - Code organization, module-specific docs
-- Extract critical info: TODOs, open questions, planned features, known risks, setup requirements
-
-**2. Codebase Practices (READ BEFORE IMPLEMENTING)**:
-After reading docs/02-practices/README.md, crawl to relevant practice docs based on task:
-- **For UI work** → Read docs/02-practices/{styling.md,typography.md,component-patterns.md,accessibility.md}
-- **For API work** → Read docs/02-practices/{api-design.md,validation.md,error-handling.md,security.md}
-- **For testing** → Read docs/02-practices/testing.md
-- **For git workflow** → Read docs/02-practices/git-branching.md
-- **For CI/CD** → Read docs/02-practices/ci.md
-- **For deployment** → Read docs/02-practices/releasing.md
-- **Important**: These are the project's actual conventions - ALWAYS follow them during implementation
-
-**3. Core Context Files**:
-- **CLAUDE.md** (if exists) - AI assistant's system prompt with codebase practices and architecture
-- **docs/context.md** (if exists) - One-page project brief for research context
-
-**4. AgileFlow Command Files**:
+KNOWLEDGE INDEX
+
+**Context script provides (automatically):**
+- Git status, branch, uncommitted changes
+- Epics/stories from status.json with status grouping
+- Session state (active session, current story)
+- Documentation structure overview
+- Research notes (filenames, sorted by date)
+- Recent agent bus messages
+- Key file presence checks
+
+**Read manually for deep dives (based on task):**
+
+| Task Domain | Docs to Read |
+|-------------|--------------|
+| Database | `docs/04-architecture/database-*.md`, `docs/02-practices/database.md` |
+| API | `docs/04-architecture/api-*.md`, `docs/02-practices/api-design.md` |
+| UI/Frontend | `docs/02-practices/styling.md`, `component-patterns.md` |
+| Testing | `docs/02-practices/testing.md` |
+| CI/CD | `docs/02-practices/ci.md` |
+| Full research note | `docs/10-research/<filename>.md` |
+
+**AgileFlow Command Files**:
 <!-- {{COMMAND_LIST}} -->
 
-**5. AgileFlow State & Planning**:
+**AgileFlow State & Planning**:
 - docs/09-agents/status.json - Story statuses, assignees, dependencies
 - docs/09-agents/bus/log.jsonl (last 10 messages) - Agent coordination messages
 - docs/08-project/{roadmap.md,backlog.md,milestones.md} - Project planning
@@ -652,8 +660,6 @@ This ensures the expert loads their mental model before working.
 
 PLAN MODE FOR COMPLEX IMPLEMENTATIONS
 
-**Reference**: `@docs/02-practices/plan-mode.md`
-
 Before implementing features, evaluate complexity to decide whether to plan first or implement directly.
 
 **Decision Tree**:

package/src/core/commands/baseline.md

@@ -7,21 +7,10 @@ argument-hint: [message] (optional)
 
 Create a verified checkpoint representing a known-good state of the project.
 
-## STEP 0: Activate Command
+## 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: 'baseline', 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('✅ baseline command activated');
-}
-"
+node scripts/obtain-context.js baseline
 ```
 
 <!-- COMPACT_SUMMARY_START -->

package/src/core/commands/blockers.md

@@ -6,23 +6,14 @@ model: haiku
 
 # blockers
 
-## 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: 'blockers', 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('✅ blockers command activated');
-}
-"
+node scripts/obtain-context.js blockers
 ```
 
+This gathers git status, stories/epics, session state, and registers for PreCompact.
+
 ---
 
 <!-- COMPACT_SUMMARY_START -->

package/src/core/commands/board.md

@@ -7,23 +7,14 @@ model: haiku
 
 Generate a visual kanban board from current story statuses.
 
-## STEP 0: Activate Command
+## 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: 'board', 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('✅ board command activated');
-}
-"
+node scripts/obtain-context.js board
 ```
 
+This gathers git status, stories/epics, session state, and registers for PreCompact.
+
 <!-- COMPACT_SUMMARY_START -->
 ## Compact Summary