agileflow 2.92.1 → 2.94.0

package/src/core/commands/session/new.md

@@ -30,6 +30,16 @@ When you need to work on multiple things simultaneously in the same repo, this c
 - Its own branch
 - Independent session tracking
 
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js session:new
+```
+
+---
+
 ## IMMEDIATE ACTIONS
 
 Upon invocation, execute these steps:
@@ -87,23 +97,75 @@ AskUserQuestion:
       description: "Bug fixing"
 ```
 
-Then run:
+### Step 2B.2: Ask Startup Mode (OPTIONAL but recommended)
+
+After getting the session name, check for configured default startup mode:
 
 ```bash
-# If auto-generate selected:
-node .agileflow/scripts/spawn-parallel.js add-window
+# Read the default startup mode from metadata (if exists)
+cat docs/00-meta/agileflow-metadata.json | grep -A1 '"defaultStartupMode"' 2>/dev/null
+```
+
+The `defaultStartupMode` can be: `normal`, `skip-permissions`, `accept-edits`, or `no-claude`.
 
-# If named option selected:
-node .agileflow/scripts/spawn-parallel.js add-window --name {selected_name}
+Then ask how Claude should start, putting the configured default first with "(Recommended)":
 
-# If "Other" with custom input:
-node .agileflow/scripts/spawn-parallel.js add-window --name {custom_name}
+```
+AskUserQuestion:
+  question: "How should Claude start in this session?"
+  header: "Startup mode"
+  multiSelect: false
+  options:
+    # Put the defaultStartupMode option FIRST with "(Recommended)" suffix
+    # Example if defaultStartupMode is "normal":
+    - label: "Normal (Recommended)"
+      description: "Standard Claude with permission prompts"
+    - label: "Skip permissions"
+      description: "claude --dangerously-skip-permissions (trusted mode)"
+    - label: "Accept edits only"
+      description: "claude --permission-mode acceptEdits"
+    - label: "Don't start Claude"
+      description: "Create worktree only, start Claude manually"
+
+    # Example if defaultStartupMode is "skip-permissions":
+    # - label: "Skip permissions (Recommended)"
+    #   description: "claude --dangerously-skip-permissions (trusted mode)"
+    # - label: "Normal"
+    #   description: "Standard Claude with permission prompts"
+    # - label: "Accept edits only"
+    #   description: "claude --permission-mode acceptEdits"
+    # - label: "Don't start Claude"
+    #   description: "Create worktree only, start Claude manually"
+```
+
+**Mode to Flag Mapping:**
+| defaultStartupMode | spawn-parallel.js flag |
+|--------------------|------------------------|
+| `normal` | (no extra flags) |
+| `skip-permissions` | `--dangerous` |
+| `accept-edits` | `--claude-args "--permission-mode acceptEdits"` |
+| `no-claude` | `--no-claude` |
+
+Then run based on selections:
+
+```bash
+# Normal mode (default):
+node .agileflow/scripts/spawn-parallel.js add-window --name {session_name}
+
+# Skip permissions mode:
+node .agileflow/scripts/spawn-parallel.js add-window --name {session_name} --dangerous
+
+# Accept edits only mode:
+node .agileflow/scripts/spawn-parallel.js add-window --name {session_name} --claude-args "--permission-mode acceptEdits"
+
+# Don't start Claude:
+node .agileflow/scripts/spawn-parallel.js add-window --name {session_name} --no-claude
 ```
 
 The script will:
 1. Create a new git worktree
 2. Add a new tmux window to the current session
-3. Start Claude in that window
+3. Start Claude with selected options (or just cd if --no-claude)
 4. Output the Alt+N shortcut to switch to it
 
 Display success and exit - skip remaining steps.
@@ -284,7 +346,7 @@ echo $TMUX
 
 ### 🚨 RULE #1B: TMUX FLOW (when in tmux)
 
-Ask for session name:
+**Step 1: Ask for session name:**
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
@@ -301,13 +363,44 @@ Ask for session name:
 </invoke>
 ```
 
-Then run:
+**Step 2: Read default startup mode and ask:**
 ```bash
