@syntesseraai/opencode-feature-factory 0.6.20 → 0.7.0

package/command/mini-loop/documentation/run.md

@@ -1,6 +1,6 @@
 ---
 description: Run documentation mini-loop until gate passes
-subtask: true
+subtask: false
 agent: general
 model: openai/gpt-5.4
 loop:
@@ -12,3 +12,5 @@ return:
   - /mini-loop/documentation/gate $RESULT[mini-doc-review]
   - If `MINI_LOOP_DOCUMENTATION_GATE=REWORK`, continue loop with prior documentation review feedback included in the next documentation pass.
 ---
+
+Reply with only: "Documentation phase started"

package/command/mini-loop/implementation/run.md

@@ -1,6 +1,6 @@
 ---
 description: Run implementation mini-loop until gate passes
-subtask: true
+subtask: false
 agent: general
 model: openai/gpt-5.4
 loop:
@@ -12,3 +12,5 @@ return:
   - /mini-loop/implementation/gate $RESULT[mini-impl-review]
   - If `MINI_LOOP_IMPLEMENTATION_GATE=REWORK`, continue loop with prior review feedback included in the next build input.
 ---
+
+Reply with only: "Implementation phase started"

package/command/mini-loop/start.md

@@ -1,9 +1,11 @@
 ---
 description: Mini-loop two-stage workflow entrypoint
-subtask: true
+subtask: false
 agent: general
 model: openai/gpt-5.4
 return:
   - /mini-loop/implementation/run {as:implementation-phase} $ARGUMENTS
   - /mini-loop/documentation/run $RESULT[implementation-phase]
 ---
+
+Reply with only: "Mini-loop started"

package/command/pipeline/building/run.md

@@ -1,6 +1,6 @@
 ---
 description: Run build phase from approved plan
-subtask: true
+subtask: false
 agent: general
 model: openai/gpt-5.4
 return:
@@ -9,3 +9,5 @@ return:
   - /pipeline/building/implement-batch {as:build-implementation} $RESULT[build-batches]
   - /pipeline/reviewing/run {as:review-phase} $RESULT[build-implementation]
 ---
+
+Reply with only: "Building phase started"

package/command/pipeline/documentation/run.md

@@ -1,6 +1,6 @@
 ---
 description: Run documentation loop after review approval
-subtask: true
+subtask: false
 agent: general
 model: openai/gpt-5.4
 loop:
@@ -12,3 +12,5 @@ return:
   - /pipeline/documentation/gate $RESULT[doc-review]
   - If `DOCUMENTATION_GATE=REWORK`, continue loop with review feedback for the next document pass.
 ---
+
+Reply with only: "Documentation phase started"

package/command/pipeline/planning/run.md

@@ -1,6 +1,6 @@
 ---
 description: Execute one planning iteration
-subtask: true
+subtask: false
 agent: general
 model: openai/gpt-5.4
 parallel:
@@ -11,3 +11,5 @@ return:
   - /pipeline/planning/synthesize {as:plan-consensus} $RESULT[plan-opus] $RESULT[plan-gemini] $RESULT[plan-codex]
   - /pipeline/planning/gate $RESULT[plan-consensus]
 ---
+
+Reply with only: "Planning phase started"

package/command/pipeline/reviewing/run.md

@@ -1,6 +1,6 @@
 ---
 description: Run review loop for completed tasks
-subtask: true
+subtask: false
 agent: general
 model: openai/gpt-5.4
 loop:
@@ -17,3 +17,5 @@ return:
   - /pipeline/reviewing/gate $RESULT[review-synthesis]
   - If `REVIEW_GATE=REWORK`, invoke `/pipeline/building/implement-batch` to apply fixes before the next loop iteration.
 ---
+
+Reply with only: "Reviewing phase started"

package/command/pipeline/start.md

@@ -1,6 +1,6 @@
 ---
 description: Pipeline workflow entrypoint
-subtask: true
+subtask: false
 agent: general
 model: openai/gpt-5.4
 return:
@@ -10,3 +10,5 @@ return:
   - /pipeline/documentation/run $RESULT[build-phase]
   - /pipeline/complete
 ---
+
+Reply with only: "Workflow started"

package/dist/command-config.d.ts

