agileflow 3.0.1 → 3.1.0

package/src/core/commands/team/start.md

@@ -56,13 +56,42 @@ If no argument given, use AskUserQuestion to let user choose.
 
 ### Native Mode (Agent Teams enabled)
 
-When Agent Teams is enabled, operate as the **team lead** in delegate mode:
-
-1. Read the template JSON from `.agileflow/teams/<template>.json`
-2. Announce the team composition to the user
-3. Create tasks for each teammate using the native task list
-4. Spawn teammate sessions as defined in the template
-5. Monitor progress and coordinate handoffs
+When Agent Teams is enabled, use native tools to create and coordinate the team:
+
+1. **Run the team-manager script** to load the template and build the native payload:
+   ```bash
+   node .agileflow/scripts/team-manager.js start <template-name>
+   ```
+   Parse the JSON output. The `native_payload` field contains the team configuration.
+
+2. **Announce the team composition** to the user — list each teammate's name, role, and domain.
+
+3. **Spawn teammates using the Task tool with native parameters**:
+   For each teammate in `native_payload.teammates`:
+   ```
+   Task tool call:
+     subagent_type: <teammate.name>     (e.g. "agileflow-api")
+     description: "<role> - <domain>"
+     prompt: <built from teammate instructions + project context>
+   ```
+   The prompt for each teammate should include:
+   - Their role and domain from the template
+   - The specific task or story they should work on
+   - A pointer to read CLAUDE.md and check `docs/09-agents/status.json` for context
+   - Quality gate requirements from the template
+
+4. **If native tools fail** (e.g., TeamCreate not available, tool not found errors):
+   - Log a warning: "Native Agent Teams tools not available. Falling back to subagent mode."
+   - Proceed with the **Fallback Mode** instructions below instead
+   - Update `session-state.json` to reflect `mode: "subagent"`
+
+5. **Create shared tasks** using TaskCreate for the work to be done:
+   - One task per teammate with clear acceptance criteria
+   - Set up dependencies (e.g., UI tasks blocked by API tasks)
+
+6. **Report** which mode was actually used (native vs fallback) and the spawned teammates.
+
+> **Tip**: For teams with 3+ teammates, consider using tmux sessions (`/agileflow:session:spawn`) to run teammates in parallel windows for better visibility.
 
 ### Fallback Mode (Agent Teams disabled)
 

package/src/core/commands/team/stop.md

@@ -43,8 +43,11 @@ Before stopping:
 
 ### Native Mode
 
-Teammates will be stopped when the team lead session ends.
-The native Agent Teams runtime handles cleanup.
+When `active_team.mode === "native"` in session-state.json:
+
+1. **Stop running teammate tasks**: Use `TaskStop` for any background teammate tasks still running
+2. **Attempt TeamDelete**: If the `TeamDelete` tool is available in your tool list, call it with the team name from `active_team.native_payload.name` to clean up the native team session
+3. **If TeamDelete is not available**: This is fine — teammate sessions will end naturally when their tasks complete. Log: "TeamDelete not available, teammates will complete naturally."
 
 ### Subagent Mode
 

package/src/core/templates/product-brief.md