-# Auto-generate:
-node .agileflow/scripts/spawn-parallel.js add-window
+# Check configured default (normal if not set)
+cat docs/00-meta/agileflow-metadata.json | grep '"defaultStartupMode"' 2>/dev/null
+```
 
-# Named:
+Then ask with configured default first + "(Recommended)":
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "How should Claude start?",
+  "header": "Startup",
+  "multiSelect": false,
+  "options": [
+    {"label": "{default} (Recommended)", "description": "Configured default"},
+    {"label": "Normal", "description": "Standard with prompts"},
+    {"label": "Skip permissions", "description": "--dangerously-skip-permissions"},
+    {"label": "Accept edits only", "description": "--permission-mode acceptEdits"},
+    {"label": "Don't start Claude", "description": "Manual start later"}
+  ]
+}]</parameter>
+</invoke>
+```
+Note: Put the defaultStartupMode FIRST with "(Recommended)", remove duplicate.
+
+**Step 3: Run with selected options:**
+```bash
+# Normal:
 node .agileflow/scripts/spawn-parallel.js add-window --name {name}
+
+# Skip permissions:
+node .agileflow/scripts/spawn-parallel.js add-window --name {name} --dangerous
+
+# Accept edits:
+node .agileflow/scripts/spawn-parallel.js add-window --name {name} --claude-args "--permission-mode acceptEdits"
+
+# No Claude:
+node .agileflow/scripts/spawn-parallel.js add-window --name {name} --no-claude
 ```
 
 The script outputs the Alt+N shortcut. **DONE - skip remaining rules.**
@@ -609,5 +702,12 @@ To switch to this session, run:
 - **Run `session-manager.js switch {new_id}` AFTER creating session** (enables boundary protection)
 - Show `/add-dir {path}` command for user to switch (NOT cd && claude)
 - Show tip to use /agileflow:session:resume
+- **STARTUP OPTIONS (tmux flow)**: After name, ask startup mode:
+  - Read `defaultStartupMode` from `docs/00-meta/agileflow-metadata.json`
+  - Put configured default FIRST with "(Recommended)" suffix
+  - Normal → (no extra flags)
+  - Skip permissions → `--dangerous`
+  - Accept edits → `--claude-args "--permission-mode acceptEdits"`
+  - Don't start → `--no-claude`
 
 <!-- COMPACT_SUMMARY_END -->

package/src/core/commands/session/resume.md

@@ -29,6 +29,16 @@ When you have multiple sessions and want to switch between them, this command:
 - Shows which are currently active (have a running Claude process)
 - Provides the `cd` command to switch to your chosen session
 
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js session:resume
+```
+
+---
+
 ## IMMEDIATE ACTIONS
 
 Upon invocation, execute these steps:

package/src/core/commands/session/spawn.md

@@ -35,6 +35,14 @@ Based on the [git worktrees parallel sessions research](../../../10-research/202
 
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js session:spawn
+```
+
+---
+
 ## IMMEDIATE ACTIONS
 
 Upon invocation, execute these steps:

package/src/core/commands/session/status.md

@@ -27,6 +27,16 @@ Quick view of all sessions and their status.
 
 Display a compact overview of all registered sessions without prompting for action.
 
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js session:status
+```
+
+---
+
 ## Arguments
 
 | Argument | Required | Description |

package/src/core/commands/skill/create.md

@@ -1,6 +1,6 @@
 ---
 description: Generate a custom skill with web research, cookbook pattern, and MCP integration
-argument-hint: [SKILL_NAME] (optional)
+argument-hint: [<name>]
 compact_context:
   priority: high
   preserve_rules:

package/src/core/commands/skill/delete.md

@@ -1,6 +1,6 @@
 ---
 description: Remove an installed skill from .claude/skills/
-argument-hint: [SKILL_NAME] (optional)
+argument-hint: [<name>]
 compact_context:
   priority: medium
   preserve_rules:
@@ -304,3 +304,13 @@ Try manually: rm -rf .claude/skills/<skill>/
 # Delete specific skill
 /agileflow:skill:delete supabase-swift
 ```
+
+---
+
+## Related Commands
+
+- `/agileflow:skill:create` - Create a new skill
+- `/agileflow:skill:list` - List all installed skills
+- `/agileflow:skill:edit` - Edit existing skill
+- `/agileflow:skill:upgrade` - Add learning capability
+- `/agileflow:skill:test` - Test skill functionality

package/src/core/commands/skill/edit.md

@@ -1,6 +1,6 @@
 ---
 description: Edit an existing skill's SKILL.md, cookbook entries, or references
-argument-hint: [SKILL_NAME] (optional)
+argument-hint: [<name>]
 compact_context:
   priority: medium
   preserve_rules:
