edsger 0.72.6 → 0.74.0

package/dist/phases/features/index.js

@@ -0,0 +1,292 @@
+/**
+ * Features phase: clone EVERY repository linked to the product
+ * (product_repositories), ask Claude to catalogue the user-facing features
+ * the product delivers, and persist them via the product_features table.
+ *
+ * Multi-repo: unlike recipes (single primary repo), features are discovered
+ * across the whole product. Repo resolution + cloning is shared with the
+ * diagram phases (cloneDiagramRepos): each repo is cloned into its own
+ * subdirectory of a per-product parent dir, and the agent runs in the
+ * parent so it can explore all of them in one pass.
+ *
+ * Production-grade behaviours layered on top of the basic agent loop
+ * (mirrors the recipes phase):
+ *
+ *   - Heartbeat: `last_heartbeat_at` on the feature_scans row is refreshed
+ *     on every assistant message so the reader can detect stalled / crashed
+ *     runs (see desktop-app/.../services/db/feature-scans.ts for the lazy
+ *     reaper).
+ *   - Cancellation-safe writes: markRunning / markSuccess / markFailed only
+ *     touch rows whose status is in {pending, running}. If the user clicked
+ *     Stop and the row is now 'cancelled', the final write no-ops.
+ *   - Per-call MCP writes: agent commits each create / update / remove as
+ *     it goes. There is no "submit at the end" buffer — partial progress
+ *     survives even if the agent later errors out.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { getSupabase } from '../../supabase/client.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cleanupIssueRepo } from '../../workspace/workspace-manager.js';
+import { cloneDiagramRepos, safeDirName, } from '../diagram-shared/clone-repos.js';
+import { fetchProductBasics } from '../find-shared/mcp.js';
+import { createPromptGenerator, extractTextFromContent, } from '../pr-shared/agent-utils.js';
+import { createFeaturesMcpServer, createFeaturesMutationCounts, } from './mcp-server.js';
+import { createFeaturesSystemPrompt, createFeaturesUserPrompt, } from './prompts.js';
+const WORKSPACE_KEY = 'features';
+const MAX_TURNS = 200;
+// Heartbeat cadence: at most one DB write per HEARTBEAT_MIN_INTERVAL_MS.
+// Triggered on every assistant message so a stalled agent (no messages
+// flowing) lets the row go stale and the reader can mark it failed.
+const HEARTBEAT_MIN_INTERVAL_MS = 15_000;
+/**
+ * Repo-scope note for the agent's user prompt. Unlike the diagram phases'
+ * describeRepoScope (which asks for one unified flow), this tells the agent
+ * the exact full names it may use in the `repos` field of each feature.
+ */
+export function describeFeatureRepoScope(repos) {
+    if (repos.length === 1) {
+        return `The working directory is a clone of \`${repos[0].fullName}\`. Use that full name in the \`repos\` field.`;
+    }
+    const list = repos.map((r) => `- ${r.fullName} (subdirectory: ${safeDirName(r.fullName)})`);
+    return [
+        `This product spans ${repos.length} repositories, each cloned into its own subdirectory of the working directory:`,
+        ...list,
+        'Explore all of them. A feature implemented across several repositories is ONE feature listing every repo it touches in `repos` — do not duplicate it per repo.',
+    ].join('\n');
+}
+export async function runFeaturesPhase(options) {
+    const { productId, scanId, guidance, verbose } = options;
+    logInfo(`Starting features scan for product ${productId}`);
+    const supabase = getSupabase();
+    const claimed = await markRunning(supabase, scanId);
+    if (!claimed) {
+        return {
+            status: 'cancelled',
+            message: 'Feature scan row is no longer in a runnable state (likely cancelled before the CLI started)',
+        };
+    }
+    let cleanupDir;
+    let succeeded = false;
+    try {
+        // Every repo linked to the product, in stored order. cloneDiagramRepos
+        // falls back to the product's primary repo when the list is empty
+        // (older single-repo products with no product_repositories rows).
+        const repositoryIds = await listProductRepositoryIds(supabase, productId);
+        const cloned = await cloneDiagramRepos({
+            productId,
+            repositoryIds,
+            workspaceKey: WORKSPACE_KEY,
+            verbose,
+        });
+        if (!cloned.ok) {
+            await markFailed(supabase, scanId, cloned.message);
+            return { status: 'error', message: cloned.message };
+        }
+        ;
+        ({ cleanupDir } = cloned);
+        const [basics, scanMeta, existingFeatures] = await Promise.all([
+            fetchProductBasics(productId),
+            getScanCreator(supabase, scanId),
+            listProductFeatures(supabase, productId),
+        ]);
+        if (!scanMeta) {
+            const msg = 'feature_scans row vanished mid-run; aborting';
+            await markFailed(supabase, scanId, msg);
+            return { status: 'error', message: msg };
+        }
+        const systemPrompt = createFeaturesSystemPrompt();
+        const userPrompt = createFeaturesUserPrompt({
+            productName: basics.name,
+            productDescription: basics.description,
+            guidance,
+            existingFeatures,
+            repoScopeNote: describeFeatureRepoScope(cloned.repos),
+        });
+        const counts = createFeaturesMutationCounts();
+        const mcpServer = createFeaturesMcpServer({
+            supabase,
+            productId,
+            createdBy: scanMeta.created_by,
+        }, counts, existingFeatures);
+        logInfo(`Running Claude agent to identify features across ${cloned.repos.length} repo(s)...`);
+        let lastHeartbeatAt = 0;
+        for await (const message of query({
+            prompt: createPromptGenerator(userPrompt),
+            options: {
+                systemPrompt: {
+                    type: 'preset',
+                    preset: 'claude_code',
+                    append: systemPrompt,
+                },
+                model: DEFAULT_MODEL,
+                maxTurns: MAX_TURNS,
+                permissionMode: 'bypassPermissions',
+                cwd: cloned.projectDir,
+                mcpServers: {
+                    features: mcpServer,
+                },
+            },
+        })) {
+            if (message.type === 'assistant') {
+                extractTextFromContent(message.message?.content ?? [], verbose);
+                const now = Date.now();
+                if (now - lastHeartbeatAt >= HEARTBEAT_MIN_INTERVAL_MS) {
+                    lastHeartbeatAt = now;
+                    await heartbeat(supabase, scanId);
+                }
+                continue;
+            }
+            if (message.type !== 'result') {
+                continue;
+            }
+            if (message.subtype !== 'success') {
+                const msg = `Features scan failed: agent ${message.subtype}`;
+                const written = await markFailed(supabase, scanId, msg);
+                return {
+                    status: written ? 'error' : 'cancelled',
+                    message: written
+                        ? msg
+                        : 'Scan was cancelled while the agent was running',
+                    counts,
+                };
+            }
+            const written = await markSuccess(supabase, scanId);
+            if (!written) {
+                return {
+                    status: 'cancelled',
+                    message: 'Scan was cancelled before the result could be written',
+                    counts,
+                };
+            }
+            succeeded = true;
+            const summary = `created ${counts.created}, updated ${counts.updated}, removed ${counts.removed}`;
+            logSuccess(`Features scan complete — ${summary}`);
+            return {
+                status: 'success',
+                message: `Features scan complete (${summary})`,
+                counts,
+            };
+        }
+        const msg = 'Features scan ended without a result message';
+        await markFailed(supabase, scanId, msg);
+        return { status: 'error', message: msg, counts };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`Features scan failed: ${errorMessage}`);
+        await markFailed(supabase, scanId, errorMessage);
+        return { status: 'error', message: errorMessage };
+    }
+    finally {
+        if (succeeded) {
+            cleanupIssueRepo(cleanupDir);
+        }
+    }
+}
+// ============================================================================
+// DB helpers — exported for unit tests
+// ============================================================================
+export async function listProductRepositoryIds(supabase, productId) {
+    const { data, error } = await supabase
+        .from('product_repositories')
+        .select('repository_id, position')
+        .eq('product_id', productId)
+        .order('position', { ascending: true });
+    if (error || !data) {
+        return [];
+    }
+    return data.map((r) => r.repository_id);
+}
+export async function getScanCreator(supabase, scanId) {
+    const { data, error } = await supabase
+        .from('feature_scans')
+        .select('created_by')
+        .eq('id', scanId)
+        .maybeSingle();
+    if (error || !data) {
+        return null;
+    }
+    return data;
+}
+export async function listProductFeatures(supabase, productId) {
+    const { data, error } = await supabase
+        .from('product_features')
+        .select('id, name, description, status, source')
+        .eq('product_id', productId)
+        .order('created_at', { ascending: true });
+    if (error || !data) {
+        return [];
+    }
+    return data;
+}
+/**
+ * Claim the row by flipping `pending` → `running`. Returns true on success
+ * (we won the claim) and false when the row has already moved on (e.g. user
+ * cancelled before the CLI started). Bounded by the status filter so we
+ * can't accidentally resurrect a 'cancelled' row.
+ */
+export async function markRunning(supabase, scanId) {
+    const { data, error } = await supabase
+        .from('feature_scans')
+        .update({
+        status: 'running',
+        error: null,
+        last_heartbeat_at: new Date().toISOString(),
+    })
+        .eq('id', scanId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark scan as running: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+export async function heartbeat(supabase, scanId) {
+    const { error } = await supabase
+        .from('feature_scans')
+        .update({ last_heartbeat_at: new Date().toISOString() })
+        .eq('id', scanId)
+        .eq('status', 'running');
+    if (error) {
+        logWarning(`Heartbeat failed: ${error.message}`);
+    }
+}
+export async function markFailed(supabase, scanId, errorMessage) {
+    const { data, error } = await supabase
+        .from('feature_scans')
+        .update({
+        status: 'failed',
+        error: errorMessage,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', scanId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark scan as failed: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}
+export async function markSuccess(supabase, scanId) {
+    const { data, error } = await supabase
+        .from('feature_scans')
+        .update({
+        status: 'success',
+        error: null,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', scanId)
+        .in('status', ['pending', 'running'])
+        .select('id')
+        .maybeSingle();
+    if (error) {
+        logWarning(`Could not mark scan as success: ${error.message}`);
+        return false;
+    }
+    return data !== null;
+}

package/dist/phases/features/mcp-server.d.ts

@@ -0,0 +1,61 @@
+/**
+ * In-process MCP server exposing the features toolkit. Three tools:
+ *
+ *   - create_feature   INSERT a product_features row (source = 'agent')
+ *   - update_feature   UPDATE an existing row (enrichment, latest-wins on
+ *                      the fields passed)
+ *   - remove_feature   DELETE a previously agent-discovered row the agent
+ *                      confirmed is no longer present (manual rows are
+ *                      never deletable from a scan)
+ *
+ * All writes are scoped to the active feature_scan's product_id. The
+ * handlers persist directly via the Supabase client passed in by the
+ * orchestrator — there is no captured-extraction buffer to flush at the
+ * end. Each tool call is its own committed effect.
+ */
+import type { SupabaseClient } from '@supabase/supabase-js';
+import { z } from 'zod';
+import { type FeatureSummary } from './types.js';
+export interface FeaturesToolContext {
+    supabase: SupabaseClient;
+    productId: string;
+    createdBy: string;
+}
+/**
+ * Records how many of each kind of mutation the agent made — exported so the
+ * orchestrator can print a summary line at the end of the scan.
+ */
+export interface FeaturesMutationCounts {
+    created: number;
+    updated: number;
+    removed: number;
+}
+export declare function createFeaturesMutationCounts(): FeaturesMutationCounts;
+export declare function createCreateFeatureTool(ctx: FeaturesToolContext, counts: FeaturesMutationCounts, knownFeatures: Map<string, FeatureSummary>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    name: z.ZodString;
+    description: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<{
+        shipped: "shipped";
+        deprecated: "deprecated";
+        planned: "planned";
+        in_development: "in_development";
+    }>>;
+    repos: z.ZodArray<z.ZodString>;
+    evidence: z.ZodString;
+}>;
+export declare function createUpdateFeatureTool(ctx: FeaturesToolContext, counts: FeaturesMutationCounts, knownFeatures: Map<string, FeatureSummary>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    feature_id: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        shipped: "shipped";
+        deprecated: "deprecated";
+        planned: "planned";
+        in_development: "in_development";
+    }>>;
+    repos: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    evidence: z.ZodOptional<z.ZodString>;
+}>;
+export declare function createRemoveFeatureTool(ctx: FeaturesToolContext, counts: FeaturesMutationCounts, knownFeatures: Map<string, FeatureSummary>): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    feature_id: z.ZodString;
+}>;
+export declare function createFeaturesMcpServer(ctx: FeaturesToolContext, counts: FeaturesMutationCounts, existingFeatures: FeatureSummary[]): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/phases/features/mcp-server.js

@@ -0,0 +1,165 @@
+/**
+ * In-process MCP server exposing the features toolkit. Three tools:
+ *
+ *   - create_feature   INSERT a product_features row (source = 'agent')
+ *   - update_feature   UPDATE an existing row (enrichment, latest-wins on
+ *                      the fields passed)
+ *   - remove_feature   DELETE a previously agent-discovered row the agent
+ *                      confirmed is no longer present (manual rows are
+ *                      never deletable from a scan)
+ *
+ * All writes are scoped to the active feature_scan's product_id. The
+ * handlers persist directly via the Supabase client passed in by the
+ * orchestrator — there is no captured-extraction buffer to flush at the
+ * end. Each tool call is its own committed effect.
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { FEATURE_DESCRIPTION_MAX, FEATURE_EVIDENCE_MAX, FEATURE_NAME_MAX, FEATURE_REPO_NAME_MAX, FEATURE_REPOS_MAX, } from './types.js';
+export function createFeaturesMutationCounts() {
+    return { created: 0, updated: 0, removed: 0 };
+}
+const statusSchema = z
+    .enum(['planned', 'in_development', 'shipped', 'deprecated'])
+    .describe('Lifecycle status as evidenced by the code. Default "shipped"; use "in_development" for half-wired / flag-gated code.');
+const reposSchema = z
+    .array(z.string().min(1).max(FEATURE_REPO_NAME_MAX))
+    .max(FEATURE_REPOS_MAX)
+    .describe('Repository full names ("owner/repo") where the feature is implemented. Only names from the repository list you were given.');
+function normalizeRepos(repos) {
+    const cleaned = repos.map((r) => r.trim()).filter((r) => r.length > 0);
+    return Array.from(new Set(cleaned)).sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+}
+function textError(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+function textOk(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+    };
+}
+export function createCreateFeatureTool(ctx, counts, knownFeatures) {
+    return tool('create_feature', 'Register a feature that is not in the existing list for this product. Pass a short user-facing name, a 1-3 sentence description, the repos it lives in, and evidence (file paths / entry points).', {
+        name: z.string().min(1).max(FEATURE_NAME_MAX),
+        description: z.string().min(1).max(FEATURE_DESCRIPTION_MAX),
+        status: statusSchema.optional(),
+        repos: reposSchema,
+        evidence: z
+            .string()
+            .min(1)
+            .max(FEATURE_EVIDENCE_MAX)
+            .describe('Plain-text paragraph saying where in the code this feature shows up (file paths, routes, entry points).'),
+    }, async (args) => {
+        const name = args.name.trim();
+        const duplicate = [...knownFeatures.values()].find((f) => f.name.toLowerCase() === name.toLowerCase());
+        if (duplicate) {
+            return textError(`A feature named "${duplicate.name}" already exists (id=${duplicate.id}). Use update_feature instead.`);
+        }
+        const { data, error } = await ctx.supabase
+            .from('product_features')
+            .insert({
+            product_id: ctx.productId,
+            name,
+            description: args.description.trim(),
+            status: args.status ?? 'shipped',
+            source: 'agent',
+            repos: normalizeRepos(args.repos),
+            evidence: args.evidence.trim(),
+            created_by: ctx.createdBy,
+        })
+            .select('id')
+            .single();
+        if (error || !data) {
+            return textError(`Failed to create feature: ${error?.message ?? 'unknown error'}`);
+        }
+        knownFeatures.set(data.id, {
+            id: data.id,
+            name,
+            description: args.description.trim(),
+            status: args.status ?? 'shipped',
+            source: 'agent',
+        });
+        counts.created += 1;
+        return textOk(`Created feature ${data.id} ("${name}").`);
+    });
+}
+export function createUpdateFeatureTool(ctx, counts, knownFeatures) {
+    return tool('update_feature', "Enrich an existing feature you corroborated in the code: evidence, repos, corrected status, or a better description. Omit fields you do not want to change. For source=manual entries only add evidence/repos/status or fill a missing description — never rewrite the user's intent.", {
+        feature_id: z.string().uuid().describe('id from the existing list'),
+        description: z.string().min(1).max(FEATURE_DESCRIPTION_MAX).optional(),
+        status: statusSchema.optional(),
+        repos: reposSchema.optional(),
+        evidence: z.string().min(1).max(FEATURE_EVIDENCE_MAX).optional(),
+    }, async (args) => {
+        const known = knownFeatures.get(args.feature_id);
+        if (!known) {
+            return textError(`feature_id ${args.feature_id} is not in this product's feature list. Use create_feature for new entries.`);
+        }
+        const patch = {};
+        if (args.description !== undefined) {
+            patch.description = args.description.trim();
+        }
+        if (args.status !== undefined) {
+            patch.status = args.status;
+        }
+        if (args.repos !== undefined) {
+            patch.repos = normalizeRepos(args.repos);
+        }
+        if (args.evidence !== undefined) {
+            patch.evidence = args.evidence.trim();
+        }
+        if (Object.keys(patch).length === 0) {
+            return textError('Nothing to update — pass at least one field.');
+        }
+        const { error } = await ctx.supabase
+            .from('product_features')
+            .update(patch)
+            .eq('id', args.feature_id)
+            .eq('product_id', ctx.productId);
+        if (error) {
+            return textError(`Failed to update feature: ${error.message}`);
+        }
+        counts.updated += 1;
+        return textOk(`Updated feature ${args.feature_id} ("${known.name}").`);
+    });
+}
+export function createRemoveFeatureTool(ctx, counts, knownFeatures) {
+    return tool('remove_feature', 'Delete a previously agent-discovered feature (source=agent) that you have confirmed is NO LONGER present in the code. Manually defined features cannot be removed by a scan.', {
+        feature_id: z.string().uuid(),
+    }, async (args) => {
+        const known = knownFeatures.get(args.feature_id);
+        if (!known) {
+            return textError(`feature_id ${args.feature_id} is not in this product's feature list — nothing to remove.`);
+        }
+        if (known.source !== 'agent') {
+            return textError(`Feature ${args.feature_id} ("${known.name}") was defined manually and cannot be removed by a scan. If it looks wrong, leave it for the user.`);
+        }
+        const { error } = await ctx.supabase
+            .from('product_features')
+            .delete()
+            .eq('id', args.feature_id)
+            .eq('product_id', ctx.productId)
+            .eq('source', 'agent');
+        if (error) {
+            return textError(`Failed to remove feature: ${error.message}`);
+        }
+        knownFeatures.delete(args.feature_id);
+        counts.removed += 1;
+        return textOk(`Removed feature ${args.feature_id} ("${known.name}").`);
+    });
+}
+export function createFeaturesMcpServer(ctx, counts, existingFeatures) {
+    const knownFeatures = new Map(existingFeatures.map((f) => [f.id, f]));
+    return createSdkMcpServer({
+        name: 'features',
+        version: '1.0.0',
+        tools: [
+            createCreateFeatureTool(ctx, counts, knownFeatures),
+            createUpdateFeatureTool(ctx, counts, knownFeatures),
+            createRemoveFeatureTool(ctx, counts, knownFeatures),
+        ],
+    });
+}

package/dist/phases/features/prompts.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Prompts for the features phase.
+ *
+ * Agent's job: explore the cloned repositories of a product (one or several
+ * — multi-repo products are cloned side by side as subdirectories of the
+ * working directory) and catalogue the user-facing FEATURES the product
+ * delivers. A feature is the WHAT from the user's perspective ("Export
+ * board as PDF", "Slack notifications", "SSO login"), not the HOW (that is
+ * what recipes capture) and not a tech-stack inventory.
+ *
+ * The agent is fed the product's existing features (manual + previously
+ * discovered) and must, for each feature it identifies, pick one of:
+ *   - update_feature — an existing entry matches; enrich it with evidence /
+ *                      repos / corrected status
+ *   - create_feature — nothing matches; new entry (source = 'agent')
+ *   - remove_feature — a previously agent-discovered entry can no longer be
+ *                      corroborated in the code (manual entries are never
+ *                      removed)
+ *
+ * Submission is via MCP tool calls only — no fenced JSON.
+ */
+import type { FeatureSummary } from './types.js';
+export interface FeaturesPromptContext {
+    productName: string;
+    productDescription?: string;
+    guidance?: string;
+    existingFeatures: FeatureSummary[];
+    /** Multi-repo note from describeRepoScope(); empty for single-repo. */
+    repoScopeNote: string;
+}
+export declare function createFeaturesSystemPrompt(): string;
+export declare function createFeaturesUserPrompt(ctx: FeaturesPromptContext): string;

package/dist/phases/features/prompts.js

@@ -0,0 +1,92 @@
+/**
+ * Prompts for the features phase.
+ *
+ * Agent's job: explore the cloned repositories of a product (one or several
+ * — multi-repo products are cloned side by side as subdirectories of the
+ * working directory) and catalogue the user-facing FEATURES the product
+ * delivers. A feature is the WHAT from the user's perspective ("Export
+ * board as PDF", "Slack notifications", "SSO login"), not the HOW (that is
+ * what recipes capture) and not a tech-stack inventory.
+ *
+ * The agent is fed the product's existing features (manual + previously
+ * discovered) and must, for each feature it identifies, pick one of:
+ *   - update_feature — an existing entry matches; enrich it with evidence /
+ *                      repos / corrected status
+ *   - create_feature — nothing matches; new entry (source = 'agent')
+ *   - remove_feature — a previously agent-discovered entry can no longer be
+ *                      corroborated in the code (manual entries are never
+ *                      removed)
+ *
+ * Submission is via MCP tool calls only — no fenced JSON.
+ */
+export function createFeaturesSystemPrompt() {
+    return `You are a senior product manager with a staff-engineer's eye, cataloguing the FEATURES a product delivers by reading its source code.
+
+The current working directory contains a fresh clone of the product's repository (or, for multi-repo products, one subdirectory per repository). Use Glob/Grep/Read (and Bash for git log when helpful) to explore before writing anything.
+
+## What is a "feature"?
+
+A feature is ONE user-facing capability, named from the user's point of view. It answers "what can a user do with this product?", not "how is it built?".
+
+Good feature names: "Export board as PDF", "Slack notifications", "Single sign-on (SAML)", "Real-time collaborative editing", "Usage-based billing".
+Bad feature names: "React frontend", "Postgres database", "REST API", "Utils module" (implementation details, not user value).
+
+Keep names short (a few words, Title-style), and the description 1–3 sentences in plain product language: what the user gets, plus any notable scope/limits you can see in the code.
+
+## Output protocol
+
+The MCP server exposes these tools — use them, do NOT paste content as fenced code:
+
+1. \`create_feature({ name, description, status?, repos, evidence })\` — register a feature that is not in the existing list. \`status\` defaults to "shipped"; use "in_development" when the code is clearly behind an unfinished flag or half-wired.
+
+2. \`update_feature({ feature_id, description?, status?, repos?, evidence? })\` — enrich an existing entry you corroborated in the code. Omit fields you don't want to change.
+
+3. \`remove_feature({ feature_id })\` — drop a previously agent-discovered entry you could NOT corroborate anywhere in the code. Only entries marked source=agent can be removed; manually defined features are never deleted by a scan.
+
+Call exactly one of create / update for each feature you identify, then remove for any stale agent entries. When you are done, end your turn — no summary message, no JSON dump.
+
+## Rules
+
+- \`repos\` is the list of repository full names ("owner/repo") where the feature is implemented — only use names from the repository list you were given.
+- \`evidence\` is one short plain-text paragraph pointing at where the feature lives: key file paths, routes, entry points. For multi-repo products prefix paths with the repo subdirectory.
+- Aim for the level of granularity a changelog or pricing page would use. Don't list every API endpoint as its own feature, and don't collapse the whole product into one feature. Most products have 5–30 features.
+- Don't invent features. If you can't point at concrete code, don't record it.
+- Existing entries: match by meaning, not exact name. If an existing feature (manual or agent) covers what you found, \`update_feature\` it instead of creating a near-duplicate.
+- Manual entries (source=manual) are the user's own definitions: never rewrite their intent. You may add \`evidence\` / \`repos\`, correct an obviously wrong \`status\`, or fill in a missing description — nothing more.`;
+}
+export function createFeaturesUserPrompt(ctx) {
+    const lines = [];
+    lines.push(`# Product: ${ctx.productName}`);
+    if (ctx.productDescription) {
+        lines.push('');
+        lines.push('## Description');
+        lines.push(ctx.productDescription);
+    }
+    if (ctx.repoScopeNote) {
+        lines.push('');
+        lines.push('## Repositories');
+        lines.push(ctx.repoScopeNote);
+    }
+    if (ctx.guidance && ctx.guidance.trim()) {
+        lines.push('');
+        lines.push('## Reviewer guidance (focus or exclusions)');
+        lines.push(ctx.guidance.trim());
+    }
+    lines.push('');
+    lines.push('## Existing features for this product');
+    if (ctx.existingFeatures.length === 0) {
+        lines.push('(none — every feature you identify will be a `create_feature`.)');
+    }
+    else {
+        lines.push('Prefer `update_feature` over `create_feature` when one of these matches what you found. Entries marked source=manual were written by a human — enrich, never rewrite.');
+        lines.push('');
+        for (const f of ctx.existingFeatures) {
+            const desc = f.description ? ` — ${f.description}` : '';
+            lines.push(`- id=${f.id} "${f.name}" [status=${f.status}, source=${f.source}]${desc}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Task');
+    lines.push('Explore the cloned repositories, identify every user-facing feature the product delivers, and for each call exactly one of `create_feature` / `update_feature`. Then call `remove_feature` for any previously agent-discovered entry you could not corroborate. End your turn when done.');
+    return lines.join('\n');
+}

package/dist/phases/features/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shapes the features MCP tools accept and return. The Zod schemas live in
+ * mcp-server.ts; these plain TS types are what the rest of the phase
+ * (orchestrator, persistence helpers, tests) consumes so they don't have
+ * to inflate Zod into their dependency graph.
+ */
+export type FeatureStatus = 'planned' | 'in_development' | 'shipped' | 'deprecated';
+export type FeatureSource = 'manual' | 'agent';
+export interface FeatureSummary {
+    id: string;
+    name: string;
+    description: string | null;
+    status: FeatureStatus;
+    source: FeatureSource;
+}
+export interface CreateFeatureArgs {
+    name: string;
+    description: string;
+    status?: FeatureStatus;
+    repos: string[];
+    evidence: string;
+}
+export interface UpdateFeatureArgs {
+    featureId: string;
+    description?: string;
+    status?: FeatureStatus;
+    repos?: string[];
+    evidence?: string;
+}
+export declare const FEATURE_NAME_MAX = 200;
+export declare const FEATURE_DESCRIPTION_MAX = 10000;
+export declare const FEATURE_EVIDENCE_MAX = 4000;
+export declare const FEATURE_REPOS_MAX = 20;
+export declare const FEATURE_REPO_NAME_MAX = 200;