agileflow 2.42.0 → 2.44.0

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
 

package/src/core/commands/context.md

@@ -1,6 +1,6 @@
 ---
 description: Generate context export for web AI tools
-argument-hint: [MODE=full|export|note|research] [NOTE=<text>] [TOPIC=<text>] [DETAILS=<text>]
+argument-hint: [MODE=full|export|note|research|import] [NOTE=<text>] [TOPIC=<text>] [DETAILS=<text>] [CONTENT=<text>] [SOURCE=<url>]
 ---
 
 <!-- COMPACT_SUMMARY_START
@@ -12,11 +12,12 @@ This section is extracted by the PreCompact hook to preserve essential context a
 Web AI Context Manager - Generates/exports/manages project context briefs for web AI tools (ChatGPT, Perplexity, Gemini, Claude web).
 
 ### Critical Behavioral Rules
-- **ALWAYS create TodoWrite list** for MODE=full and MODE=research to track multi-step workflows
+- **ALWAYS create TodoWrite list** for MODE=full, MODE=research, and MODE=import to track multi-step workflows
 - **Diff-first approach**: Show changes and wait for YES/NO confirmation before ANY file writes
 - **Preserve user-written content**: Only update managed sections in docs/context.md
 - **No writes in export mode**: MODE=export outputs text only, never writes files
 - **Research is two-step**: STEP 1 generates prompt, STEP 2 stores results when user returns
+- **Import is one-step**: Process CONTENT immediately and create research file
 - **Link research files**: Always reference research from ADRs/Epics/Stories that use it
 
 ### Core Workflow
@@ -50,6 +51,16 @@ Web AI Context Manager - Generates/exports/manages project context briefs for we
 7. Ask if user wants ADR/Epic/Story created from research
 8. Add research reference to created ADR/Epic/Story
 
+**MODE=import**
+1. Create todo list tracking: validate inputs, process content, extract key points, extract code, generate actions, suggest stories, format research file, save, update index
+2. Validate TOPIC and CONTENT are provided
+3. Process raw content (transcript, article, etc.) by: summarizing key points, extracting code snippets, generating action items, suggesting user stories
+4. Format into structured research file with all extracted sections
+5. Save to docs/10-research/YYYYMMDD-topic-slug.md
+6. Update docs/10-research/README.md index
+7. Ask if user wants ADR/Epic/Story created from imported content
+8. Add research reference to created ADR/Epic/Story
+
 ### Key Files
 - docs/context.md - Main context brief (managed sections + user content)
 - docs/10-research/YYYYMMDD-topic-slug.md - Research results storage
@@ -68,9 +79,11 @@ Generate, export, or manage the web AI context brief.
 ROLE: Web AI Context Manager
 
 INPUTS (optional)
-- MODE=full|export|note|research (default: full)
+- MODE=full|export|note|research|import (default: full)
 - NOTE=<text> (required if MODE=note)
-- TOPIC=<text> (required if MODE=research)
+- TOPIC=<text> (required if MODE=research or MODE=import)
+- CONTENT=<text> (required if MODE=import - raw content to process)
+- SOURCE=<url> (optional for MODE=import - original source URL)
 
 ---
 
@@ -249,6 +262,124 @@ When user pastes research results back:
 
 ---
 