@@ -347,3 +347,13 @@ Create a skill first: /agileflow:skill:create
 # Edit specific skill
 /agileflow:skill:edit supabase-swift
 ```
+
+---
+
+## Related Commands
+
+- `/agileflow:skill:create` - Create a new skill
+- `/agileflow:skill:list` - List all installed skills
+- `/agileflow:skill:test` - Test skill functionality
+- `/agileflow:skill:upgrade` - Add learning capability
+- `/agileflow:skill:delete` - Remove an installed skill

package/src/core/commands/skill/test.md

@@ -1,6 +1,6 @@
 ---
 description: Verify a skill works correctly by testing its activation and functionality
-argument-hint: [SKILL_NAME] (optional)
+argument-hint: [<name>]
 compact_context:
   priority: medium
   preserve_rules:
@@ -382,3 +382,13 @@ Fix with: /agileflow:skill:edit <name>
 # Test specific skill
 /agileflow:skill:test supabase-swift
 ```
+
+---
+
+## Related Commands
+
+- `/agileflow:skill:create` - Create a new skill
+- `/agileflow:skill:list` - List all installed skills
+- `/agileflow:skill:edit` - Edit existing skill
+- `/agileflow:skill:upgrade` - Add learning capability
+- `/agileflow:skill:delete` - Remove an installed skill

package/src/core/commands/skill/upgrade.md

@@ -1,6 +1,6 @@
 ---
 description: Upgrade existing skills with self-improving learning capability
-argument-hint: [SKILL_NAME] (optional)
+argument-hint: [<name>]
 compact_context:
   priority: medium
   preserve_rules:
@@ -540,3 +540,13 @@ Before completing, verify:
 # Batch upgrade (upgrade all at once)
 /agileflow:skill:upgrade --all
 ```
+
+---
+
+## Related Commands
+
+- `/agileflow:skill:create` - Create a new skill
+- `/agileflow:skill:list` - List all installed skills
+- `/agileflow:skill:edit` - Edit existing skill
+- `/agileflow:skill:test` - Test skill functionality
+- `/agileflow:skill:delete` - Remove an installed skill

package/src/core/commands/sprint.md

@@ -1,16 +1,16 @@
 ---
 description: Data-driven sprint planning with velocity forecasting
-argument-hint: "[SPRINT=<id>] [DURATION=<days>] [AGENTS=<list>] [MODE=suggest|commit] [FOCUS_EPIC=<id>]"
+argument-hint: [SPRINT=<id>] [DURATION=<number>] [AGENTS=<list>] [MODE=suggest|commit] [FOCUS_EPIC=<EP-ID>]
 model: haiku
 compact_context:
   priority: critical
   preserve_rules:
     - "ACTIVE COMMAND: /agileflow:sprint-plan - Sprint planner with capacity analysis"
-    - "MUST create TodoWrite task list immediately (8 steps: load knowledge, analyze capacity, calculate velocity, select stories, assess risks, generate report, commit if MODE=commit)"
+    - "{{RULES:todo_tracking}}"
     - "MUST calculate historical velocity from last 30 days (bus/log.jsonl)"
     - "MUST respect WIP limits (max 2 in-progress per agent)"
     - "MUST validate dependencies resolved (only select stories with all deps status=done)"
-    - "MUST show diff preview before committing (MODE=commit)"
+    - "{{RULES:file_preview}}"
     - "MUST assess risks (dependency chains, cross-agent coordination, epic staleness)"
     - "MODE=suggest shows preview; MODE=commit updates status.json + milestones.md"
   state_fields:
@@ -627,3 +627,14 @@ After displaying plan, ask:
 - "Does this sprint commitment look reasonable?"
 - "Should I commit this plan (update status.json and milestones.md)?"
 - "Any stories you'd like to add/remove?"
+
+---
+
+## Related Commands
+
+- `/agileflow:board` - Visual kanban board
+- `/agileflow:velocity` - Track velocity and forecast capacity
+- `/agileflow:metrics` - Analytics dashboard with cycle time
+- `/agileflow:assign` - Assign stories to owners
+- `/agileflow:blockers` - Track and resolve blockers
+- `/agileflow:retro` - Sprint retrospective

package/src/core/commands/status.md

@@ -5,12 +5,11 @@ compact_context:
   priority: high
   preserve_rules:
     - "ACTIVE COMMAND: /agileflow:status - Status updater broadcasting to message bus"
-    - "MUST update docs/09-agents/status.json (use jq or Edit tool, never echo/cat >)"
-    - "MUST validate JSON after modification (jq empty check)"
-    - "MUST append bus message to docs/09-agents/bus/log.jsonl"
-    - "MUST use AskUserQuestion for user confirmation (YES/NO format)"
-    - "MUST show diff preview before confirming (diff-first pattern)"
-    - "Status values: ready|in-progress|blocked|in-review|done"
+    - "{{RULES:json_operations}}"
+    - "{{RULES:bus_messaging}}"
+    - "{{RULES:user_confirmation}}"
+    - "{{RULES:file_preview}}"
+    - "{{RULES:status_updates}}"
     - "MUST escape user text automatically (jq handles escaping)"
     - "PHASE HANDOFF: Prompt for summary on phase transitions (ready→in-progress, in-progress→in-review, in-review→done)"
   state_fields:
@@ -411,3 +410,13 @@ Valid values are:
 Fix: Restoring from backup: docs/09-agents/status.json.backup
 ✅ Backup restored successfully
 ```