@@ -0,0 +1,38 @@
+type BunShell = any;
+/**
+ * Command configuration type matching the OpenCode `command` config schema.
+ */
+export interface CommandConfig {
+    template: string;
+    description?: string;
+    agent?: string;
+    model?: string;
+    subtask?: boolean;
+}
+export interface CommandConfigs {
+    [commandName: string]: CommandConfig;
+}
+/**
+ * Default commands to register in the global OpenCode config.
+ *
+ * "Feature-Factory" is a Socratic entrypoint that guides the user through
+ * clarifying requirements, choosing between pipeline and mini-loop, confirming
+ * model selections, and then invoking the appropriate workflow tool.
+ */
+export declare const DEFAULT_COMMANDS: Record<string, CommandConfig>;
+/**
+ * Merge command configs, preserving existing settings and adding new ones.
+ * Existing command configs take precedence (we never overwrite them).
+ */
+export declare function mergeCommandConfigs(existing: CommandConfigs | undefined, defaults: Record<string, CommandConfig>): CommandConfigs;
+/**
+ * Update the command configuration in global opencode.json.
+ *
+ * This function:
+ * 1. Reads existing config from ~/.config/opencode/opencode.json
+ * 2. Preserves existing command settings
+ * 3. Adds default Feature Factory commands that don't exist yet
+ * 4. Writes updated config back to ~/.config/opencode/opencode.json
+ */
+export declare function updateCommandConfig($: BunShell): Promise<void>;
+export {};

package/dist/command-config.js

@@ -0,0 +1,128 @@
+import { isRecord, updateGlobalOpenCodeConfigBlock } from './opencode-global-config.js';
+/**
+ * Default commands to register in the global OpenCode config.
+ *
+ * "Feature-Factory" is a Socratic entrypoint that guides the user through
+ * clarifying requirements, choosing between pipeline and mini-loop, confirming
+ * model selections, and then invoking the appropriate workflow tool.
+ */
+export const DEFAULT_COMMANDS = {
+    'feature-factory': {
+        description: 'Feature Factory — guided workflow for planning and building features',
+        agent: 'general',
+        subtask: false,
+        template: `You are the Feature Factory workflow assistant. Your job is to guide the user through a structured process before launching either the full pipeline or the mini-loop.
+
+Work through this process step by step. Do NOT skip steps or launch a tool until all steps are complete.
+
+---
+
+## Step 1: Understand the request
+
+The user said: $ARGUMENTS
+
+Work through their request in a Socratic manner:
+- Ask clarifying questions about scope, constraints, and acceptance criteria.
+- Summarise your understanding back to them and ask them to confirm or correct it.
+- Continue until you have a clear, unambiguous set of requirements.
+
+If $ARGUMENTS is empty, ask the user what they would like to build.
+
+---
+
+## Step 2: Choose workflow
+
+Once requirements are agreed, present the two workflow options:
+
+**Pipeline** (full multi-model workflow)
+- Multi-model fan-out planning (3 models propose plans, then consensus synthesis)
+- Build phase with task breakdown and batch validation
+- Multi-model fan-out code review
+- Documentation with review loop
+- Best for: complex features, architectural changes, high-risk work
+
+**Mini-loop** (lightweight workflow)
+- Direct build → review loop (single model per step)
+- Documentation with review loop
+- Best for: small features, bug fixes, incremental improvements, well-understood changes
+
+Ask the user which workflow they prefer. If they are unsure, recommend one based on the complexity of the requirements.
+
+---
+
+## Step 3: Confirm models
+
+Present the default models that will be used for the chosen workflow:
+
+**Pipeline defaults:**
+- Planning fan-out: opus (anthropic/claude-opus-4-6), gemini (opencode/gemini-3.1-pro), codex (openai/gpt-5.3-codex)
+- Review fan-out: same as planning
+- Orchestrator (synthesis/triage): openai/gpt-5.4
+- Build: openai/gpt-5.3-codex
+- Validate: opencode/gemini-3.1-pro
+- Documentation: openai/gpt-5.3-codex
+- Doc review: opencode/gemini-3.1-pro
+
+**Mini-loop defaults:**
+- Build: openai/gpt-5.3-codex
+- Review: openai/gpt-5.4
+- Documentation: openai/gpt-5.3-codex
+- Doc review: opencode/gemini-3.1-pro
+
+Ask: "Would you like to use these default models, or would you like to override any of them?"
+
+If they want to override, collect the provider/model strings for each role they want to change.
+
+---
+
+## Step 4: Launch
+
+Once all three steps are confirmed, call the appropriate tool:
+
+- If they chose **Pipeline**: call the \`ff_pipeline\` tool with the agreed requirements and any model overrides.
+- If they chose **Mini-loop**: call the \`ff_mini_loop\` tool with the agreed requirements and any model overrides.
+
+Pass only the model parameters that were explicitly overridden; omit any that should use defaults.`,
+    },
+};
+/**
+ * Merge command configs, preserving existing settings and adding new ones.
+ * Existing command configs take precedence (we never overwrite them).
+ */
+export function mergeCommandConfigs(existing, defaults) {
+    const existingCommands = existing ?? {};
+    const result = { ...existingCommands };
+    for (const [commandName, commandConfig] of Object.entries(defaults)) {
+        if (!result[commandName]) {
+            result[commandName] = commandConfig;
+        }
+    }
+    return result;
+}
+/**
+ * Update the command configuration in global opencode.json.
+ *
+ * This function:
+ * 1. Reads existing config from ~/.config/opencode/opencode.json
+ * 2. Preserves existing command settings
+ * 3. Adds default Feature Factory commands that don't exist yet
+ * 4. Writes updated config back to ~/.config/opencode/opencode.json
+ */
+export async function updateCommandConfig($) {
+    void $;
+    await updateGlobalOpenCodeConfigBlock({
+        blockName: 'command',
+        warningLabel: 'command config',
+        update: (existingBlock) => {
+            const existingCommandConfigs = isRecord(existingBlock)
+                ? existingBlock
+                : undefined;
+            const updatedCommandConfigs = mergeCommandConfigs(existingCommandConfigs, DEFAULT_COMMANDS);
+            const hasChanges = Object.keys(DEFAULT_COMMANDS).some((commandName) => !existingCommandConfigs?.[commandName]);
+            return {
+                nextBlock: updatedCommandConfigs,
+                changed: hasChanges,
+            };
+        },
+    });
+}