+## MODE=import
+Import raw content (transcripts, articles, notes) and convert to structured research file.
+
+### Input
+- TOPIC=<text> (required - name for the research file)
+- CONTENT=<text> (required - raw content to process: transcript, article, notes, etc.)
+- SOURCE=<url> (optional - original source URL for reference)
+
+### Use Cases
+- YouTube video transcripts
+- Conference talk notes
+- Podcast transcripts
+- Blog posts / articles
+- Documentation pages
+- Forum discussions / Stack Overflow threads
+- Meeting notes
+
+### TODO LIST TRACKING
+**CRITICAL**: Immediately create a todo list using TodoWrite tool to track import workflow:
+```
+1. Validate TOPIC and CONTENT are provided
+2. Analyze and summarize key points from content
+3. Extract any code snippets
+4. Generate action items based on content
+5. Create user story suggestions (if applicable)
+6. Format into structured research markdown
+7. Show diff for review
+8. Save to docs/10-research/YYYYMMDD-topic-slug.md
+9. Update docs/10-research/README.md index
+10. Ask about creating ADR/Epic/Story from research
+```
+
+Mark each step complete as you finish it.
+
+### Processing Steps
+
+1. **Validate Inputs**
+   - Verify TOPIC is provided (error if missing)
+   - Verify CONTENT is provided (error if missing)
+   - SOURCE is optional but recommended for attribution
+
+2. **Analyze Content**
+   Extract from the raw content:
+   - **Summary**: 2-3 paragraph TL;DR of the main points
+   - **Key Findings**: Bullet list of important takeaways
+   - **Code Snippets**: Any code blocks, commands, or configuration (preserve exactly)
+   - **Action Items**: Concrete next steps mentioned or implied
+   - **Story Suggestions**: Potential user stories/epics based on content
+
+3. **Format Research File**
+   ```markdown
+   # [Topic Title]
+
+   **Import Date**: YYYY-MM-DD
+   **Topic**: [original topic]
+   **Source**: [URL if provided, or "Direct import"]
+   **Content Type**: [transcript/article/notes/etc.]
+
+   ## Summary
+   [2-3 paragraph executive summary of the content]
+
+   ## Key Findings
+   - [Main point 1 with details]
+   - [Main point 2 with details]
+   - [Main point 3 with details]
+   - ...
+
+   ## Code Snippets
+   [Preserve all code snippets exactly as they appeared]
+   ```language
+   [code here]
+   ```
+
+   ## Action Items
+   - [ ] [Action 1 - concrete next step]
+   - [ ] [Action 2 - concrete next step]
+   - [ ] [Action 3 - concrete next step]
+
+   ## Story Suggestions
+   [If content suggests feature work, list potential stories]
+
+   ### Potential Epic: [Epic Title]
+   - **US-XXXX**: [Story 1 title]
+     - AC: [acceptance criteria bullet]
+   - **US-XXXX**: [Story 2 title]
+     - AC: [acceptance criteria bullet]
+
+   ## Raw Content Reference
+   <details>
+   <summary>Original content (click to expand)</summary>
+
+   [First 500 chars of original content for reference...]
+   </details>
+
+   ## References
+   - Source: [URL or "Direct import"]
+   - Import date: [YYYY-MM-DD]
+   ```
+
+4. **Save and Index**
+   - Save to `docs/10-research/YYYYMMDD-<topic-slug>.md`
+   - Update `docs/10-research/README.md` with new entry
+
+5. **Offer Next Steps**
+   Ask user via AskUserQuestion:
+   - Create an ADR referencing this research?
+   - Create an Epic/Stories based on the story suggestions?
+   - Link this research to an existing Epic/Story?
+
+### Rules
+- Diff-first; YES/NO before writing research file
+- Preserve ALL code snippets exactly as provided
+- Generate actionable items (not vague suggestions)
+- Keep raw content reference collapsed to save space
+- Always update the research index
+
+---
+
 ## Usage Examples
 
 ```bash
@@ -262,9 +393,13 @@ When user pastes research results back:
 # Add a quick note
 /agileflow:context MODE=note NOTE="User reported auth bug in production"
 
-# Build research prompt
+# Build research prompt for web AI
 /agileflow:context MODE=research TOPIC="Implement OAuth 2.0 with Google"
 /agileflow:context MODE=research TOPIC="Add Stripe payments" DETAILS="Launch by end of sprint"
+
+# Import external content (transcripts, articles, notes)
+/agileflow:context MODE=import TOPIC="React Server Components" CONTENT="[paste transcript here]"
+/agileflow:context MODE=import TOPIC="Stripe Webhooks Tutorial" SOURCE="https://youtube.com/..." CONTENT="[paste transcript here]"
 ```
 
 ---
@@ -276,3 +411,4 @@ Depending on MODE:
 - **export**: Text output ready to paste into web AI tool
 - **note**: Appended note to docs/context.md (after YES confirmation)
 - **research**: Research prompt in code block ready to paste into web AI tool
+- **import**: Processed research file saved to docs/10-research/ (after YES confirmation)

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.