@specforge/mcp 3.0.6 → 3.1.0

package/dist/cli/commands/plan.js

@@ -0,0 +1,154 @@
+/**
+ * Plan Command
+ *
+ * Dry-run visualization of the Agent Teams implementation plan.
+ * Calls get_implementation_plan via MCP and displays an ASCII tree
+ * showing team-worker mapping, execution phases, and dependency status.
+ */
+import ora from 'ora';
+import { resolveConfig } from '../config/index.js';
+import { loadProjectConfig, getActiveSpecification } from '../config/loader.js';
+import { withErrorHandler, CliError, NetworkError } from '../middleware/error-handler.js';
+import { printBlank, printJson } from '../ui/output.js';
+import { colors } from '../ui/colors.js';
+import { ApiClient } from '../../client/api-client.js';
+/**
+ * Resolve the specification ID from options or active spec config
+ */
+function resolveSpecificationId(options, configSpecId) {
+    if (options.spec) {
+        return options.spec;
+    }
+    // Try active specification from .specforge.json
+    const projectConfig = loadProjectConfig();
+    const activeSpec = getActiveSpecification(projectConfig);
+    if (activeSpec?.id) {
+        return activeSpec.id;
+    }
+    // Fall back to specificationId from resolved config
+    if (configSpecId) {
+        return configSpecId;
+    }
+    throw new CliError('No active specification', 1, "Run 'specforge spec activate <id>' to set an active specification, or use --spec <id>");
+}
+/**
+ * Render the ASCII tree visualization of the implementation plan
+ */
+function renderPlanTree(plan) {
+    printBlank();
+    // Strategy header
+    console.log(`${colors.bold('Strategy:')} ${colors.primary(plan.strategy)} ${colors.muted(`(${plan.reasoning})`)}`);
+    printBlank();
+    if (plan.teams.length === 0) {
+        console.log(colors.muted('No teams to display. The specification may have no remaining work.'));
+        printBlank();
+        return;
+    }
+    // Build a lookup: team name -> phase number
+    const teamPhaseMap = new Map();
+    for (const phase of plan.executionOrder) {
+        for (const teamName of phase.teams) {
+            teamPhaseMap.set(teamName, phase.phase);
+        }
+    }
+    // Render by execution phase
+    for (const phase of plan.executionOrder) {
+        const phaseLabel = phase.phase === 1
+            ? 'parallel'
+            : `after phase ${phase.phase - 1}`;
+        console.log(colors.bold(`Phase ${phase.phase}`) + colors.muted(` (${phaseLabel}):`));
+        // Find teams in this phase
+        const phaseTeams = plan.teams.filter(t => phase.teams.includes(t.name));
+        for (const team of phaseTeams) {
+            console.log(`  ${colors.bold('Team:')} ${colors.primary(team.name)} ${colors.muted(`(${team.suggestedWorkers} worker${team.suggestedWorkers === 1 ? '' : 's'})`)}`);
+            for (const task of team.tasks) {
+                const isBlocked = task.blockedBy.length > 0;
+                if (isBlocked) {
+                    const deps = task.blockedBy.join(', ');
+                    console.log(`    ${colors.warning('[BLOCKED]')} ${task.slug}: ${task.title} ${colors.muted(`(by ${deps})`)}`);
+                }
+                else {
+                    console.log(`    ${colors.success('[READY]')}   ${task.slug}: ${task.title}`);
+                }
+            }
+        }
+        printBlank();
+    }
+    // Summary line
+    console.log(`${colors.bold('Total:')} ${plan.estimatedTotalTickets} tickets, ` +
+        `${plan.estimatedParallelizableTickets} parallelizable`);
+    printBlank();
+}
+/**
+ * Plan command action handler
+ */
+export async function planAction(options) {
+    const config = resolveConfig();
+    if (!config.apiKey) {
+        throw new CliError('Not authenticated', 1, 'Run `specforge login` to authenticate first');
+    }
+    const specificationId = resolveSpecificationId(options, config.specificationId);
+    const spinner = ora({
+        text: 'Generating implementation plan...',
+        color: 'cyan',
+    }).start();
+    try {
+        const client = new ApiClient({
+            apiKey: config.apiKey,
+            apiUrl: config.apiUrl,
+            debug: config.debug,
+        });
+        const plan = await client.call('get_implementation_plan', {
+            specificationId,
+            ...(options.strategy && options.strategy !== 'auto' ? { strategy: options.strategy } : {}),
+        });
+        spinner.stop();
+        if (options.json) {
+            printJson(plan);
+        }
+        else {
+            renderPlanTree(plan);
+        }
+    }
+    catch (error) {
+        spinner.fail('Failed to generate implementation plan');
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        if (message.includes('401') || message.includes('Unauthorized')) {
+            throw new CliError('Authentication failed', 1, 'Your API key may be invalid. Run `specforge login` to re-authenticate');
+        }
+        if (message.includes('404') || message.includes('Not Found') || message.includes('not found')) {
+            throw new CliError(`Specification not found: ${specificationId}`, 1, "Run 'specforge specs' to list available specifications.");
+        }
+        throw new NetworkError(`Failed to generate plan: ${message}`);
+    }
+}
+/**
+ * Register plan command with Commander
+ */
+export function registerPlanCommand(program) {
+    program
+        .command('plan')
+        .description('Preview Agent Teams implementation plan (dry-run)')
+        .option('--strategy <type>', 'Override strategy: epic-as-team | spec-as-team | single-session | auto')
+        .option('--spec <id>', 'Specification ID (overrides active spec)')
+        .option('--json', 'Output raw JSON plan')
+        .addHelpText('after', `
+Examples:
+  $ specforge plan                                  # Preview plan for active spec
+  $ specforge plan --strategy epic-as-team          # Force epic-as-team strategy
+  $ specforge plan --spec ff1f8edb-4976-458b-acb0   # Plan for a specific spec
+  $ specforge plan --json                           # Output raw JSON for scripting
+
+Output shows:
+  - Strategy name and reasoning
+  - Execution phases with team groupings
+  - Ticket-to-worker mapping with dependency indicators
+  - [READY] for tickets that can start immediately
+  - [BLOCKED] for tickets waiting on dependencies
+
+This is a dry-run visualization - it does NOT execute anything.
+Use 'specforge spec activate <specId>' to set the active specification.
+`)
+        .action(withErrorHandler(planAction));
+}
+//# sourceMappingURL=plan.js.map