package/dist/index.js

@@ -2,6 +2,8 @@ import { StopQualityGateHooksPlugin } from './stop-quality-gate.js';
 import { updateMCPConfig } from './mcp-config.js';
 import { updateAgentConfig } from './agent-config.js';
 import { updatePluginConfig } from './plugin-config.js';
+import { updateCommandConfig } from './command-config.js';
+import { createWorkflowTools } from './tools/index.js';
 import { $ } from 'bun';
 /**
  * Feature Factory Plugin
@@ -40,10 +42,24 @@ export const FeatureFactoryPlugin = async (input) => {
     catch {
         console.error('Failed to update plugin config in OpenCode plugin');
     }
+    // Update command configuration in global OpenCode config
+    // This registers the Feature-Factory Socratic entrypoint command
+    try {
+        await updateCommandConfig($);
+    }
+    catch {
+        console.error('Failed to update command config in OpenCode plugin');
+    }
     // Load hooks from the quality gate plugin
     const qualityGateHooks = await StopQualityGateHooksPlugin(input).catch(() => ({}));
-    // Tool registry intentionally empty after hard removal of ff-* artifact tools.
-    const tools = {};
+    // Tool registry: workflow tools (ff_pipeline, ff_mini_loop) powered by
+    // the SDK client for programmatic session orchestration.
+    // The old ff-* artifact tools were removed; these replace the subtask2
+    // command-based workflow with TypeScript-driven orchestration.
+    const workflowTools = createWorkflowTools(input.client);
+    // Merge workflow tools with any existing tools from quality gate hooks
+    const existingTools = qualityGateHooks.tool ?? {};
+    const tools = { ...existingTools, ...workflowTools };
     // Return combined hooks and tools
     return {
         ...qualityGateHooks,

package/dist/tools/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tool registry for Feature Factory.
+ *
+ * Exports a function that creates all FF tools given the SDK client.
+ * Only entrypoint tools (pipeline, mini-loop) are exposed to the LLM.
+ * Internal workflow steps are orchestrated programmatically, not as
+ * individually callable tools.
+ */
+import type { ToolDefinition } from '@opencode-ai/plugin/tool';
+import type { Client } from '../workflow/fan-out.js';
+/**
+ * Build the tool map to be merged into the plugin's `Hooks.tool` output.
+ *
+ * @param client - The OpenCode SDK client from PluginInput
+ */
+export declare function createWorkflowTools(client: Client): Record<string, ToolDefinition>;

package/dist/tools/index.js

@@ -0,0 +1,21 @@
+/**
+ * Tool registry for Feature Factory.
+ *
+ * Exports a function that creates all FF tools given the SDK client.
+ * Only entrypoint tools (pipeline, mini-loop) are exposed to the LLM.
+ * Internal workflow steps are orchestrated programmatically, not as
+ * individually callable tools.
+ */
+import { createPipelineTool } from './pipeline.js';
+import { createMiniLoopTool } from './mini-loop.js';
+/**
+ * Build the tool map to be merged into the plugin's `Hooks.tool` output.
+ *
+ * @param client - The OpenCode SDK client from PluginInput
+ */
+export function createWorkflowTools(client) {
+    return {
+        ff_pipeline: createPipelineTool(client),
+        ff_mini_loop: createMiniLoopTool(client),
+    };
+}