@@ -0,0 +1,136 @@
+---
+brief_id: {{BRIEF_ID}}
+topic: {{TOPIC}}
+depth: {{DEPTH}}
+created: {{CREATED}}
+status: draft
+ideation_source: {{IDEATION_SOURCE}}
+research_sources: {{RESEARCH_SOURCES}}
+---
+
+# Product Brief: {{TOPIC}}
+
+## Executive Summary
+
+{{EXECUTIVE_SUMMARY}}
+
+---
+
+## Problem Statement
+
+### What Problem Are We Solving?
+
+{{PROBLEM_DESCRIPTION}}
+
+### Why Now?
+
+{{WHY_NOW}}
+
+### Who Has This Problem?
+
+{{TARGET_USERS}}
+
+---
+
+## User Personas
+
+### Persona 1: {{PERSONA_1_NAME}}
+
+- **Role**: {{PERSONA_1_ROLE}}
+- **Pain Points**: {{PERSONA_1_PAINS}}
+- **Goals**: {{PERSONA_1_GOALS}}
+- **Current Workaround**: {{PERSONA_1_WORKAROUND}}
+
+### Persona 2: {{PERSONA_2_NAME}}
+
+- **Role**: {{PERSONA_2_ROLE}}
+- **Pain Points**: {{PERSONA_2_PAINS}}
+- **Goals**: {{PERSONA_2_GOALS}}
+- **Current Workaround**: {{PERSONA_2_WORKAROUND}}
+
+---
+
+## Key Features (MoSCoW)
+
+### MUST HAVE (High-Confidence / Core Value)
+
+| # | Feature | Rationale | Source |
+|---|---------|-----------|--------|
+| 1 | {{MUST_1}} | {{RATIONALE}} | {{SOURCE}} |
+| 2 | {{MUST_2}} | {{RATIONALE}} | {{SOURCE}} |
+
+### SHOULD HAVE (Medium-Confidence / Important)
+
+| # | Feature | Rationale | Source |
+|---|---------|-----------|--------|
+| 1 | {{SHOULD_1}} | {{RATIONALE}} | {{SOURCE}} |
+| 2 | {{SHOULD_2}} | {{RATIONALE}} | {{SOURCE}} |
+
+### COULD HAVE (Nice-to-Have / Differentiators)
+
+| # | Feature | Rationale | Source |
+|---|---------|-----------|--------|
+| 1 | {{COULD_1}} | {{RATIONALE}} | {{SOURCE}} |
+
+### WON'T HAVE (Explicit Out-of-Scope)
+
+| # | Feature | Rationale |
+|---|---------|-----------|
+| 1 | {{WONT_1}} | {{RATIONALE}} |
+
+---
+
+## Success Metrics
+
+| Metric | Target | How to Measure |
+|--------|--------|----------------|
+| {{METRIC_1}} | {{TARGET_1}} | {{MEASURE_1}} |
+| {{METRIC_2}} | {{TARGET_2}} | {{MEASURE_2}} |
+| {{METRIC_3}} | {{TARGET_3}} | {{MEASURE_3}} |
+
+---
+
+## Business Case (Simple ROI)
+
+- **Effort Estimate**: {{EFFORT_ESTIMATE}}
+- **Expected Benefit**: {{EXPECTED_BENEFIT}}
+- **Payback Period**: {{PAYBACK_PERIOD}}
+- **Confidence Level**: {{ROI_CONFIDENCE}}
+
+---
+
+## Competitive Context
+
+### Existing Alternatives
+
+| Alternative | Strengths | Weaknesses | Our Differentiator |
+|-------------|-----------|------------|-------------------|
+| {{ALT_1}} | {{STRENGTHS}} | {{WEAKNESSES}} | {{DIFFERENTIATOR}} |
+| {{ALT_2}} | {{STRENGTHS}} | {{WEAKNESSES}} | {{DIFFERENTIATOR}} |
+
+### Positioning Statement
+
+{{POSITIONING}}
+
+---
+
+## Risks and Edge Cases
+
+| Risk | Severity | Likelihood | Mitigation |
+|------|----------|------------|------------|
+| {{RISK_1}} | {{SEV}} | {{LIKE}} | {{MITIGATION}} |
+| {{RISK_2}} | {{SEV}} | {{LIKE}} | {{MITIGATION}} |
+
+---
+
+## Technical Considerations
+
+{{TECHNICAL_NOTES}}
+
+---
+
+## Next Steps
+
+1. Create epic: `/agileflow:epic "{{TOPIC}}"`
+2. Generate stories: `/agileflow:auto`
+3. Implement: `/agileflow:babysit`

package/tools/cli/installers/ide/claude-code.js