package/dist/cli/commands/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../src/cli/commands/plan.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/plan.types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Plan Command Types
+ *
+ * Type definitions for the plan dry-run visualization command
+ * that previews Agent Teams implementation plans.
+ */
+/**
+ * Command line options for plan command
+ */
+export interface PlanOptions {
+    /** Output as raw JSON */
+    json?: boolean;
+    /** Override strategy: epic-as-team | spec-as-team | single-session | auto */
+    strategy?: string;
+    /** Override specification ID (instead of using active spec) */
+    spec?: string;
+}
+/**
+ * A single task within a team
+ */
+export interface TaskDefinition {
+    ticketId: string;
+    title: string;
+    slug: string;
+    blockedBy: string[];
+    estimatedComplexity: string;
+    workspace: string | null;
+}
+/**
+ * A team definition from the implementation plan
+ */
+export interface TeamDefinition {
+    name: string;
+    epicId: string;
+    epicTitle: string;
+    suggestedWorkers: number;
+    targetWorkspace: string | null;
+    canParallelizeWith: string[];
+    mustPrecede: string[];
+    tasks: TaskDefinition[];
+}
+/**
+ * An execution phase grouping teams
+ */
+export interface ExecutionPhase {
+    phase: number;
+    teams: string[];
+}
+/**
+ * Full implementation plan response from the API
+ */
+export interface ImplementationPlan {
+    strategy: string;
+    reasoning: string;
+    teams: TeamDefinition[];
+    executionOrder: ExecutionPhase[];
+    estimatedTotalTickets: number;
+    estimatedParallelizableTickets: number;
+}
+//# sourceMappingURL=plan.types.d.ts.map

package/dist/cli/commands/plan.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.types.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/plan.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,yBAAyB;IACzB,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,cAAc,EAAE,cAAc,EAAE,CAAC;IACjC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,8BAA8B,EAAE,MAAM,CAAC;CACxC"}

package/dist/cli/commands/plan.types.js

@@ -0,0 +1,8 @@
+/**
+ * Plan Command Types
+ *
+ * Type definitions for the plan dry-run visualization command
+ * that previews Agent Teams implementation plans.
+ */
+export {};
+//# sourceMappingURL=plan.types.js.map

