@syntesseraai/opencode-feature-factory 0.10.13 → 0.10.15

package/AGENTS.md

@@ -5,11 +5,11 @@ This file is installed to `~/.config/opencode/AGENTS.md` by `@syntesseraai/openc
 ## What Feature Factory Provides
 
 - Native workflow orchestration through the `feature-factory` agent.
-- Default orchestrator model: `feature-factory` -> `openai/gpt-5.4`
+- Default orchestrator model: `feature-factory` -> `github-copilot/gpt-5.4-mini`
 - Stage sub-agents with default model routing:
   - `planning` -> `openai/gpt-5.4`
   - `building` -> `openai/gpt-5.3-codex`
-  - `reviewing` -> `opencode/claude-opus-4-6`
+  - `reviewing` -> `opencode/glm-5.1`
   - `documenting` -> `opencode/gemini-3.1-pro`
 - Specialized agents: `feature-factory`, `planning`, `building`, `reviewing`, `documenting`, and `ff-research`.
 - Quick commands: `/ff-review [optional prompt]`, `/ff-document [optional prompt]`, and `/ff-rework [optional prompt]` (all run as subtasks on the relevant stage agent).
@@ -36,7 +36,8 @@ When work changes behavior, workflows, configuration, operational guidance, or r
 
 ## Preferred Tooling Pattern
 
-- Use `morph-mcp_codebase_search` first for semantic codebase discovery.
+- Use codebase-memory MCP graph tools first in stage agents (`codebase-memory-mcp_search_graph`, `codebase-memory-mcp_get_architecture`, `codebase-memory-mcp_trace_call_path`, `codebase-memory-mcp_get_code_snippet`) for discovery, architecture context, and call-path impact analysis.
+- Keep `morph-mcp_codebase_search` as fallback when codebase-memory MCP is unavailable or the repository has not been indexed.
 - Use `read`, `glob`, and `grep` for targeted file inspection.
 - Writable agents should prefer `morph-mcp` `edit_file`, then fallback to native `edit` when needed.
 - Keep `edit` restricted on read-only agents (`planning`, `reviewing`, `ff-research`).

package/README.md

@@ -56,10 +56,10 @@ The plugin no longer exposes `ff_pipeline`, `ff_mini_loop`, or `ff_list_models`
 
 Instead, the `feature-factory` primary agent orchestrates workflows natively by delegating to stage sub-agents:
 
-- `feature-factory` (orchestrator) -> default model `openai/gpt-5.4`
+- `feature-factory` (orchestrator) -> default model `github-copilot/gpt-5.4-mini`
   - `planning` -> default model `openai/gpt-5.4`
   - `building` -> default model `openai/gpt-5.3-codex`
-  - `reviewing` -> default model `opencode/claude-opus-4-6`
+  - `reviewing` -> default model `opencode/glm-5.1`
   - `documenting` -> default model `opencode/gemini-3.1-pro`
 
 ### Fixed execution path
@@ -76,6 +76,17 @@ Each transition carries forward prior-stage context (summary, gate/verdict, acti
 
 Writable stage agents (`building`, `documenting`) prefer Morph MCP `edit_file` and can fallback to native `edit` (and `write` for new files) when needed. Read-only agents keep `edit` disabled.
 
+Stage-agent code discovery is graph-first: planning/building/reviewing/documenting prefer codebase-memory MCP tools (`codebase-memory-mcp_search_graph`, `codebase-memory-mcp_get_architecture`, `codebase-memory-mcp_trace_call_path`, `codebase-memory-mcp_get_code_snippet`) before semantic warp_grep/warpgrep-style fallbacks.
+
+### Plugin auto-handoff safety net
+
+The plugin now includes an auto-handoff hook that can continue deterministic next steps by reading explicit machine-readable fields from assistant output and dispatching `client.session.prompt(...)`.
+
+- The orchestrator (`@feature-factory`) remains the source of truth for workflow progression.
+- Auto-handoff is a continuation safety net, not a replacement for orchestrator logic.
+- Multi-stage continuation should target `feature-factory`; one-stage follow-up can target a stage agent.
+- Dispatch is performed through direct API prompt calls (not slash-command execution).
+
 ## Quick Commands
 
 The plugin installs global custom slash commands in `~/.config/opencode/commands/`:
@@ -83,14 +94,17 @@ The plugin installs global custom slash commands in `~/.config/opencode/commands
 - `/ff-review [optional prompt]`
   - Agent: `reviewing`
   - Subtask: `true` (always runs as a subtask)