@@ -61,9 +61,12 @@ class ClaudeCodeSetup extends BaseIdeSetup {
     // Claude Code specific: Setup damage control hooks
     await this.setupDamageControl(projectDir, agileflowDir, ideDir, options);
 
-    // Claude Code specific: Setup SessionStart hooks (welcome, archive, context-loader)
+    // Claude Code specific: Setup SessionStart hooks (welcome, archive, context-loader, tmux-task-watcher)
     await this.setupSessionStartHooks(projectDir, agileflowDir, ideDir, options);
 
+    // Claude Code specific: Setup Stop hooks (tmux-task-watcher cleanup)
+    await this.setupStopHooks(projectDir, agileflowDir, ideDir, options);
+
     return result;
   }
 
@@ -256,6 +259,12 @@ class ClaudeCodeSetup extends BaseIdeSetup {
           'node $CLAUDE_PROJECT_DIR/.agileflow/scripts/context-loader.js 2>/dev/null || true',
         timeout: 5000,
       },
+      {
+        type: 'command',
+        command:
+          'bash $CLAUDE_PROJECT_DIR/.agileflow/scripts/tmux-task-watcher.sh 2>/dev/null || true',
+        timeout: 5000,
+      },
     ];
 
     // Check if SessionStart hooks already exist
@@ -285,7 +294,65 @@ class ClaudeCodeSetup extends BaseIdeSetup {
 
     // Write settings
     await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
-    console.log(chalk.dim(`    - SessionStart hooks: welcome, archive, context-loader`));
+    console.log(
+      chalk.dim(`    - SessionStart hooks: welcome, archive, context-loader, tmux-task-watcher`)
+    );
+  }
+
+  /**
+   * Setup Stop hooks (tmux-task-watcher cleanup)
+   * @param {string} projectDir - Project directory
+   * @param {string} agileflowDir - AgileFlow installation directory
+   * @param {string} claudeDir - .claude directory path
+   * @param {Object} options - Setup options
+   */
+  async setupStopHooks(projectDir, agileflowDir, claudeDir, options = {}) {
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    let settings = {};
+
+    if (fs.existsSync(settingsPath)) {
+      try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      } catch (e) {
+        settings = {};
+      }
+    }
+
+    if (!settings.hooks) settings.hooks = {};
+    if (!settings.hooks.Stop) settings.hooks.Stop = [];
+
+    const stopHooks = [
+      {
+        type: 'command',
+        command:
+          'bash $CLAUDE_PROJECT_DIR/.agileflow/scripts/tmux-task-watcher.sh stop 2>/dev/null || true',
+        timeout: 3000,
+      },
+    ];
+
+    const existingEntry = settings.hooks.Stop.find(
+      h => h.matcher === '' || h.matcher === undefined
+    );
+
+    if (existingEntry) {
+      if (!existingEntry.hooks) existingEntry.hooks = [];
+      for (const newHook of stopHooks) {
+        const alreadyExists = existingEntry.hooks.some(
+          h => h.command && h.command.includes('tmux-task-watcher')
+        );
+        if (!alreadyExists) {
+          existingEntry.hooks.push(newHook);
+        }
+      }
+    } else {
+      settings.hooks.Stop.push({
+        matcher: '',
+        hooks: stopHooks,
+      });
+    }
+
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
+    console.log(chalk.dim(`    - Stop hooks: tmux-task-watcher cleanup`));
   }
 
   /**

package/src/core/agents/configuration/archival.md

@@ -1,350 +0,0 @@
----
-name: configuration-archival
-description: Configure AgileFlow auto-archival system for story status management
-tools:
-  - Bash
-  - Read
-  - Edit
-  - Write
-  - Glob
-  - Grep
-  - AskUserQuestion
-model: haiku
-team_role: teammate
----
-
-
-## STEP 0: Gather Context
-
-```bash
-node .agileflow/scripts/obtain-context.js configuration-archival
-```
-
----
-
-# Configuration Agent: Auto-Archival System
-
-Configure auto-archival system to manage status.json file size.
-
-## Prompt
-
-ROLE: Auto-Archival Configurator
-
-🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options:
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "How many days before archiving completed stories?",
-  "header": "Threshold",
-  "multiSelect": false,
-  "options": [
-    {"label": "30 days (Recommended)", "description": "Archive after 1 month"},
-    {"label": "14 days", "description": "Archive after 2 weeks"},
-    {"label": "7 days", "description": "Archive after 1 week"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-OBJECTIVE
-Configure the auto-archival system that prevents `docs/09-agents/status.json` from exceeding Claude Code's token limit by automatically moving old completed stories to an archive.
-
-## The Problem
-
-**IMPORTANT**: As projects grow, `docs/09-agents/status.json` can exceed Claude Code's token limit (25k tokens), causing agents to fail reading it. Auto-archival solves this by moving old completed stories to an archive.
-
-**Why This Matters**:
-- status.json grows as stories complete
-- Agents need to read status.json on every invocation
-- File exceeds 25k token limit → agents break with "file too large" error
-- Solution: Move old completed stories to status-archive.json
-
-## Configuration Steps
-
-### Step 1: Ask User for Archival Threshold
-
-Use AskUserQuestion tool to get user preference:
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "How long should completed stories remain in active status before archiving?",
-  "header": "Archival",
-  "multiSelect": false,
-  "options": [
-    {
-      "label": "30 days (Recommended)",
-      "description": "Monthly archival - default, keeps recent context visible"
-    },
-    {
-      "label": "14 days",
-      "description": "Bi-weekly archival - good balance for fast-moving projects"
-    },
-    {
-      "label": "7 days",
-      "description": "Weekly archival - for large teams with many stories"
-    },
-    {
-      "label": "3 days",
-      "description": "Very aggressive - keeps status.json very small"
-    }
-  ]
-}]</parameter>
-</invoke>
-```
-
-**Note**: User can also select "Other" to enter a custom number of days.
-
-### Step 2: Process User Choice
-
-Store choice in `docs/00-meta/agileflow-metadata.json`:
-
-```bash
-# Map user choice to days
-case "$CHOICE" in
-  "3 days") DAYS=3 ;;
-  "7 days") DAYS=7 ;;
-  "14 days") DAYS=14 ;;
-  "30 days") DAYS=30 ;;
-  *)
-    # User selected "Other" and entered custom days
-    # Extract number from custom input
-    DAYS=$(echo "$CHOICE" | grep -oE '[0-9]+')
-    if [ -z "$DAYS" ]; then
-      echo "⚠️ Invalid days value, defaulting to 30 days"
-      DAYS=30
-    fi
-    ;;
-esac
-
-# Update docs/00-meta/agileflow-metadata.json with archival config
-METADATA_FILE="docs/00-meta/agileflow-metadata.json"
-if [ -f "$METADATA_FILE" ]; then
-  # Update existing metadata
-  jq ".archival = {\"threshold_days\": $DAYS, \"enabled\": true} | .updated = \"$(date -u +"%Y-%m-%dT%H:%M:%SZ")\"" "$METADATA_FILE" > "${METADATA_FILE}.tmp" && mv "${METADATA_FILE}.tmp" "$METADATA_FILE"
-else
-  # Create new metadata (shouldn't happen if core system was set up)
-  cat > "$METADATA_FILE" << EOF
-{
-  "version": "2.28.0",
-  "created": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
-  "updated": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
-  "archival": {
-    "threshold_days": $DAYS,
-    "enabled": true
-  }
-}
-EOF
-fi
-
-echo "✅ Configured $DAYS-day archival threshold in agileflow-metadata.json"
-```
-
-### Step 3: Add Auto-Archival Hook
-
-Add SessionStart hook to `.claude/settings.json` (if not already present):
-
-```bash
-# Check if auto-archival hook already exists
-if ! grep -q "archive-completed-stories.sh" .claude/settings.json 2>/dev/null; then
-  # Add auto-archival hook to SessionStart
-  # Script reads threshold from agileflow-metadata.json automatically
-  jq '.hooks.SessionStart += [{
-    "matcher": "",
-    "hooks": [{
-      "type": "command",
-      "command": "bash .agileflow/scripts/archive-completed-stories.sh > /dev/null 2>&1 &"
-    }]
-  }]' .claude/settings.json > .claude/settings.json.tmp && mv .claude/settings.json.tmp .claude/settings.json
-
-  echo "✅ Added auto-archival hook to .claude/settings.json"
-else
-  echo "✅ Auto-archival hook already exists"
-fi
-```
-
-### Step 4: Deploy Archival Scripts
-
-Copy scripts from AgileFlow plugin to project:
-
-```bash
-# Check if AgileFlow plugin is installed
-PLUGIN_PATH="$HOME/.claude-code/plugins/AgileFlow"
-
-if [ -d "$PLUGIN_PATH" ]; then
-  # Copy archival script
-  if [ -f "$PLUGIN_PATH/scripts/archive-completed-stories.sh" ]; then
-    cp "$PLUGIN_PATH/scripts/archive-completed-stories.sh" scripts/archive-completed-stories.sh
-    chmod +x scripts/archive-completed-stories.sh
-    echo "✅ Deployed archival script: scripts/archive-completed-stories.sh"
-  else
-    echo "⚠️ Warning: archival script not found in plugin"
-  fi
-
-  # Copy compression script (v2.20.0+)
-  if [ -f "$PLUGIN_PATH/scripts/compress-status.sh" ]; then
-    cp "$PLUGIN_PATH/scripts/compress-status.sh" scripts/compress-status.sh
-    chmod +x scripts/compress-status.sh
-    echo "✅ Deployed compression script: scripts/compress-status.sh"
-  else
-    echo "⚠️ Warning: compression script not found in plugin"
-  fi
-else
-  echo "⚠️ Warning: AgileFlow plugin not found at $PLUGIN_PATH"
-  echo "   Auto-archival scripts will need to be manually copied"
-fi
-```
-
-### Step 5: Update CLAUDE.md
-
-Add auto-archival documentation to project's CLAUDE.md:
-
-```markdown
-## Auto-Archival System (AgileFlow v2.19.4+)
-
-AgileFlow automatically manages \`docs/09-agents/status.json\` file size by archiving old completed stories to \`docs/09-agents/status-archive.json\`.
-
-### Why Auto-Archival?
-
-**The Problem**:
-- status.json grows as stories complete (can reach 100KB+ in active projects)
-- Agents must read status.json on every invocation
-- Files >25k tokens cause agents to fail with "file too large" error
-- This breaks all agent workflows
-
-**The Solution**:
-- Automatically move completed stories older than threshold to status-archive.json
-- Keep only active work (ready, in-progress, blocked) + recent completions in status.json
-- Agents work fast with small, focused status.json
-- Full history preserved in archive (nothing deleted)
-
-### Configuration
-
-**Current Threshold**: {{DAYS}} days (completed stories older than {{DAYS}} days are archived)
-
-**To change threshold**:
-1. Edit \`docs/00-meta/agileflow-metadata.json\`:
-   \`\`\`bash
-   # Update threshold to 7 days
-   jq '.archival.threshold_days = 7 | .updated = "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'"' docs/00-meta/agileflow-metadata.json > tmp.json && mv tmp.json docs/00-meta/agileflow-metadata.json
-   \`\`\`
-2. Changes take effect immediately (no restart needed)
-3. Next SessionStart will use new threshold
-
-### How It Works
-
-**Auto-Archival Hook** (runs on SessionStart):
-- Checks \`docs/09-agents/status.json\` size
-- If large enough, runs: \`bash .agileflow/scripts/archive-completed-stories.sh <DAYS>\`
-- Moves completed stories older than threshold to status-archive.json
-- Updates status.json with only active + recent stories
-- Runs silently in background (no interruption)
-
-### File Structure
-
-**docs/09-agents/status.json** (active work):
-- Stories with status: ready, in-progress, blocked
-- Completed stories within threshold (recent completions)
-- Agents read this file (small, fast)
-
-**docs/09-agents/status-archive.json** (historical):
-- Completed stories older than threshold
-- Full history preserved
-- Agents rarely need to read this
-
-### Troubleshooting
-
-**If agents fail with "file too large"**:
-1. Run manual archival: \`bash .agileflow/scripts/archive-completed-stories.sh 7\`
-2. Reduce threshold in \`docs/00-meta/agileflow-metadata.json\` (e.g., 3 days instead of 30)
-3. Verify auto-archival hook is in \`.claude/settings.json\`
-
-**To view archived stories**:
-\`\`\`bash
-# List all archived stories
-jq '.stories | keys[]' docs/09-agents/status-archive.json
-
-# View specific archived story
-jq '.stories["US-0042"]' docs/09-agents/status-archive.json
-\`\`\`
-```
-
-**Note**: Replace `{{DAYS}}` with the actual threshold value chosen by the user.
-
-## Success Output
-
-After successful configuration, print:
-
-```
-✅ Auto-Archival System configured
-✅ Threshold: $DAYS days
-✅ Archive script deployed: scripts/archive-completed-stories.sh
-✅ Compression script deployed: scripts/compress-status.sh (v2.20.0+)
-✅ Auto-archival hook added to .claude/settings.json
-✅ Settings saved to docs/00-meta/agileflow-metadata.json
-✅ CLAUDE.md updated with archival documentation
-
-How it works:
-- Every time Claude Code starts (SessionStart hook)
-- Script checks docs/09-agents/status.json size
-- Reads threshold from docs/00-meta/agileflow-metadata.json
-- If needed, archives completed stories older than $DAYS days
-- Keeps status.json small and fast for agents
-- Full history preserved in docs/09-agents/status-archive.json
-
-Manual archival and compression:
-- Archival: bash .agileflow/scripts/archive-completed-stories.sh (reads from metadata)
-- Archival with custom threshold: bash .agileflow/scripts/archive-completed-stories.sh 7
-- Compression: /agileflow:compress (strips verbose fields if archival isn't enough)
-- View status: ls -lh docs/09-agents/status*.json
-
-Configuration:
-- Stored in: docs/00-meta/agileflow-metadata.json
-- Change threshold: jq '.archival.threshold_days = 7' docs/00-meta/agileflow-metadata.json
-- Takes effect immediately (no restart needed)
-
-Next steps:
-- Auto-archival runs automatically on SessionStart
-- Monitor file sizes: ls -lh docs/09-agents/status*.json
-- If status.json grows too large, reduce threshold or run manual archival
-```
-
-## Integration with Hooks System
-
-**IMPORTANT**: Auto-archival requires the hooks system to be configured first. This agent assumes `.claude/settings.json` already exists from the hooks configuration agent.
-
-- Auto-archival uses the hooks system
-- Runs silently in background on SessionStart
-- No user interruption or prompts during normal usage
-- Archives only when needed (status.json size triggers)
-
-### Update Metadata with Version
-
-Record the configured version for version tracking:
-
-```bash
-node -e "
-const fs = require('fs');
-const metaPath = 'docs/00-meta/agileflow-metadata.json';
-if (!fs.existsSync(metaPath)) process.exit(0);
-
-const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
-meta.features = meta.features || {};
-meta.features.archival = {
-  enabled: true,
-  configured_version: '2.40.0',
-  configured_at: new Date().toISOString()
-};
-meta.updated = new Date().toISOString();
-fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
-console.log('Updated metadata with archival version 2.40.0');
-"
-```
-
-## Rules
-
-- Validate JSON (no trailing commas)
-- Show preview before writing files
-- Use AskUserQuestion tool for user choices
-- Handle missing plugin gracefully (warn user)
-- Replace {{DAYS}} placeholder in CLAUDE.md with actual value