package/dist/tools/mini-loop.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ff_mini_loop — Lightweight build → review → document workflow tool.
+ *
+ * A simpler two-stage workflow (no multi-model fan-out for planning).
+ * Implements a build/review loop, then a documentation loop.
+ */
+import { type Client } from '../workflow/orchestrator.js';
+export declare function createMiniLoopTool(client: Client): {
+    description: string;
+    args: {
+        requirements: import("zod").ZodString;
+        build_model: import("zod").ZodOptional<import("zod").ZodString>;
+        review_model: import("zod").ZodOptional<import("zod").ZodString>;
+        doc_model: import("zod").ZodOptional<import("zod").ZodString>;
+        doc_review_model: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        requirements: string;
+        build_model?: string | undefined;
+        review_model?: string | undefined;
+        doc_model?: string | undefined;
+        doc_review_model?: string | undefined;
+    }, context: import("@opencode-ai/plugin/tool").ToolContext): Promise<string>;
+};

package/dist/tools/mini-loop.js

@@ -0,0 +1,133 @@
+/**
+ * ff_mini_loop — Lightweight build → review → document workflow tool.
+ *
+ * A simpler two-stage workflow (no multi-model fan-out for planning).
+ * Implements a build/review loop, then a documentation loop.
+ */
+import { tool } from '@opencode-ai/plugin/tool';
+import { promptSession, evaluateMiniLoopImplGate, evaluateMiniLoopDocGate, BUILD_MODEL, DOC_MODEL, DOC_REVIEW_MODEL, ORCHESTRATOR_MODEL, parseModelString, } from '../workflow/orchestrator.js';
+import { miniBuildPrompt, miniReviewPrompt, documentPrompt, docReviewPrompt } from './prompts.js';
+import { parseMiniReview, parseDocReview } from './parsers.js';
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+export function createMiniLoopTool(client) {
+    return tool({
+        description: 'Run the Feature Factory mini-loop: build → review (with rework loop) → documentation. ' +
+            'Lighter weight than the full pipeline — no multi-model planning phase. ' +
+            'All model parameters are optional and use sensible defaults.',
+        args: {
+            requirements: tool.schema
+                .string()
+                .describe('The feature requirements or task description to implement'),
+            build_model: tool.schema
+                .string()
+                .optional()
+                .describe('provider/model for building and implementation. Defaults to openai/gpt-5.3-codex.'),
+            review_model: tool.schema
+                .string()
+                .optional()
+                .describe('provider/model for implementation review. Defaults to openai/gpt-5.4.'),
+            doc_model: tool.schema
+                .string()
+                .optional()
+                .describe('provider/model for documentation writing. Defaults to the build model.'),
+            doc_review_model: tool.schema
+                .string()
+                .optional()
+                .describe('provider/model for documentation review. Defaults to opencode/gemini-3.1-pro.'),
+        },
+        async execute(args, context) {
+            const sessionId = context.sessionID;
+            const { requirements } = args;
+            // Resolve models — use provided overrides or fall back to defaults
+            const buildModel = args.build_model
+                ? parseModelString(args.build_model)
+                : BUILD_MODEL;
+            const reviewModel = args.review_model
+                ? parseModelString(args.review_model)
+                : ORCHESTRATOR_MODEL;
+            const docModel = args.doc_model
+                ? parseModelString(args.doc_model)
+                : args.build_model
+                    ? buildModel
+                    : DOC_MODEL;
+            const docReviewModel = args.doc_review_model
+                ? parseModelString(args.doc_review_model)
+                : DOC_REVIEW_MODEL;
+            const report = [];
+            const addReport = (phase, msg) => {
+                report.push(`## ${phase}\n${msg}`);
+            };
+            // ===================================================================
+            // PHASE 1: IMPLEMENTATION LOOP (build → review → gate, up to 10)
+            // ===================================================================
+            let implGate = { decision: 'REWORK', feedback: requirements };
+            let lastImplRaw = '';
+            for (let implIter = 0; implIter < 10 && implGate.decision === 'REWORK'; implIter++) {
+                const buildInput = implIter === 0
+                    ? requirements
+                    : `${requirements}\n\nPrevious review feedback:\n${implGate.feedback}`;
+                // Build
+                lastImplRaw = await promptSession(client, sessionId, miniBuildPrompt(buildInput, implIter > 0 ? implGate.feedback : undefined), { model: buildModel, agent: 'building', title: `ff-mini-build-${implIter + 1}` });
+                // Review
+                const reviewRaw = await promptSession(client, sessionId, miniReviewPrompt(lastImplRaw), {
+                    model: reviewModel,
+                    agent: 'reviewing',
+                    title: `ff-mini-review-${implIter + 1}`,
+                });
+                const review = parseMiniReview(reviewRaw);
+                // Gate (deterministic)
+                implGate = evaluateMiniLoopImplGate(review, implIter + 1);
+                if (implGate.decision === 'APPROVED') {
+                    addReport('Implementation', `APPROVED (confidence: ${review.confidence}, iteration: ${implIter + 1})`);
+                }
+                else if (implGate.decision === 'ESCALATE') {
+                    addReport('Implementation', `ESCALATE: ${implGate.reason}`);
+                    return report.join('\n\n');
+                }
+                // REWORK continues the loop
+            }
+            if (implGate.decision !== 'APPROVED') {
+                addReport('Implementation', `REWORK exhausted (10 iterations). Last feedback:\n${implGate.feedback}`);
+                return report.join('\n\n');
+            }
+            // ===================================================================
+            // PHASE 2: DOCUMENTATION LOOP (document → review → gate, up to 5)
+            // ===================================================================
+            let docInput = lastImplRaw;
+            let docGate = { decision: 'REWORK' };
+            for (let docIter = 0; docIter < 5 && docGate.decision === 'REWORK'; docIter++) {
+                // Write docs
+                const docRaw = await promptSession(client, sessionId, documentPrompt(docInput), {
+                    model: docModel,
+                    agent: 'documenting',
+                    title: `ff-mini-doc-write-${docIter + 1}`,
+                });
+                // Review docs
+                const docRevRaw = await promptSession(client, sessionId, docReviewPrompt(docRaw), {
+                    model: docReviewModel,
+                    agent: 'reviewing',
+                    title: `ff-mini-doc-review-${docIter + 1}`,
+                });
+                const docReview = parseDocReview(docRevRaw);
+                // Gate (deterministic)
+                docGate = evaluateMiniLoopDocGate(docReview, docIter + 1);
+                if (docGate.decision === 'APPROVED') {
+                    addReport('Documentation', `APPROVED (confidence: ${docReview.confidence}, iteration: ${docIter + 1})`);
+                }
+                else if (docGate.decision === 'ESCALATE') {
+                    addReport('Documentation', `ESCALATE: ${docGate.reason}`);
+                }
+                else {
+                    docInput = `${docInput}\n\nDocumentation review feedback:\n${docGate.feedback}`;
+                }
+            }
+            // ===================================================================
+            // FINAL REPORT
+            // ===================================================================
+            addReport('Complete', 'Mini-loop finished.');
+            return report.join('\n\n');
+        },
+    });
+}