+  - Mode: manual standalone helper (does not continue the full pipeline automatically)
   - Default prompt when no argument is provided: `Review the changes so far`
 - `/ff-document [optional prompt]`
   - Agent: `documenting`
   - Subtask: `true` (always runs as a subtask)
+  - Mode: manual standalone helper (does not continue the full pipeline automatically)
   - Default prompt when no argument is provided: `Document all the changes so far`
 - `/ff-rework [optional prompt]`
   - Agent: `building`
   - Subtask: `true` (always runs as a subtask)
+  - Mode: manual standalone helper (does not continue the full pipeline automatically)
   - Default prompt when no argument is provided: `apply the rework recommendations`
 
 Examples:
@@ -111,6 +125,8 @@ The plugin merges the following MCP servers into global OpenCode config when mis
 - `context7`
 - `morph-mcp`
 
+`codebase-memory-mcp` is currently treated as an optional prerequisite (not auto-provisioned by this plugin) because it commonly requires repository-specific indexing/setup. Stage agents still include morph semantic fallback guidance when codebase-memory MCP is unavailable.
+
 `morph-mcp` is configured as:
 
 ```json

package/agents/building.md

@@ -11,6 +11,11 @@ tools:
   bash: true
   skill: true
   task: true
+  'codebase-memory-mcp_search_graph': true
+  'codebase-memory-mcp_get_architecture': true
+  'codebase-memory-mcp_trace_call_path': true
+  'codebase-memory-mcp_get_code_snippet': true
+  'codebase-memory-mcp_search_code': true
   'morph-mcp_codebase_search': true
 permission:
   skill:
@@ -43,29 +48,38 @@ You are the building specialist.
 
 ## Editing Workflow (Required)
 
-Prefer Morph MCP `edit_file` for all implementation edits.
+Prefer the OpenCode `edit_file` tool (Fast Apply) for all implementation edits.
+
+Fallback policy:
+
+- **Codex models:** use `patch` or `apply_patch`.
+- **Non-Codex models:** use `edit`.
+- **New files (all models):** `write` or `patch` are acceptable.
 
 1. **Read before editing** to confirm current behavior and scope.
 2. **Apply changes with `edit_file`** for targeted replacements/insertions whenever available.
 3. **Re-read after edits** to verify the applied diff and avoid stale assumptions.
-4. If `edit_file` is unavailable or cannot express the required change, fallback to `edit`.
-5. Use `write` when creating brand-new files.
+4. If `edit_file` is unavailable or cannot express the required change, choose fallback by model family: Codex → `patch`/`apply_patch`; non-Codex → `edit`.
+5. For brand-new files, use `write` or `patch`.
 
 ## Semantic Code Search
 
-Use `morph-mcp_codebase_search` for semantic code search when you need to:
+Use codebase-memory MCP tools first for semantic/structural code search when you need to:
 
-- Find implementations by meaning, not just text matching (e.g., "authentication logic", "database connection handling")
-- Locate related code without knowing exact names or keywords
-- Understand how features work across the codebase
+- Find implementations by meaning with `codebase-memory-mcp_search_graph`
+- Understand package/service boundaries via `codebase-memory-mcp_get_architecture`
+- Trace caller/callee impact with `codebase-memory-mcp_trace_call_path`
+- Read exact source around graph hits with `codebase-memory-mcp_get_code_snippet`
 
-Prefer this over `grep` when searching by concept rather than exact text.
+Prefer this over warp_grep/warpgrep-style search because graph context reduces false positives and improves dependency-aware edits.
 
 Search fallback order:
 
-1. `morph-mcp_codebase_search` for semantic discovery.
-2. `read` to inspect exact implementation details before editing.
-3. `grep` for exact symbol/literal checks when needed.
+1. `codebase-memory-mcp_search_graph` + `codebase-memory-mcp_get_architecture` for discovery.
+2. `codebase-memory-mcp_trace_call_path` / `codebase-memory-mcp_get_code_snippet` for impact and code verification.
+3. `morph-mcp_codebase_search` if codebase-memory MCP is unavailable or unindexed.
+4. `read` to inspect exact implementation details before editing.
+5. `grep` for exact symbol/literal checks when needed.
 
 ## GitHub Workflow Guidance
 

package/agents/documenting.md

@@ -11,6 +11,11 @@ tools:
   bash: false
   skill: true
   task: true
+  'codebase-memory-mcp_search_graph': true
+  'codebase-memory-mcp_get_architecture': true
+  'codebase-memory-mcp_trace_call_path': true
+  'codebase-memory-mcp_get_code_snippet': true
+  'codebase-memory-mcp_search_code': true
   'morph-mcp_codebase_search': true
 permission:
   skill:
@@ -47,25 +52,38 @@ Always load `ff-documentation-rules` before scoping or editing documentation. Tr
 
 ## Editing Workflow (Required)
 
-Prefer Morph MCP `edit_file` for documentation updates.
+Prefer the OpenCode `edit_file` tool (Fast Apply) for documentation updates.
+
+Fallback policy:
+
+- **Codex models:** use `patch` or `apply_patch`.
+- **Non-Codex models:** use `edit`.
+- **New files (all models):** `write` or `patch` are acceptable.
 
 1. **Read the current navigation chain first** — inspect the root `README.md`, `docs/INDEX.md`, relevant nested `docs/**/INDEX.md` files, and affected leaf docs before editing.
 2. **Verify behavior from code** — use semantic search and targeted reads so the documentation matches what actually ships.
 3. **Update canonical docs and navigation together** — change the affected leaf docs, every impacted `INDEX.md`, and the root `README.md` when primary documentation entry points or doc structure change.
 4. **Apply changes with `edit_file`** for precise doc updates whenever available.
 5. **Re-read after edits** to validate wording, relative links, and cross-doc consistency.
-6. If `edit_file` is unavailable or cannot express the required change, fallback to `edit`.
-7. Use `write` when creating brand-new documentation files.
+6. If `edit_file` is unavailable or cannot express the required change, choose fallback by model family: Codex → `patch`/`apply_patch`; non-Codex → `edit`.
+7. For brand-new documentation files, use `write` or `patch`.
 
 ## Semantic Code Search
 
-Use `morph-mcp_codebase_search` to understand how code actually works before documenting it. Search by meaning (e.g., "how are users authenticated", "error handling middleware") rather than exact text.
+Use codebase-memory MCP tools first to understand how code actually works before documenting it.
+
+- `codebase-memory-mcp_search_graph` to locate relevant functions/classes/routes
+- `codebase-memory-mcp_get_architecture` to capture subsystem context accurately
+- `codebase-memory-mcp_trace_call_path` for workflow and dependency narratives
+- `codebase-memory-mcp_get_code_snippet` to verify exact behavior before writing docs
 
 Search fallback order:
 
-1. `morph-mcp_codebase_search` for semantic discovery.
-2. `read` to verify exact behavior before writing docs.
-3. `grep` for exact symbol/literal checks when needed.
+1. `codebase-memory-mcp_search_graph` + `codebase-memory-mcp_get_architecture` for graph-first discovery.
+2. `codebase-memory-mcp_trace_call_path` / `codebase-memory-mcp_get_code_snippet` for behavior confirmation.
+3. `morph-mcp_codebase_search` if codebase-memory MCP is unavailable or the repo is not indexed.
+4. `read` to verify exact behavior before writing docs.
+5. `grep` for exact symbol/literal checks when needed.
 
 ## GitHub Workflow Guidance
 

package/agents/feature-factory.md

@@ -191,6 +191,13 @@ For each iteration `n`:
 7. If either gate is not `APPROVED`, route back to Build with consolidated action items from both review outputs.
 8. If 10 iterations are exhausted, stop and escalate to the user.
 
+### Autonomous continuation rule
+
+- After the required user confirmation checkpoint is satisfied, do not pause between required stages.
+- Do not ask the user what to do next while required workflow stages remain unfinished.
+- Do not use optional phrasing like "If you want, I can..." for unfinished required workflow steps.
+- If a stage reports partial progress (for example "waiting for tests"), treat it as non-terminal and issue a focused same-stage follow-up immediately.
+
 ### Direct-execution prohibition
 
 - Do not substitute manual/orchestrator-only answers for work that should be performed by stage agents.
@@ -208,3 +215,30 @@ When a workflow ends (success or escalation), return:
 4. `TEST_RESULTS` (if reported)
 5. `OPEN_ISSUES`
 6. `RECOMMENDED_NEXT_STEP`
+
+`RECOMMENDED_NEXT_STEP` is reserved for true end-of-workflow recommendations only; do not use it to defer unfinished required stages.
+
+## Auto-handoff contract (plugin-facing)
+
+When the next step is deterministic and does not require user input, append this exact block at the end of the response:
+
+```text
+RECOMMENDED_NEXT_STEP=<ACTION> "<human-readable next step>"
+
+AUTO_HANDOFF=YES|NO
+AUTO_HANDOFF_TARGET=feature-factory|building|documenting|reviewing
+AUTO_HANDOFF_REASON=CONTINUE_WORKFLOW|REWORK|DOCUMENT|REVIEW
+AUTO_HANDOFF_PROMPT<<FF_PROMPT
+<exact prompt text for next turn>
+FF_PROMPT
+```
+
+Rules:
+
+- Use `AUTO_HANDOFF=YES` only when the next step is deterministic and should run automatically.
+- Use `AUTO_HANDOFF_TARGET=feature-factory` when the workflow should continue across multiple stages.
+- Use stage targets (`building`, `documenting`, `reviewing`) only for focused one-stage follow-up.
+- Never use `AUTO_HANDOFF=YES` before the required user confirmation checkpoint.
+- If complete, blocked, escalated, or waiting on the user, output `AUTO_HANDOFF=NO`.
+- `RECOMMENDED_NEXT_STEP` must match the machine-readable handoff block semantically.
+- For normal workflow progression, continue by delegating to stage agents directly (`@building`, `@documenting`, `@reviewing`), not by invoking slash commands such as `/ff-review`, `/ff-document`, or `/ff-rework`.

package/agents/ff-research.md

@@ -9,6 +9,11 @@ tools:
   bash: false
   skill: true
   task: false
+  'codebase-memory-mcp_search_graph': true
+  'codebase-memory-mcp_get_architecture': true
+  'codebase-memory-mcp_trace_call_path': true
+  'codebase-memory-mcp_get_code_snippet': true
+  'codebase-memory-mcp_search_code': true
   'morph-mcp_codebase_search': true
   'morph-mcp_github_codebase_search': true
 permission:
@@ -53,13 +58,19 @@ You have access to powerful external research tools. **Use them proactively:**
 
 ### Semantic Code Search
 
-- **`morph-mcp_codebase_search`** — Search the local codebase by meaning. Use to understand the project's existing patterns before recommending changes.
+- **`codebase-memory-mcp_search_graph`** — Graph-first local discovery for functions/classes/routes and their relationships.
+- **`codebase-memory-mcp_get_architecture`** — High-level package/service map for architectural context.
+- **`codebase-memory-mcp_trace_call_path`** — Call-chain tracing for impact analysis and behavior verification.
+- **`codebase-memory-mcp_get_code_snippet`** — Read exact symbol source after graph discovery.
+- **`morph-mcp_codebase_search`** — Semantic local fallback when graph indexing is unavailable.
 
 Search fallback order for code understanding:
 
-1. `morph-mcp_codebase_search` for semantic discovery in local code.
-2. `morph-mcp_github_codebase_search` for upstream/public GitHub internals when needed.
-3. `gh_grep_searchGitHub` for exact code pattern matching across public repos.
+1. `codebase-memory-mcp_search_graph` + `codebase-memory-mcp_get_architecture` for local graph-first discovery.
+2. `codebase-memory-mcp_trace_call_path` / `codebase-memory-mcp_get_code_snippet` for local behavior verification.
+3. `morph-mcp_codebase_search` for local semantic fallback when graph search is unavailable.
+4. `morph-mcp_github_codebase_search` for upstream/public GitHub internals when needed.
+5. `gh_grep_searchGitHub` for exact code pattern matching across public repos.
 
 ## GitHub Workflow Guidance
 

package/agents/planning.md

@@ -10,6 +10,11 @@ tools:
   bash: false
   skill: true
   task: true
+  'codebase-memory-mcp_search_graph': true
+  'codebase-memory-mcp_get_architecture': true
+  'codebase-memory-mcp_trace_call_path': true
+  'codebase-memory-mcp_get_code_snippet': true
+  'codebase-memory-mcp_search_code': true
   'morph-mcp_codebase_search': true
 permission:
   skill:
@@ -40,19 +45,22 @@ You are a read-only agent — you do not write or edit files.
 
 ## Semantic Code Search
 
-Use `morph-mcp_codebase_search` for semantic code search when planning:
+Use codebase-memory MCP tools first when planning:
 
-- Understand existing architecture by meaning (e.g., "authentication logic", "API routing")
-- Find related implementations before proposing changes
-- Verify assumptions about how code works
+- `codebase-memory-mcp_search_graph` to find candidate functions, classes, and routes
+- `codebase-memory-mcp_get_architecture` for package/service-level orientation
+- `codebase-memory-mcp_trace_call_path` for dependency and impact analysis
+- `codebase-memory-mcp_get_code_snippet` to inspect exact implementation context
 
-Prefer this over `grep` when searching by concept rather than exact text.
+This is preferred over warp_grep/warpgrep-style semantic discovery because graph-aware results surface structural context directly.
 
 Search fallback order:
 
-1. `morph-mcp_codebase_search` for semantic discovery.
-2. `read` to verify relevant source context.
-3. `grep` for exact symbol/literal checks when needed.
+1. `codebase-memory-mcp_search_graph` + `codebase-memory-mcp_get_architecture` for graph-first discovery.
+2. `codebase-memory-mcp_trace_call_path` / `codebase-memory-mcp_get_code_snippet` for call-flow and source verification.
+3. `morph-mcp_codebase_search` if codebase-memory MCP is unavailable or the repository is not indexed yet.
+4. `read` to verify relevant source context.
+5. `grep` for exact symbol/literal checks when needed.
 
 ## GitHub Workflow Guidance
 

package/agents/reviewing.md

@@ -2,7 +2,7 @@
 description: Unified validation agent for code and documentation. Performs acceptance, quality, security, and architecture review with context-driven scope.
 mode: primary
 color: '#8b5cf6'
-model: opencode/claude-opus-4-6
+model: opencode/glm-5.1
 tools:
   read: true
   write: false
@@ -10,6 +10,11 @@ tools:
   bash: false
   skill: true
   task: true
+  'codebase-memory-mcp_search_graph': true
+  'codebase-memory-mcp_get_architecture': true
+  'codebase-memory-mcp_trace_call_path': true
+  'codebase-memory-mcp_get_code_snippet': true
+  'codebase-memory-mcp_search_code': true
   'morph-mcp_codebase_search': true
 permission:
   skill:
@@ -40,19 +45,22 @@ You are a read-only agent — you do not write or edit files.
 
 ## Semantic Code Search
 
-Use `morph-mcp_codebase_search` for semantic code search when reviewing:
+Use codebase-memory MCP tools first when reviewing:
 
-- Search by meaning to find related code (e.g., "input validation", "access control checks")
-- Verify that implementations match architectural patterns across the codebase
-- Find similar code to check for consistency
+- `codebase-memory-mcp_search_graph` to locate related implementations by structure + name pattern
+- `codebase-memory-mcp_get_architecture` to validate subsystem boundaries and coupling
+- `codebase-memory-mcp_trace_call_path` to verify security/validation coverage across call paths
+- `codebase-memory-mcp_get_code_snippet` to inspect concrete evidence for findings
 
-Prefer this over `grep` when searching by concept rather than exact text.
+Prefer this over warp_grep/warpgrep-style search so findings are anchored to graph-aware dependencies, not isolated text matches.
 
 Search fallback order:
 
-1. `morph-mcp_codebase_search` for semantic discovery.
-2. `read` to verify concrete evidence and line references.
-3. `grep` for exact symbol/literal checks when needed.
+1. `codebase-memory-mcp_search_graph` + `codebase-memory-mcp_get_architecture` for discovery and context.
+2. `codebase-memory-mcp_trace_call_path` / `codebase-memory-mcp_get_code_snippet` for evidence collection.
+3. `morph-mcp_codebase_search` if codebase-memory MCP is unavailable or not indexed.
+4. `read` to verify concrete evidence and line references.
+5. `grep` for exact symbol/literal checks when needed.
 
 ## GitHub Workflow Guidance
 
@@ -96,6 +104,28 @@ When acting as gate reviewer, output status line exactly:
 - `REVIEW_GATE=APPROVED|REWORK|ESCALATE`
 - `DOCUMENTATION_GATE=APPROVED|REWORK|ESCALATE`
 
+## Auto-handoff output contract (for standalone review runs)
+
+When a standalone review clearly requires rework and the next action is deterministic, append:
+
+```text
+RECOMMENDED_NEXT_STEP=REWORK "<specific rework summary>"
+AUTO_HANDOFF=YES
+AUTO_HANDOFF_TARGET=building
+AUTO_HANDOFF_REASON=REWORK
+AUTO_HANDOFF_PROMPT<<FF_PROMPT
+apply the rework recommendations
+
+- <specific action item>
+FF_PROMPT
+```
+
+Otherwise emit:
+
+```text
+AUTO_HANDOFF=NO
+```
+
 ## Operating Mode
 
 - Use result-based handoff (`$RESULT[...]`) rather than file-based artifacts.

package/dist/auto-handoff.d.ts

@@ -0,0 +1,22 @@
+import { type Plugin, type PluginInput } from '@opencode-ai/plugin';
+type AutoHandoffTarget = 'feature-factory' | 'building' | 'documenting' | 'reviewing';
+type AutoHandoffReason = 'CONTINUE_WORKFLOW' | 'REWORK' | 'DOCUMENT' | 'REVIEW';
+export type ParsedAutoHandoff = {
+    enabled: false;
+} | {
+    enabled: true;
+    target: AutoHandoffTarget;
+    reason: AutoHandoffReason;
+    prompt: string;
+};
+type Client = PluginInput['client'];
+type SessionMetadata = {
+    parentID?: string;
+};
+export declare function parseAutoHandoff(text: string): ParsedAutoHandoff | null;
+export declare function fingerprint(sessionId: string, messageId: string, handoff: Extract<ParsedAutoHandoff, {
+    enabled: true;
+}>): string;
+export declare function getSessionMetadata(client: Client, sessionId: string): Promise<SessionMetadata>;
+export declare const AutoHandoffHooksPlugin: Plugin;
+export {};

package/dist/auto-handoff.js

@@ -0,0 +1,195 @@
+const SERVICE_NAME = 'feature-factory';
+const MAX_AUTO_HANDOFFS_PER_SESSION = 5;
+const AUTO_HANDOFF_FLAG_RE = /^AUTO_HANDOFF=(YES|NO)$/m;
+const AUTO_HANDOFF_TARGET_RE = /^AUTO_HANDOFF_TARGET=(feature-factory|building|documenting|reviewing)$/m;
+const AUTO_HANDOFF_REASON_RE = /^AUTO_HANDOFF_REASON=(CONTINUE_WORKFLOW|REWORK|DOCUMENT|REVIEW)$/m;
+const AUTO_HANDOFF_PROMPT_RE = /AUTO_HANDOFF_PROMPT<<FF_PROMPT\r?\n([\s\S]*?)\r?\nFF_PROMPT/m;
+async function log(client, level, message, extra) {
+    try {
+        await client.app.log({
+            body: {
+                service: SERVICE_NAME,
+                level,
+                message,
+                extra,
+            },
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractMessageText(info) {
+    if (!info || typeof info !== 'object') {
+        return '';
+    }
+    const parts = info.parts;
+    if (!Array.isArray(parts)) {
+        return '';
+    }
+    return parts
+        .map((part) => {
+        if (!part || typeof part !== 'object') {
+            return '';
+        }
+        const typedPart = part;
+        return typedPart.type === 'text' && typeof typedPart.text === 'string' ? typedPart.text : '';
+    })
+        .join('');
+}
+export function parseAutoHandoff(text) {
+    const enabledMatch = text.match(AUTO_HANDOFF_FLAG_RE);
+    if (!enabledMatch) {
+        return null;
+    }
+    const enabled = enabledMatch[1];
+    if (enabled === 'NO') {
+        return { enabled: false };
+    }
+    const targetMatch = text.match(AUTO_HANDOFF_TARGET_RE);
+    const reasonMatch = text.match(AUTO_HANDOFF_REASON_RE);
+    const promptMatch = text.match(AUTO_HANDOFF_PROMPT_RE);
+    const target = targetMatch?.[1];
+    const reason = reasonMatch?.[1];
+    const prompt = promptMatch?.[1]?.trim();
+    if (!target || !reason || !prompt) {
+        return null;
+    }
+    return {
+        enabled: true,
+        target: target,
+        reason: reason,
+        prompt,
+    };
+}
+export function fingerprint(sessionId, messageId, handoff) {
+    return [sessionId, messageId, handoff.target, handoff.reason, handoff.prompt].join('::');
+}
+export async function getSessionMetadata(client, sessionId) {
+    try {
+        const response = await client.session.get({ path: { id: sessionId } });
+        return {
+            parentID: response.data?.parentID,
+        };
+    }
+    catch {
+        await log(client, 'warn', 'auto-handoff.session-metadata-fetch-failed', { sessionId });
+        return {};
+    }
+}
+export const AutoHandoffHooksPlugin = async ({ client }) => {
+    const buffers = new Map();
+    const sessionState = new Map();
+    return {
+        event: async ({ event }) => {
+            const properties = event
+                .properties;
+            const sessionId = properties?.sessionID ?? properties?.sessionId;
+            if (!sessionId) {
+                return;
+            }
+            if (event.type === 'session.deleted') {
+                buffers.delete(sessionId);
+                sessionState.delete(sessionId);
+                return;
+            }
+            if (event.type === 'message.updated') {
+                const info = event
+                    .properties?.info;
+                if (!info || info.role !== 'assistant' || !info.id) {
+                    return;
+                }
+                buffers.set(sessionId, {
+                    messageId: info.id,
+                    text: extractMessageText(info),
+                });
+                return;
+            }
+            if (event.type === 'message.part.updated') {
+                const state = buffers.get(sessionId);
+                if (!state) {
+                    return;
+                }
+                const props = event.properties;
+                const part = props?.part;
+                if (part?.type !== 'text') {
+                    return;
+                }
+                if (typeof props?.delta === 'string') {
+                    state.text += props.delta;
+                }
+                else if (typeof part.text === 'string') {
+                    state.text = part.text;
+                }
+                buffers.set(sessionId, state);
+                return;
+            }
+            if (event.type !== 'session.idle') {
+                return;
+            }
+            const buffer = buffers.get(sessionId);
+            if (!buffer?.text) {
+                return;
+            }
+            const parsed = parseAutoHandoff(buffer.text);
+            if (!parsed || !parsed.enabled) {
+                return;
+            }
+            const meta = await getSessionMetadata(client, sessionId);
+            if (meta.parentID) {
+                await log(client, 'debug', 'auto-handoff.skipped-sub-agent-session', {
+                    sessionId,
+                    parentID: meta.parentID,
+                });
+                return;
+            }
+            const state = sessionState.get(sessionId) ?? {
+                count: 0,
+                fingerprints: new Set(),
+            };
+            if (state.count >= MAX_AUTO_HANDOFFS_PER_SESSION) {
+                await log(client, 'warn', 'auto-handoff.skipped-cap-reached', {
+                    sessionId,
+                    max: MAX_AUTO_HANDOFFS_PER_SESSION,
+                });
+                sessionState.set(sessionId, state);
+                return;
+            }
+            const key = fingerprint(sessionId, buffer.messageId, parsed);
+            if (state.fingerprints.has(key)) {
+                await log(client, 'debug', 'auto-handoff.skipped-duplicate', { sessionId });
+                return;
+            }
+            state.fingerprints.add(key);
+            state.count += 1;
+            sessionState.set(sessionId, state);
+            await log(client, 'info', 'auto-handoff.dispatching', {
+                sessionId,
+                target: parsed.target,
+                reason: parsed.reason,
+            });
+            try {
+                await client.session.prompt({
+                    path: { id: sessionId },
+                    body: {
+                        agent: parsed.target,
+                        parts: [
+                            {
+                                type: 'text',
+                                text: parsed.prompt,
+                            },
+                        ],
+                    },
+                });
+            }
+            catch (error) {
+                await log(client, 'error', 'auto-handoff.dispatch-failed', {
+                    sessionId,
+                    target: parsed.target,
+                    reason: parsed.reason,
+                    error: String(error),
+                });
+            }
+        },
+    };
+};

package/dist/index.js

@@ -1,8 +1,20 @@
 import { StopQualityGateHooksPlugin } from './stop-quality-gate.js';
+import { AutoHandoffHooksPlugin } from './auto-handoff.js';
 import { updateMCPConfig } from './mcp-config.js';
 import { updateAgentConfig } from './agent-config.js';
 import { updatePluginConfig } from './plugin-config.js';
 import { $ } from 'bun';
+function composeAsyncHandlers(...handlers) {
+    const activeHandlers = handlers.filter((handler) => Boolean(handler));
+    if (activeHandlers.length === 0) {
+        return undefined;
+    }
+    return (async (...args) => {
+        for (const handler of activeHandlers) {
+            await handler(...args);
+        }
+    });
+}
 /**
  * Feature Factory Plugin
  *
@@ -42,10 +54,13 @@ export const FeatureFactoryPlugin = async (input) => {
     }
     // Load hooks from the quality gate plugin
     const qualityGateHooks = await StopQualityGateHooksPlugin(input).catch(() => ({}));
+    const autoHandoffHooks = await AutoHandoffHooksPlugin(input).catch(() => ({}));
     // Feature Factory orchestration now runs via native sub-agent handoff in
     // the feature-factory agent prompt (LLM-driven workflow). ff_* workflow MCP
     // tools are no longer registered from this plugin.
     return {
-        ...qualityGateHooks,
+        event: composeAsyncHandlers(qualityGateHooks.event, autoHandoffHooks.event),
+        'tool.execute.before': composeAsyncHandlers(qualityGateHooks['tool.execute.before'], autoHandoffHooks['tool.execute.before']),
+        'tool.execute.after': composeAsyncHandlers(qualityGateHooks['tool.execute.after'], autoHandoffHooks['tool.execute.after']),
     };
 };

package/dist/mcp-config.d.ts

@@ -2,6 +2,10 @@ type BunShell = any;
 /**
  * Default MCP server configuration to be added by the plugin
  * These servers will be merged into the global OpenCode config.
+ *
+ * Note: codebase-memory-mcp is intentionally not auto-provisioned here.
+ * It is treated as an optional prerequisite because it commonly needs
+ * repository-specific indexing/setup before graph queries are useful.
  */
 export declare const DEFAULT_MCP_SERVERS: {
     readonly 'jina-ai': {

package/dist/mcp-config.js

@@ -2,6 +2,10 @@ import { isRecord, updateGlobalOpenCodeConfigBlock } from './opencode-global-con
 /**
  * Default MCP server configuration to be added by the plugin
  * These servers will be merged into the global OpenCode config.
+ *
+ * Note: codebase-memory-mcp is intentionally not auto-provisioned here.
+ * It is treated as an optional prerequisite because it commonly needs
+ * repository-specific indexing/setup before graph queries are useful.
  */
 export const DEFAULT_MCP_SERVERS = {
     'jina-ai': {

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@syntesseraai/opencode-feature-factory",
-  "version": "0.10.13",
+  "version": "0.10.15",
   "type": "module",
   "description": "OpenCode plugin for Feature Factory agents - provides sub-agents and skills for validation, review, security, and architecture assessment",
   "license": "MIT",
@@ -34,9 +34,7 @@
   ],
   "scripts": {},
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "@opencode-ai/plugin": "^1.1.48",
-    "glob": "^10.0.0"
+    "@opencode-ai/plugin": "^1.1.48"
   },
   "devDependencies": {
     "@types/bun": "^1.2.6",