package/dist/cli/commands/plan.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.types.js","sourceRoot":"","sources":["../../../src/cli/commands/plan.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/cli/commands/spec-activate.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Spec Activate Command
+ *
+ * Sets or clears the active specification in .specforge.json.
+ * The active specification tells Agent Teams which spec to implement.
+ */
+import { Command } from 'commander';
+/**
+ * Activate a specification as the active spec for Agent Teams
+ *
+ * @param specId Specification ID to activate
+ * @param options Command options
+ */
+export declare function specActivateAction(specId: string, options: {
+    json?: boolean;
+}): Promise<void>;
+/**
+ * Deactivate the current active specification
+ *
+ * @param options Command options
+ */
+export declare function specDeactivateAction(options: {
+    json?: boolean;
+}): Promise<void>;
+/**
+ * Register spec activate/deactivate commands with Commander
+ */
+export declare function registerSpecActivateCommand(program: Command): void;
+//# sourceMappingURL=spec-activate.d.ts.map

package/dist/cli/commands/spec-activate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-activate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/spec-activate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CA2Gf;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuClE"}

package/dist/cli/commands/spec-activate.js

@@ -0,0 +1,155 @@
+/**
+ * Spec Activate Command
+ *
+ * Sets or clears the active specification in .specforge.json.
+ * The active specification tells Agent Teams which spec to implement.
+ */
+import ora from 'ora';
+import { resolveConfig } from '../config/index.js';
+import { setActiveSpecification } from '../config/writer.js';
+import { withErrorHandler, CliError, NetworkError, ValidationError } from '../middleware/error-handler.js';
+import { printBlank, printSuccess, printJson } from '../ui/output.js';
+import { colors } from '../ui/colors.js';
+import { ApiClient } from '../../client/api-client.js';
+/**
+ * Activate a specification as the active spec for Agent Teams
+ *
+ * @param specId Specification ID to activate
+ * @param options Command options
+ */
+export async function specActivateAction(specId, options) {
+    if (!specId || specId.trim() === '') {
+        throw new ValidationError('Specification ID is required', 'Usage: specforge spec activate <specId>');
+    }
+    const config = resolveConfig();
+    if (!config.apiKey) {
+        throw new CliError('Not authenticated', 1, 'Run `specforge login` to authenticate first');
+    }
+    const spinner = ora({
+        text: 'Validating specification...',
+        color: 'cyan',
+    }).start();
+    try {
+        const client = new ApiClient({
+            apiKey: config.apiKey,
+            apiUrl: config.apiUrl,
+            debug: config.debug,
+        });
+        // Validate the specification exists
+        const spec = await client.call('get_specification', {
+            specificationId: specId,
+            summary: true,
+        });
+        if (!spec || !spec.id) {
+            spinner.fail('Specification not found');
+            throw new CliError(`Specification not found: ${specId}`, 1, "Run 'specforge specs' to list available specifications.");
+        }
+        // Set active specification in .specforge.json
+        spinner.text = 'Setting active specification...';
+        setActiveSpecification({
+            id: spec.id,
+            title: spec.title,
+            activatedAt: new Date().toISOString(),
+        });
+        spinner.succeed(`Active specification set to: ${colors.primary(spec.title)}`);
+        if (options.json) {
+            printJson({
+                action: 'activate',
+                specification: {
+                    id: spec.id,
+                    title: spec.title,
+                    status: spec.status,
+                    epicCount: spec.epicCount,
+                    ticketCount: spec.ticketCount,
+                    completedTicketCount: spec.completedTicketCount,
+                },
+            });
+        }
+        else {
+            printBlank();
+            console.log(colors.muted(`  ID:      ${spec.id}`));
+            console.log(colors.muted(`  Status:  ${spec.status}`));
+            if (spec.ticketCount !== undefined) {
+                const completed = spec.completedTicketCount ?? 0;
+                console.log(colors.muted(`  Tickets: ${completed}/${spec.ticketCount} completed`));
+            }
+            printBlank();
+            console.log(colors.muted("Run 'specforge status' to see the current context."));
+            printBlank();
+        }
+    }
+    catch (error) {
+        if (error instanceof CliError || error instanceof ValidationError) {
+            spinner.stop();
+            throw error;
+        }
+        spinner.fail('Failed to activate specification');
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        if (message.includes('401') || message.includes('Unauthorized')) {
+            throw new CliError('Authentication failed', 1, 'Your API key may be invalid. Run `specforge login` to re-authenticate');
+        }
+        if (message.includes('404') || message.includes('Not Found') || message.includes('not found')) {
+            throw new CliError(`Specification not found: ${specId}`, 1, "Run 'specforge specs' to list available specifications.");
+        }
+        throw new NetworkError(`Failed to activate specification: ${message}`);
+    }
+}
+/**
+ * Deactivate the current active specification
+ *
+ * @param options Command options
+ */
+export async function specDeactivateAction(options) {
+    setActiveSpecification(null);
+    if (options.json) {
+        printJson({ action: 'deactivate', specification: null });
+    }
+    else {
+        printSuccess('Active specification cleared');
+        printBlank();
+        console.log(colors.muted("No specification is active. Run 'specforge spec activate <specId>' to set one."));
+        printBlank();
+    }
+}
+/**
+ * Register spec activate/deactivate commands with Commander
+ */
+export function registerSpecActivateCommand(program) {
+    const spec = program
+        .command('spec')
+        .description('Manage active specification for Agent Teams');
+    spec
+        .command('activate <specId>')
+        .description('Set active specification for Agent Teams implementation')
+        .option('--json', 'Output in JSON format')
+        .addHelpText('after', `
+Arguments:
+  specId    Specification ID to activate
+
+Examples:
+  $ specforge spec activate ff1f8edb-4976-458b-acb0-b0860cd9a60d
+  $ specforge spec activate ff1f8edb --json
+
+The active specification is stored in .specforge.json and tells Agent Teams
+which specification to implement when you say "implement the active spec".
+
+Use 'specforge specs' to list available specifications.
+Use 'specforge spec deactivate' to clear the active specification.
+`)
+        .action(withErrorHandler(specActivateAction));
+    spec
+        .command('deactivate')
+        .description('Clear the active specification')
+        .option('--json', 'Output in JSON format')
+        .addHelpText('after', `
+Examples:
+  $ specforge spec deactivate
+  $ specforge spec deactivate --json
+
+Removes the activeSpecification section from .specforge.json.
+`)
+        .action(withErrorHandler(async (options) => {
+        await specDeactivateAction(options);
+    }));
+}
+//# sourceMappingURL=spec-activate.js.map

