@syntesseraai/opencode-feature-factory 0.11.10 → 0.11.12

package/README.md

@@ -90,12 +90,18 @@ Feature Factory agent assets follow OpenCode granular `permissions` blocks (incl
 
 ### Plugin auto-handoff safety net
 
-The plugin includes an auto-handoff hook that continues deterministic next steps by reading explicit machine-readable fields from assistant output and dispatching the extracted prompt as a normal text prompt via `client.session.prompt(...)` while setting the target agent.
+The plugin includes an auto-handoff hook that continues deterministic next steps by reading `RECOMMENDED_NEXT_STEP` from assistant output and dispatching the extracted text as a normal prompt via `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), and handoffs are injected as the next user turn for the targeted agent.
+- On `session.idle`, the hook queries `client.session.messages({ path: { id: sessionId } })`, scans messages in reverse order, and parses only the latest assistant message.
+- The hook extracts the next prompt only from these exact machine-readable formats:
+  - `RECOMMENDED_NEXT_STEP: "<human-readable next step>"`
+  - `RECOMMENDED_NEXT_STEP="<human-readable next step>"`
+
+- If the latest assistant message does not include one of those formats, the hook does nothing.
+- The hook does not buffer streaming assistant chunks and does not enforce a fixed per-session handoff cap.
+- Dispatch is performed through direct API prompt calls (not slash-command execution), and the extracted next-step text is injected as the next user turn to `feature-factory`.
 
 ## Quick Commands
 

package/agents/feature-factory.md

@@ -2,7 +2,7 @@
 description: Feature Factory — native stage orchestrator for planning, building, reviewing, and documenting through sub-agents.
 mode: primary
 color: '#0fc24e'
-model: github-copilot/gpt-5.4-mini
+model: openai/gpt-5.4
 permissions:
   write: deny
   edit: deny
@@ -212,8 +212,8 @@ For each iteration `n`:
 - After the required user confirmation checkpoint, successful Build always proceeds to Document.
 - After the required user confirmation checkpoint, successful Document always proceeds to Review.
 - Build and Document are stage-complete states, not workflow-complete states.
-- Therefore, successful Build and successful Document must emit `AUTO_HANDOFF=YES`.
-- Successful termination with `AUTO_HANDOFF=NO` is allowed only when Review is approved with no further required work (or when blocked/escalated/waiting on required user input).
+- Therefore, successful Build and successful Document must include a deterministic `RECOMMENDED_NEXT_STEP` so continuation can proceed automatically.
+- Omit `RECOMMENDED_NEXT_STEP` only when the workflow is fully complete, blocked, escalated, or waiting on required user input.
 
 ### Direct-execution prohibition
 
@@ -233,40 +233,36 @@ When a workflow ends (success or escalation), return:
 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.
+`RECOMMENDED_NEXT_STEP` should provide the exact next action when deterministic continuation is appropriate.
 
-## Auto-handoff contract (plugin-facing)
+## Plugin continuation contract
 
-When the next step is deterministic and does not require user input, append this exact block at the end of the response:
+When the next step is deterministic and does not require user input, append exactly one of these lines 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
+RECOMMENDED_NEXT_STEP: "<human-readable next step>"
+```
+
+or
+
+```text
+RECOMMENDED_NEXT_STEP="<human-readable next step>"
 ```
 
 Rules:
 
-- After the required user confirmation checkpoint, use `AUTO_HANDOFF=YES` whenever the next workflow step is predetermined by the fixed workflow.
+- After the required user confirmation checkpoint, emit `RECOMMENDED_NEXT_STEP` whenever the next workflow step is predetermined by the fixed workflow.
 - In the fixed workflow, successful Build must always continue to Document.
 - In the fixed workflow, successful Document must always continue to Review.
-- Successful Build and successful Document are stage-complete but not workflow-complete; they must not output `AUTO_HANDOFF=NO`.
-- 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.
-- Use `AUTO_HANDOFF=NO` only when the workflow is fully complete, blocked, escalated, or waiting on required user input.
-- `RECOMMENDED_NEXT_STEP` must match the machine-readable handoff block semantically.
+- Successful Build and successful Document are stage-complete but not workflow-complete; do not omit `RECOMMENDED_NEXT_STEP` for these outcomes.
+- Never emit `RECOMMENDED_NEXT_STEP` before the required user confirmation checkpoint.
+- Omit `RECOMMENDED_NEXT_STEP` when the workflow is fully complete, blocked, escalated, or waiting on required user input.
 - 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`.
 
 Expected mappings:
 
-- Planning approved + user confirmed -> `AUTO_HANDOFF=YES`, `AUTO_HANDOFF_TARGET=feature-factory`, `AUTO_HANDOFF_REASON=CONTINUE_WORKFLOW`
-- Build succeeded -> `AUTO_HANDOFF=YES`, `AUTO_HANDOFF_TARGET=feature-factory`, `AUTO_HANDOFF_REASON=DOCUMENT`
-- Document succeeded -> `AUTO_HANDOFF=YES`, `AUTO_HANDOFF_TARGET=feature-factory`, `AUTO_HANDOFF_REASON=REVIEW`
-- Review requires changes -> `AUTO_HANDOFF=YES`, `AUTO_HANDOFF_TARGET=feature-factory`, `AUTO_HANDOFF_REASON=REWORK`
-- Review approved with no further work -> `AUTO_HANDOFF=NO`
+- Planning approved + user confirmed -> `RECOMMENDED_NEXT_STEP` describes running Build
+- Build succeeded -> `RECOMMENDED_NEXT_STEP` describes running Document
+- Document succeeded -> `RECOMMENDED_NEXT_STEP` describes running Review
+- Review requires changes -> `RECOMMENDED_NEXT_STEP` describes Build rework actions
+- Review approved with no further work -> omit `RECOMMENDED_NEXT_STEP`

package/agents/planning.md

@@ -2,7 +2,7 @@
 description: Creates implementation plans and planning gates for pipeline and ad-hoc work. Uses result-based handoff instead of file artifacts.
 mode: all
 color: '#3b82f6'
-model: openai/gpt-5.4
+model: openai/gpt-5.4-pro
 permissions:
   write: deny
   edit: deny

package/agents/reviewing.md

@@ -118,28 +118,6 @@ 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 normalized, resolved handoff context (summary/status/action items/issues plus resolved prior output excerpts) rather than file-based artifacts.

package/dist/auto-handoff.d.ts

@@ -1,22 +1,10 @@
 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 parseRecommendedNextStep(text: string): string | null;
+export declare function fingerprint(sessionId: string, messageId: string, recommendedNextStep: string): string;
 export declare function getSessionMetadata(client: Client, sessionId: string): Promise<SessionMetadata>;
-export declare const AutoHandoffHooksPlugin: Plugin;
+export declare const RecommendedNextStepHooksPlugin: Plugin;
 export {};

package/dist/auto-handoff.js

@@ -1,9 +1,6 @@
 const SERVICE_NAME = 'feature-factory';
-const MAX_AUTO_HANDOFFS_PER_SESSION = 5;
-const AUTO_HANDOFF_FLAG_RE = /^\s*AUTO_HANDOFF\s*=\s*(YES|NO)\s*$/im;
-const AUTO_HANDOFF_TARGET_RE = /^\s*AUTO_HANDOFF_TARGET\s*=\s*(feature-factory|building|documenting|reviewing)\s*$/im;
-const AUTO_HANDOFF_REASON_RE = /^\s*AUTO_HANDOFF_REASON\s*=\s*(CONTINUE_WORKFLOW|REWORK|DOCUMENT|REVIEW)\s*$/im;
-const AUTO_HANDOFF_PROMPT_RE = /^\s*(?:AUTO_HANDOFF_PROMPT|FF_PROMPT)\s*<<\s*FF_PROMPT\s*\r?\n([\s\S]*?)\r?\n\s*FF_PROMPT\s*$/im;
+const RECOMMENDED_NEXT_STEP_COLON_RE = /^\s*RECOMMENDED_NEXT_STEP\s*:\s*"([^"\r\n]+)"\s*$/im;
+const RECOMMENDED_NEXT_STEP_EQUALS_RE = /^\s*RECOMMENDED_NEXT_STEP\s*=\s*"([^"\r\n]+)"\s*$/im;
 async function log(client, level, message, extra) {
     try {
         await client.app.log({
@@ -19,11 +16,11 @@ async function log(client, level, message, extra) {
         return undefined;
     }
 }
-function extractMessageText(info) {
-    if (!info || typeof info !== 'object') {
+function extractMessageText(message) {
+    if (!message || typeof message !== 'object') {
         return '';
     }
-    const parts = info.parts;
+    const parts = message.parts;
     if (!Array.isArray(parts)) {
         return '';
     }
@@ -37,34 +34,20 @@ function extractMessageText(info) {
     })
         .join('');
 }
-export function parseAutoHandoff(text) {
+export function parseRecommendedNextStep(text) {
     const normalizedText = text.replace(/\r\n/g, '\n');
-    const enabledMatch = normalizedText.match(AUTO_HANDOFF_FLAG_RE);
-    if (!enabledMatch) {
-        return null;
-    }
-    const enabled = enabledMatch[1]?.toUpperCase();
-    if (enabled === 'NO') {
-        return { enabled: false };
+    const colonMatch = normalizedText.match(RECOMMENDED_NEXT_STEP_COLON_RE);
+    if (colonMatch?.[1]) {
+        return colonMatch[1].trim() || null;
     }
-    const targetMatch = normalizedText.match(AUTO_HANDOFF_TARGET_RE);
-    const reasonMatch = normalizedText.match(AUTO_HANDOFF_REASON_RE);
-    const promptMatch = normalizedText.match(AUTO_HANDOFF_PROMPT_RE);
-    const target = targetMatch?.[1]?.toLowerCase();
-    const reason = reasonMatch?.[1]?.toUpperCase();
-    const prompt = promptMatch?.[1]?.trim();
-    if (!target || !reason || !prompt) {
-        return null;
+    const equalsMatch = normalizedText.match(RECOMMENDED_NEXT_STEP_EQUALS_RE);
+    if (equalsMatch?.[1]) {
+        return equalsMatch[1].trim() || null;
     }
-    return {
-        enabled: true,
-        target,
-        reason,
-        prompt,
-    };
+    return null;
 }
-export function fingerprint(sessionId, messageId, handoff) {
-    return [sessionId, messageId, handoff.target, handoff.reason, handoff.prompt].join('::');
+export function fingerprint(sessionId, messageId, recommendedNextStep) {
+    return [sessionId, messageId, recommendedNextStep].join('::');
 }
 export async function getSessionMetadata(client, sessionId) {
     try {
@@ -78,8 +61,34 @@ export async function getSessionMetadata(client, sessionId) {
         return {};
     }
 }
-export const AutoHandoffHooksPlugin = async ({ client }) => {
-    const buffers = new Map();
+async function getLatestAssistantMessage(client, sessionId) {
+    try {
+        const response = await client.session.messages({
+            path: { id: sessionId },
+        });
+        const messages = Array.isArray(response.data) ? response.data : [];
+        for (let index = messages.length - 1; index >= 0; index -= 1) {
+            const current = messages[index];
+            if (!current || typeof current !== 'object') {
+                continue;
+            }
+            const info = current.info;
+            if (!info || info.role !== 'assistant' || !info.id) {
+                continue;
+            }
+            return {
+                messageId: info.id,
+                text: extractMessageText(current),
+            };
+        }
+        return null;
+    }
+    catch {
+        await log(client, 'warn', 'auto-handoff.session-messages-fetch-failed', { sessionId });
+        return null;
+    }
+}
+export const RecommendedNextStepHooksPlugin = async ({ client }) => {
     const sessionState = new Map();
     return {
         event: async ({ event }) => {
@@ -90,89 +99,44 @@ export const AutoHandoffHooksPlugin = async ({ client }) => {
                 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) {
+            const latestAssistantMessage = await getLatestAssistantMessage(client, sessionId);
+            if (!latestAssistantMessage?.text) {
                 return;
             }
-            const parsed = parseAutoHandoff(buffer.text);
-            if (!parsed || !parsed.enabled) {
+            const recommendedNextStep = parseRecommendedNextStep(latestAssistantMessage.text);
+            if (!recommendedNextStep) {
                 return;
             }
             const meta = await getSessionMetadata(client, sessionId);
             const dispatchSessionId = meta.parentID ?? sessionId;
-            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);
+            const state = sessionState.get(sessionId) ?? { fingerprints: new Set() };
+            const key = fingerprint(sessionId, latestAssistantMessage.messageId, recommendedNextStep);
             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,
                 dispatchSessionId,
-                target: parsed.target,
-                reason: parsed.reason,
+                target: 'feature-factory',
             });
             try {
                 await client.session.prompt({
                     path: { id: dispatchSessionId },
                     body: {
-                        agent: parsed.target,
+                        agent: 'feature-factory',
                         parts: [
                             {
                                 type: 'text',
-                                text: parsed.prompt,
+                                text: recommendedNextStep,
                             },
                         ],
                     },
@@ -182,8 +146,7 @@ export const AutoHandoffHooksPlugin = async ({ client }) => {
                 await log(client, 'error', 'auto-handoff.dispatch-failed', {
                     sessionId,
                     dispatchSessionId,
-                    target: parsed.target,
-                    reason: parsed.reason,
+                    target: 'feature-factory',
                     error: String(error),
                 });
             }

package/dist/index.js

@@ -1,5 +1,5 @@
 import { StopQualityGateHooksPlugin } from './stop-quality-gate.js';
-import { AutoHandoffHooksPlugin } from './auto-handoff.js';
+import { RecommendedNextStepHooksPlugin } from './auto-handoff.js';
 import { updateMCPConfig } from './mcp-config.js';
 import { updateAgentConfig } from './agent-config.js';
 import { updatePluginConfig } from './plugin-config.js';
@@ -54,7 +54,7 @@ export const FeatureFactoryPlugin = async (input) => {
     }
     // Load hooks from the quality gate plugin
     const qualityGateHooks = await StopQualityGateHooksPlugin(input).catch(() => ({}));
-    const autoHandoffHooks = await AutoHandoffHooksPlugin(input).catch(() => ({}));
+    const autoHandoffHooks = await RecommendedNextStepHooksPlugin(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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@syntesseraai/opencode-feature-factory",
-  "version": "0.11.10",
+  "version": "0.11.12",
   "type": "module",
   "description": "OpenCode plugin for Feature Factory agents - provides sub-agents and skills for validation, review, security, and architecture assessment",
   "license": "MIT",