agileflow 2.99.0 → 2.99.2

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.99.2] - 2026-02-09
+
+### Added
+- Documentation overhaul with teams commands, frontmatter fixes, and damage control resilience
+
+## [2.99.1] - 2026-02-08
+
+### Added
+- Smart session management with context-aware naming and tmux quick-create keybinds
+
 ## [2.99.0] - 2026-02-08
 
 ### Added

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 [![npm version](https://img.shields.io/npm/v/agileflow?color=brightgreen)](https://www.npmjs.com/package/agileflow)
-[![Commands](https://img.shields.io/badge/commands-90-blue)](docs/04-architecture/commands.md)
+[![Commands](https://img.shields.io/badge/commands-91-blue)](docs/04-architecture/commands.md)
 [![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-47-orange)](docs/04-architecture/subagents.md)
 [![Skills](https://img.shields.io/badge/skills-dynamic-purple)](docs/04-architecture/skills.md)
 
@@ -65,7 +65,7 @@ AgileFlow combines three proven methodologies:
 
 | Component | Count | Description |
 |-----------|-------|-------------|
-| [Commands](docs/04-architecture/commands.md) | 90 | Slash commands for agile workflows |
+| [Commands](docs/04-architecture/commands.md) | 91 | Slash commands for agile workflows |
 | [Agents/Experts](docs/04-architecture/subagents.md) | 47 | Specialized agents with self-improving knowledge bases |
 | [Skills](docs/04-architecture/skills.md) | Dynamic | Generated on-demand with `/agileflow:skill:create` |
 
@@ -76,7 +76,7 @@ AgileFlow combines three proven methodologies:
 Full documentation lives in [`docs/04-architecture/`](docs/04-architecture/):
 
 ### Reference
-- [Commands](docs/04-architecture/commands.md) - All 90 slash commands
+- [Commands](docs/04-architecture/commands.md) - All 91 slash commands
 - [Agents/Experts](docs/04-architecture/subagents.md) - 47 specialized agents with self-improving knowledge
 - [Skills](docs/04-architecture/skills.md) - Dynamic skill generator with MCP integration
 

package/lib/dashboard-protocol.js

@@ -78,6 +78,9 @@ const OutboundMessageType = {
   // User Interaction
   ASK_USER_QUESTION: 'ask_user_question', // Claude is asking user a question
 
+  // Sessions
+  SESSION_LIST: 'session_list', // Session list with sync status
+
   // Errors
   ERROR: 'error', // General error
 };
@@ -123,6 +126,9 @@ const InboundMessageType = {
   INBOX_LIST_REQUEST: 'inbox_list_request', // Request inbox list
   INBOX_ACTION: 'inbox_action', // Accept/dismiss inbox item
 
+  // File Operations
+  OPEN_FILE: 'open_file', // Open file in editor
+
   // User Interaction Response
   USER_ANSWER: 'user_answer', // User's answer to AskUserQuestion
 };
@@ -435,6 +441,36 @@ function createInboxItem(item) {
   };
 }
 
+/**
+ * Create a project status update message
+ * @param {Object} summary - Status summary
+ * @param {number} summary.total - Total stories
+ * @param {number} summary.done - Completed stories
+ * @param {number} summary.inProgress - In-progress stories
+ * @param {number} summary.ready - Ready stories
+ * @param {number} summary.blocked - Blocked stories
+ * @param {Object[]} summary.epics - Epic summaries
+ */
+function createStatusUpdate(summary) {
+  return {
+    type: OutboundMessageType.STATUS_UPDATE,
+    ...summary,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * Create a session list message with sync status
+ * @param {Object[]} sessions - Array of session objects with sync info
+ */
+function createSessionList(sessions) {
+  return {
+    type: OutboundMessageType.SESSION_LIST,
+    sessions,
+    timestamp: new Date().toISOString(),
+  };
+}
+
 /**
  * Create an AskUserQuestion message
  * @param {string} toolId - Tool call ID for response correlation
@@ -533,6 +569,8 @@ module.exports = {
   createInboxList,
   createInboxItem,
   createAskUserQuestion,
+  createStatusUpdate,
+  createSessionList,
 
   // Parsing
   parseInboundMessage,

package/lib/dashboard-server.js

@@ -38,6 +38,8 @@ const {
   createAutomationResult,
   createInboxList,
   createInboxItem,
+  createStatusUpdate,
+  createSessionList,
   parseInboundMessage,
   serializeMessage,
 } = require('./dashboard-protocol');
@@ -510,7 +512,8 @@ class DashboardServer extends EventEmitter {
     // Auth is on by default - auto-generate key if not provided
     // Set requireAuth: false explicitly to disable
     this.requireAuth = options.requireAuth !== false;
-    this.apiKey = options.apiKey || (this.requireAuth ? crypto.randomBytes(32).toString('hex') : null);
+    this.apiKey =
+      options.apiKey || (this.requireAuth ? crypto.randomBytes(32).toString('hex') : null);
 
     // Session management
     this.sessions = new Map();
@@ -708,8 +711,10 @@ class DashboardServer extends EventEmitter {
       // Use timing-safe comparison to prevent timing attacks
       const keyBuffer = Buffer.from(this.apiKey, 'utf8');
       const providedBuffer = Buffer.from(providedKey, 'utf8');
-      if (keyBuffer.length !== providedBuffer.length ||
-          !crypto.timingSafeEqual(keyBuffer, providedBuffer)) {
+      if (
+        keyBuffer.length !== providedBuffer.length ||
+        !crypto.timingSafeEqual(keyBuffer, providedBuffer)
+      ) {
         socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
         socket.destroy();
         return;
@@ -720,9 +725,12 @@ class DashboardServer extends EventEmitter {
     const origin = req.headers.origin;
     if (origin) {
       const LOCALHOST_ORIGINS = [
-        'http://localhost', 'https://localhost',
-        'http://127.0.0.1', 'https://127.0.0.1',
-        'http://[::1]', 'https://[::1]',
+        'http://localhost',
+        'https://localhost',
+        'http://127.0.0.1',
+        'https://127.0.0.1',
+        'http://[::1]',
+        'https://[::1]',
       ];
       const isLocalhost = LOCALHOST_ORIGINS.some(
         allowed => origin === allowed || origin.startsWith(allowed + ':')
@@ -803,6 +811,12 @@ class DashboardServer extends EventEmitter {
     // Send initial git status
     this.sendGitStatus(session);
 
+    // Send project status (stories/epics)
+    this.sendStatusUpdate(session);
+
+    // Send session list with sync info
+    this.sendSessionList(session);
+
     // Send initial automation list and inbox
     this.sendAutomationList(session);
     this.sendInboxList(session);
@@ -936,6 +950,10 @@ class DashboardServer extends EventEmitter {
         this.handleInboxAction(session, message);
         break;
 
+      case InboundMessageType.OPEN_FILE:
+        this.handleOpenFile(session, message);
+        break;
+
       default:
         console.log(`[Session ${session.id}] Unhandled message type: ${message.type}`);
         this.emit('message', session, message);
@@ -985,8 +1003,12 @@ class DashboardServer extends EventEmitter {
         this.emit('refresh:tasks', session);
         break;
       case 'status':
+        this.sendStatusUpdate(session);
         this.emit('refresh:status', session);
         break;
+      case 'sessions':
+        this.sendSessionList(session);
+        break;
       case 'automations':
         this.sendAutomationList(session);
         break;
@@ -995,6 +1017,8 @@ class DashboardServer extends EventEmitter {
         break;
       default:
         this.sendGitStatus(session);
+        this.sendStatusUpdate(session);
+        this.sendSessionList(session);
         this.sendAutomationList(session);
         this.sendInboxList(session);
         this.emit('refresh:all', session);
@@ -1260,6 +1284,170 @@ class DashboardServer extends EventEmitter {
     return { additions, deletions };
   }
 
+  /**
+   * Send project status update (stories/epics summary) to session
+   */
+  sendStatusUpdate(session) {
+    const path = require('path');
+    const fs = require('fs');
+    const statusPath = path.join(this.projectRoot, 'docs', '09-agents', 'status.json');
+    if (!fs.existsSync(statusPath)) return;
+
+    try {
+      const data = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
+      const stories = data.stories || {};
+      const epics = data.epics || {};
+
+      const storyValues = Object.values(stories);
+      const summary = {
+        total: storyValues.length,
+        done: storyValues.filter(s => s.status === 'done' || s.status === 'completed').length,
+        inProgress: storyValues.filter(s => s.status === 'in-progress').length,
+        ready: storyValues.filter(s => s.status === 'ready').length,
+        blocked: storyValues.filter(s => s.status === 'blocked').length,
+        epics: Object.entries(epics).map(([id, e]) => ({
+          id,
+          title: e.title || id,
+          status: e.status || 'unknown',
+          storyCount: (e.stories || []).length,
+          doneCount: (e.stories || []).filter(
+            sid =>
+              stories[sid] &&
+              (stories[sid].status === 'done' || stories[sid].status === 'completed')
+          ).length,
+        })),
+      };
+
+      session.send(createStatusUpdate(summary));
+    } catch (error) {
+      console.error('[Status Update Error]', error.message);
+    }
+  }
+
+  /**
+   * Send session list with sync status to dashboard
+   */
+  sendSessionList(session) {
+    const sessions = [];
+
+    for (const [id, s] of this.sessions) {
+      const entry = {
+        id,
+        name: s.metadata.name || id,
+        type: s.metadata.type || 'local',
+        status: s.state === 'connected' ? 'active' : s.state === 'disconnected' ? 'idle' : s.state,
+        branch: null,
+        messageCount: s.messages.length,
+        lastActivity: s.lastActivity.toISOString(),
+        syncStatus: 'offline',
+        ahead: 0,
+        behind: 0,
+      };
+
+      // Get branch and sync status via git
+      try {
+        const cwd = s.metadata.worktreePath || this.projectRoot;
+        entry.branch = execFileSync('git', ['branch', '--show-current'], {
+          cwd,
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+
+        // Get ahead/behind counts relative to upstream
+        try {
+          const counts = execFileSync(
+            'git',
+            ['rev-list', '--left-right', '--count', 'HEAD...@{u}'],
+            {
+              cwd,
+              encoding: 'utf8',
+              stdio: ['pipe', 'pipe', 'pipe'],
+            }
+          ).trim();
+          const [ahead, behind] = counts.split(/\s+/).map(Number);
+          entry.ahead = ahead || 0;
+          entry.behind = behind || 0;
+
+          if (ahead > 0 && behind > 0) {
+            entry.syncStatus = 'diverged';
+          } else if (ahead > 0) {
+            entry.syncStatus = 'ahead';
+          } else if (behind > 0) {
+            entry.syncStatus = 'behind';
+          } else {
+            entry.syncStatus = 'synced';
+          }
+        } catch {
+          // No upstream configured
+          entry.syncStatus = 'synced';
+        }
+      } catch {
+        entry.syncStatus = 'offline';
+      }
+
+      sessions.push(entry);
+    }
+
+    session.send(createSessionList(sessions));
+  }
+
+  /**
+   * Handle open file in editor request
+   */
+  handleOpenFile(session, message) {
+    const { path: filePath, line } = message;
+
+    if (!filePath || typeof filePath !== 'string') {
+      session.send(createError('INVALID_REQUEST', 'File path is required'));
+      return;
+    }
+
+    // Validate the path stays within project root
+    const pathResult = validatePath(filePath, this.projectRoot, { allowSymlinks: true });
+    if (!pathResult.ok) {
+      session.send(createError('OPEN_FILE_ERROR', 'File path outside project'));
+      return;
+    }
+
+    const fullPath = pathResult.resolvedPath;
+
+    // Detect editor from environment
+    const editor = process.env.VISUAL || process.env.EDITOR || 'code';
+    const editorBase = require('path').basename(editor).toLowerCase();
+
+    try {
+      const lineNum = Number.isFinite(line) && line > 0 ? line : null;
+
+      switch (editorBase) {
+        case 'code':
+        case 'cursor':
+        case 'windsurf': {
+          const gotoArg = lineNum ? `${fullPath}:${lineNum}` : fullPath;
+          spawn(editor, ['--goto', gotoArg], { detached: true, stdio: 'ignore' }).unref();
+          break;
+        }
+        case 'subl':
+        case 'sublime_text': {
+          const sublArg = lineNum ? `${fullPath}:${lineNum}` : fullPath;
+          spawn(editor, [sublArg], { detached: true, stdio: 'ignore' }).unref();
+          break;
+        }
+        default: {
+          // Generic: just open the file
+          spawn(editor, [fullPath], { detached: true, stdio: 'ignore' }).unref();
+          break;
+        }
+      }
+
+      session.send(
+        createNotification('info', 'Editor', `Opened ${require('path').basename(fullPath)}`)
+      );
+    } catch (error) {
+      console.error('[Open File Error]', error.message);
+      session.send(createError('OPEN_FILE_ERROR', `Failed to open file: ${error.message}`));
+    }
+  }
+
   /**
    * Handle terminal spawn request
    */
@@ -1271,7 +1459,9 @@ class DashboardServer extends EventEmitter {
     if (cwd) {
       const cwdResult = validatePath(cwd, this.projectRoot, { allowSymlinks: true });
       if (!cwdResult.ok) {
-        session.send(createError('TERMINAL_ERROR', 'Working directory must be within project root'));
+        session.send(
+          createError('TERMINAL_ERROR', 'Working directory must be within project root')
+        );
         return;
       }
       safeCwd = cwdResult.resolvedPath;

package/lib/feedback.js

@@ -72,7 +72,10 @@ class Feedback {
   constructor(options = {}) {
     this.isTTY = options.isTTY !== undefined ? options.isTTY : process.stdout.isTTY;
     this.indent = options.indent || 0;
-    this.quiet = options.quiet || false;
+    this.quiet =
+      options.quiet !== undefined
+        ? options.quiet
+        : process.env.AGILEFLOW_QUIET === '1' || process.env.AGILEFLOW_QUIET === 'true';
     this.verbose = options.verbose || false;
   }
 
@@ -274,7 +277,8 @@ class Feedback {
 class FeedbackSpinner {
   constructor(message, options = {}) {
     this.message = message;
-    this.isTTY = options.isTTY !== undefined ? options.isTTY : process.stdout.isTTY;
+    this.stream = options.stream || process.stdout;
+    this.isTTY = options.isTTY !== undefined ? options.isTTY : this.stream.isTTY;
     this.indent = options.indent || 0;
     this.interval = options.interval || 80;
     this.frameIndex = 0;
@@ -286,13 +290,26 @@ class FeedbackSpinner {
     return '  '.repeat(this.indent);
   }
 
+  /**
+   * Write a line to the appropriate stream
+   * @param {string} text - Text to write
+   * @private
+   */
+  _writeln(text) {
+    if (this.stream !== process.stdout) {
+      this.stream.write(text + '\n');
+    } else {
+      console.log(text);
+    }
+  }
+
   /**
    * Start the spinner
    * @returns {FeedbackSpinner}
    */
   start() {
     if (!this.isTTY) {
-      console.log(`${this._prefix()}${c.dim}${this.message}${c.reset}`);
+      this._writeln(`${this._prefix()}${c.dim}${this.message}${c.reset}`);
       return this;
     }
 
@@ -327,9 +344,9 @@ class FeedbackSpinner {
     if (!this.isTTY) return;
     const frame = SPINNER_FRAMES[this.frameIndex];
     const line = `${this._prefix()}${c.cyan}${frame}${c.reset} ${this.message}`;
-    process.stdout.clearLine(0);
-    process.stdout.cursorTo(0);
-    process.stdout.write(line);
+    this.stream.clearLine(0);
+    this.stream.cursorTo(0);
+    this.stream.write(line);
   }
 
   /**
@@ -346,8 +363,8 @@ class FeedbackSpinner {
     }
 
     if (this.isTTY) {
-      process.stdout.clearLine(0);
-      process.stdout.cursorTo(0);
+      this.stream.clearLine(0);
+      this.stream.cursorTo(0);
     }
 
     const elapsed = this.startTime ? Date.now() - this.startTime : 0;
@@ -355,7 +372,7 @@ class FeedbackSpinner {
       elapsed > DOHERTY_THRESHOLD_MS ? ` ${c.dim}(${formatDuration(elapsed)})${c.reset}` : '';
     const msg = message || this.message;
 
-    console.log(`${this._prefix()}${color}${symbol}${c.reset} ${msg}${suffix}`);
+    this._writeln(`${this._prefix()}${color}${symbol}${c.reset} ${msg}${suffix}`);
     return this;
   }
 
@@ -548,12 +565,22 @@ class FeedbackProgressBar {
 // Singleton instance for convenience
 const feedback = new Feedback();
 
+/**
+ * Factory function to create a configured Feedback instance
+ * @param {Object} [options={}] - Feedback options
+ * @returns {Feedback}
+ */
+function createFeedback(options = {}) {
+  return new Feedback(options);
+}
+
 module.exports = {
   Feedback,
   FeedbackSpinner,
   FeedbackTask,
   FeedbackProgressBar,
   feedback,
+  createFeedback,
   SYMBOLS,
   SPINNER_FRAMES,
   DOHERTY_THRESHOLD_MS,

package/lib/git-operations.js

@@ -80,7 +80,10 @@ function getCurrentBranch(cwd = ROOT) {
   if (cached !== null) return cached;
 
   try {
-    const branch = execFileSync('git', ['branch', '--show-current'], { cwd, encoding: 'utf8' }).trim();
+    const branch = execFileSync('git', ['branch', '--show-current'], {
+      cwd,
+      encoding: 'utf8',
+    }).trim();
     gitCache.set(cacheKey, branch);
     return branch;
   } catch (e) {

package/lib/merge-operations.js

@@ -263,6 +263,31 @@ function integrateSession(sessionId, options = {}, loadRegistry, saveRegistry, r
     mainPath: ROOT,
   };
 
+  // Write merge notification for other sessions to pick up
+  try {
+    const notifyDir = path.join(getAgileflowDir(ROOT), 'sessions');
+    if (!fs.existsSync(notifyDir)) {
+      fs.mkdirSync(notifyDir, { recursive: true });
+    }
+    const notifyPath = path.join(notifyDir, 'last-merge.json');
+    fs.writeFileSync(
+      notifyPath,
+      JSON.stringify(
+        {
+          merged_at: new Date().toISOString(),
+          session_id: sessionId,
+          branch: branchName,
+          strategy,
+          commit_message: commitMessage,
+        },
+        null,
+        2
+      )
+    );
+  } catch (e) {
+    /* ignore notification write failures */
+  }
+
   // Delete worktree first (before branch, as worktree holds ref)
   if (deleteWorktree && session.path !== ROOT && fs.existsSync(session.path)) {
     try {

package/lib/progress.js

@@ -34,7 +34,8 @@ class Spinner {
   constructor(message, options = {}) {
     this.message = message;
     this.interval = options.interval || 80;
-    this.enabled = options.enabled !== false && process.stdout.isTTY;
+    this.stream = options.stream || process.stdout;
+    this.enabled = options.enabled !== false && this.stream.isTTY;
     this.frameIndex = 0;
     this.timer = null;
     this.startTime = null;
@@ -108,9 +109,9 @@ class Spinner {
     const line = `${c.cyan}${frame}${c.reset} ${this.message}`;
 
     // Clear line and write new content
-    process.stdout.clearLine(0);
-    process.stdout.cursorTo(0);
-    process.stdout.write(line);
+    this.stream.clearLine(0);
+    this.stream.cursorTo(0);
+    this.stream.write(line);
   }
 
   /**
@@ -163,8 +164,8 @@ class Spinner {
     }
 
     if (this.enabled) {
-      process.stdout.clearLine(0);
-      process.stdout.cursorTo(0);
+      this.stream.clearLine(0);
+      this.stream.cursorTo(0);
     }
 
     const elapsed = this.startTime ? Date.now() - this.startTime : 0;