+
+---
+
+## Related Commands
+
+- `/agileflow:board` - Visual kanban board
+- `/agileflow:assign` - Assign stories to owners
+- `/agileflow:blockers` - Track and resolve blockers
+- `/agileflow:story:view` - View story details
+- `/agileflow:handoff` - Document work handoff

package/src/core/commands/story/list.md

@@ -1,6 +1,21 @@
 ---
 description: List all stories with status and filters
 argument-hint: [EPIC=<EP-ID>] [STATUS=<status>] [OWNER=<id>]
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:story:list - Lists stories with filters and quick actions"
+    - "MUST read status.json for story data"
+    - "MUST support filters: EPIC, STATUS, OWNER (combinable)"
+    - "MUST group stories by epic in output table"
+    - "MUST show: story ID, title, status, phase, owner, estimate"
+    - "MUST offer actions: view details, start work, create new"
+    - "This is READ-ONLY - no file writes"
+  state_fields:
+    - epic_filter
+    - status_filter
+    - owner_filter
+    - story_count
 ---
 
 # /agileflow:story:list
@@ -21,6 +36,14 @@ Shows all stories from `docs/09-agents/status.json` with:
 
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js story:list
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 ## Compact Summary
 

package/src/core/commands/story/view.md

@@ -1,6 +1,22 @@
 ---
 description: View story details with contextual actions
 argument-hint: STORY=<US-ID>
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:story:view - Views story with context-aware actions"
+    - "MUST read story file and status.json entry"
+    - "MUST display full story: AC (with checkboxes), tests, dependencies, blockers"
+    - "MUST offer CONTEXT-AWARE actions based on story status"
+    - "STATUS=ready → Start work, validate, view research"
+    - "STATUS=in_progress → Mark complete, mark blocked, view tests"
+    - "STATUS=blocked → View blocker, unblock, reassign"
+    - "STATUS=done → View summary, reopen, view next story"
+    - "ALWAYS offer next steps via AskUserQuestion"
+  state_fields:
+    - selected_story_id
+    - story_status
+    - story_epic
 ---
 
 # /agileflow:story:view
@@ -19,6 +35,14 @@ Displays complete story information and offers **context-aware actions** based o
 
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js story:view
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 ## Compact Summary
 

package/src/core/commands/story.md

@@ -5,11 +5,10 @@ compact_context:
   priority: high
   preserve_rules:
     - "ACTIVE COMMAND: /agileflow:story-new - Story creator with acceptance criteria"
-    - "MUST create TodoWrite task list immediately (6 steps: parse, create story, create test stub, merge status, append bus, confirm)"
-    - "MUST show file previews before confirming writes"
-    - "MUST use Edit tool or jq for JSON operations (never echo/cat > status.json)"
-    - "MUST validate JSON after every modification"
-    - "MUST use AskUserQuestion for user confirmation (YES/NO/CANCEL format)"
+    - "{{RULES:todo_tracking}}"
+    - "{{RULES:file_preview}}"
+    - "{{RULES:json_operations}}"
+    - "{{RULES:user_confirmation}}"
     - "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"

package/src/core/commands/template.md

@@ -563,3 +563,13 @@ OUTPUT
 - Updated template file (if ACTION=edit)
 - Generated document from template (if ACTION=use)
 - Updated registry.json
+
+---
+
+## Related Commands
+
+- `/agileflow:configure` - Manage AgileFlow features and hooks
+- `/agileflow:story` - Create user stories
+- `/agileflow:epic` - Create epics
+- `/agileflow:adr` - Create Architecture Decision Records
+- `/agileflow:docs` - Synchronize documentation

package/src/core/commands/tests.md

@@ -635,3 +635,13 @@ OUTPUT
 - Example tests (unit + integration + E2E if requested)
 - CI integration
 - Testing documentation
+
+---
+
+## Related Commands
+
+- `/agileflow:configure` - Manage AgileFlow features and hooks
+- `/agileflow:ci` - Bootstrap CI/CD workflow
+- `/agileflow:verify` - Run tests and update story status
+- `/agileflow:baseline` - Mark verified baseline
+- `/agileflow:pr` - Generate pull request from story

package/src/core/commands/update.md