package/dist/cli/commands/spec-activate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-activate.js","sourceRoot":"","sources":["../../../src/cli/commands/spec-activate.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/spec-activate.types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Spec Activate Command Types
+ *
+ * Type definitions for the spec activate/deactivate commands
+ * that manage the active specification in .specforge.json.
+ */
+/**
+ * Specification summary from get_specification API (summary mode)
+ */
+export interface SpecificationSummary {
+    /** Specification ID */
+    id: string;
+    /** Specification title */
+    title: string;
+    /** Current status */
+    status: string;
+    /** Number of epics */
+    epicCount?: number;
+    /** Total number of tickets */
+    ticketCount?: number;
+    /** Number of completed tickets */
+    completedTicketCount?: number;
+}
+//# sourceMappingURL=spec-activate.types.d.ts.map

package/dist/cli/commands/spec-activate.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-activate.types.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/spec-activate.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,uBAAuB;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B"}

package/dist/cli/commands/spec-activate.types.js

@@ -0,0 +1,8 @@
+/**
+ * Spec Activate Command Types
+ *
+ * Type definitions for the spec activate/deactivate commands
+ * that manage the active specification in .specforge.json.
+ */
+export {};
+//# sourceMappingURL=spec-activate.types.js.map

package/dist/cli/commands/spec-activate.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-activate.types.js","sourceRoot":"","sources":["../../../src/cli/commands/spec-activate.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/cli/commands/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/status.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,OAAO,EACL,aAAa,EAad,MAAM,mBAAmB,CAAC;AAsK3B;;GAEG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAkGxE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmC5D"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/status.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,OAAO,EACL,aAAa,EAad,MAAM,mBAAmB,CAAC;AAmO3B;;GAEG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAsIxE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2C5D"}

package/dist/cli/commands/status.js

@@ -6,8 +6,9 @@
  */
 import ora from 'ora';
 import { resolveConfig } from '../config/index.js';
+import { loadProjectConfig, getActiveSpecification } from '../config/loader.js';
 import { withErrorHandler, CliError, NetworkError } from '../middleware/error-handler.js';
-import { printBlank } from '../ui/output.js';
+import { printBlank, printWarning } from '../ui/output.js';
 import { colors } from '../ui/colors.js';
 import { ApiClient } from '../../client/api-client.js';
 import { formatTicketNumber, formatDuration, hasWorkingContext, transformApiResponse, transformToDashboardData, calculateSessionProgress, } from './status.types.js';
@@ -102,6 +103,55 @@ function displayNextActionable(nextActionable) {
         console.log(colors.muted(`  in ${nextActionable.epicTitle}`));
     }
 }