package/dist/tools/parsers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Response parsers that extract structured data from LLM text output.
+ *
+ * These are intentionally tolerant — they fall back to raw text when
+ * structured sections cannot be found. The gate evaluators work on
+ * the parsed numbers/booleans, not on freeform text.
+ */
+import type { PlanProposal, ConsensusPlan, ReviewReport, ReviewSynthesis, DocReview, ImplementationReport, DocUpdate } from '../workflow/types.js';
+/** Extract the first integer found after a label in the text. */
+export declare function extractNumber(text: string, label: string, fallback?: number): number;
+/** Extract text between two section headers (markdown-style). */
+export declare function extractSection(text: string, heading: string): string;
+/** Check if a YES/NO field is YES. */
+export declare function isYes(text: string, label: string): boolean;
+export declare function parsePlanProposal(tag: string, raw: string): PlanProposal;
+export declare function parseConsensusPlan(raw: string): ConsensusPlan;
+export declare function parseReviewReport(tag: string, raw: string): ReviewReport;
+export declare function parseReviewSynthesis(raw: string): ReviewSynthesis;
+export declare function parseDocUpdate(raw: string): DocUpdate;
+export declare function parseDocReview(raw: string): DocReview;
+export declare function parseImplementationReport(raw: string): ImplementationReport;
+export declare function parseMiniReview(raw: string): {
+    confidence: number;
+    changeRequested: boolean;
+    unresolvedIssues: number;
+    reworkInstructions?: string;
+    raw: string;
+};