@@ -520,3 +520,13 @@ OUTPUT
 - Saved to docs/08-project/updates/
 - Optional: Email sent to stakeholders
 - Log entry in bus/log.jsonl
+
+---
+
+## Related Commands
+
+- `/agileflow:docs` - Synchronize documentation with code
+- `/agileflow:metrics` - Analytics dashboard with cycle time
+- `/agileflow:board` - Visual kanban board
+- `/agileflow:retro` - Generate sprint retrospective
+- `/agileflow:changelog` - Generate changelog from commits

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

@@ -1,6 +1,6 @@
 ---
 description: Validate expertise files for drift and staleness
-argument-hint: "[DOMAIN]"
+argument-hint: [<domain>]
 model: haiku
 compact_context:
   priority: medium
@@ -218,3 +218,12 @@ RULES
 - Report issues but don't auto-fix
 - Prioritize drift detection (most critical)
 - Keep output concise and actionable
+
+---
+
+## Related Commands
+
+- `/agileflow:diagnose` - System health diagnostics
+- `/agileflow:configure` - Manage AgileFlow features
+- `/agileflow:agent` - Onboard new agents
+- `/agileflow:help` - Display AgileFlow overview

package/src/core/commands/velocity.md

@@ -1,6 +1,6 @@
 ---
 description: Track velocity and forecast sprint capacity
-argument-hint: "[PERIOD=week|sprint|month|all] [FORECAST=<epic-id>] [FORMAT=report|chart|json]"
+argument-hint: [PERIOD=week|sprint|month|all] [FORECAST=<EP-ID>] [FORMAT=report|chart|json]
 model: haiku
 compact_context:
   priority: medium
@@ -544,3 +544,13 @@ OUTPUT
 - Forecasts for epics/milestones
 - Risk analysis
 - Action items
+
+---
+
+## Related Commands
+
+- `/agileflow:sprint` - Sprint planning
+- `/agileflow:metrics` - Analytics dashboard
+- `/agileflow:retro` - Sprint retrospective
+- `/agileflow:board` - Kanban board view
+- `/agileflow:epic:list` - View epics with progress

package/src/core/commands/verify.md

@@ -1,6 +1,6 @@
 ---
 description: Run project tests and update story test status
-argument-hint: [story_id] (optional)
+argument-hint: [<US-ID>]
 compact_context:
   priority: critical
   preserve_rules:
@@ -399,6 +399,18 @@ Run without story_id to verify all in_progress stories.
 6. **Incremental Parsing**: Start with exit code only, add framework-specific parsing later
 7. **User Feedback**: Show clear, actionable output with visual indicators (✅/❌)
 
+---
+
+## Related Commands
+
+- `/agileflow:status` - Update story status
+- `/agileflow:audit` - Audit story completion
+- `/agileflow:ci` - Set up CI/CD workflow
+- `/agileflow:tests` - Set up testing infrastructure
+- `/agileflow:baseline` - Mark verified baseline
+
+---
+
 ## Example Execution
 
 ```

package/src/core/commands/whats-new.md

@@ -122,3 +122,11 @@ If a newer version exists, show:
 - Include dates if available
 - Always show the GitHub link for full history
 - Mention update availability if applicable
+
+---
+
+## Related Commands
+
+- `/agileflow:changelog` - Generate changelog from commits
+- `/agileflow:configure` - Manage AgileFlow features
+- `/agileflow:help` - Display AgileFlow overview

package/src/core/commands/workflow.md

@@ -1,6 +1,6 @@
 ---
 description: Define and run parameterized workflow templates
-argument-hint: <template> [arguments...]
+argument-hint: <template> [<arguments>]
 compact_context:
   priority: normal
   preserve_rules:
@@ -8,6 +8,11 @@ compact_context:
     - "Template format: {{arg_name}} for substitution"
     - "Built-in workflows: review, test-feature, implement, analyze"
     - "Custom workflows in docs/08-project/workflows/"
+  state_fields:
+    - workflow_name
+    - workflow_arguments
+    - execution_status
+    - template_path
 ---
 
 # /agileflow:workflow
@@ -342,3 +347,13 @@ Custom workflows (docs/08-project/workflows/):
 - Works with babysit for story implementation
 - Can trigger from Ralph Loop
 - Integrates with expert system for multi-domain work
+
+---
+
+## Related Commands
+
+- `/agileflow:babysit` - Interactive mentor workflow
+- `/agileflow:batch` - Process multiple items
+- `/agileflow:story` - Create user stories
+- `/agileflow:template` - Manage custom templates
+- `/agileflow:choose` - AI-directed decision making