+/**
+ * Build an ASCII progress bar
+ */
+function buildProgressBar(percent, width = 10) {
+    const filled = Math.round((percent / 100) * width);
+    const empty = width - filled;
+    const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(empty);
+    // Color by progress: green >70%, yellow 30-70%, red <30%
+    const colorFn = percent > 70 ? colors.success : percent >= 30 ? colors.warning : colors.error;
+    return colorFn(`[${bar}]`);
+}
+/**
+ * Display Agent Teams progress
+ */
+function displayTeamsProgress(plan) {
+    printBlank();
+    console.log(colors.bold('Agent Teams Progress'));
+    console.log(colors.muted('────────────────────'));
+    if (plan.teams.length === 0) {
+        console.log(colors.muted('No teams configured for this specification.'));
+        return;
+    }
+    // Strategy info
+    console.log(`Strategy: ${colors.primary(plan.strategy)}`);
+    printBlank();
+    // Per-team progress
+    for (const team of plan.teams) {
+        const total = team.tasks.length;
+        // Tasks with no blockers are considered "ready" (approximation of done + ready)
+        const blocked = team.tasks.filter(t => t.blockedBy.length > 0).length;
+        const ready = total - blocked;
+        const percent = total > 0 ? Math.round((ready / total) * 100) : 0;
+        const bar = buildProgressBar(percent);
+        console.log(`  ${colors.bold(team.name)}: ${bar} ${percent}% (${ready}/${total} ready)`);
+        // Show blocked tasks
+        const blockedTasks = team.tasks.filter(t => t.blockedBy.length > 0);
+        for (const task of blockedTasks) {
+            const deps = task.blockedBy.join(', ');
+            console.log(`    ${colors.warning('Blocked')}: ${task.slug} ${colors.muted(`(by ${deps})`)}`);
+        }
+    }
+    // Summary
+    printBlank();
+    const totalTickets = plan.estimatedTotalTickets;
+    const parallelizable = plan.estimatedParallelizableTickets;
+    console.log(`${colors.bold('Total:')} ${totalTickets} tickets, ` +
+        `${parallelizable} parallelizable, ` +
+        `${plan.teams.length} team${plan.teams.length === 1 ? '' : 's'}`);
+}
 /**
  * Display status in console format
  */
@@ -207,6 +257,36 @@ export async function statusAction(options) {
             }
             return;
         }
+        // Teams mode
+        if (options.teams) {
+            // Resolve specification ID
+            const projectConfig = loadProjectConfig();
+            const activeSpec = getActiveSpecification(projectConfig);
+            const specId = activeSpec?.id || config.specificationId;
+            if (!specId) {
+                spinner.stop();
+                printBlank();
+                printWarning("No active specification. Run 'specforge spec activate <id>' to set one.");
+                printBlank();
+                return;
+            }
+            try {
+                const plan = await client.call('get_implementation_plan', { specificationId: specId });
+                spinner.stop();
+                if (options.json) {
+                    console.log(JSON.stringify(plan, null, 2));
+                }
+                else {
+                    displayTeamsProgress(plan);
+                }
+            }
+            catch (teamsError) {
+                spinner.stop();
+                const msg = teamsError instanceof Error ? teamsError.message : 'Unknown error';
+                throw new NetworkError(`Failed to fetch teams progress: ${msg}`);
+            }
+            return;
+        }
         // Transform API response to status
         const status = transformApiResponse(contextResponse, ticketsResponse);
         // Output based on format
@@ -237,6 +317,7 @@ export function registerStatusCommand(program) {
         .command('status')
         .description('Show current working context and session status')
         .option('-d, --dashboard', 'Show full project dashboard with analytics')
+        .option('-t, --teams', 'Show Agent Teams progress')
         .option('--json', 'Output as JSON')
         .option('--toon', 'Output as TOON format')
         .addHelpText('after', `
@@ -244,6 +325,7 @@ Examples:
   $ specforge status              # Show current status
   $ specforge status -d           # Show full dashboard with analytics
   $ specforge status --dashboard  # Show full dashboard with analytics
+  $ specforge status --teams      # Show Agent Teams progress
   $ specforge status --json       # Output as JSON
   $ specforge status --toon       # Output as TOON format
 
@@ -252,6 +334,12 @@ Displays:
   - Implementation Session: Active session status and statistics
   - Next Actionable: Suggested next ticket to work on
 
+Teams View (--teams):
+  - Strategy and team structure
+  - Per-team progress bars with ticket completion
+  - Blocked tickets with dependency reasons
+  - Overall ticket and parallelization summary
+
 Dashboard View (--dashboard):
   - Overall Progress: Ticket completion with progress bar
   - Time Metrics: Estimated, actual, remaining hours and velocity