@syntesseraai/opencode-feature-factory 0.6.21 → 0.7.1

package/agents/feature-factory.md

@@ -0,0 +1,95 @@
+---
+description: Feature Factory — guided workflow for planning and building features. Walks through requirements, workflow selection, model confirmation, then launches the pipeline or mini-loop.
+mode: primary
+color: '#f59e0b'
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: false
+  skill: true
+  task: true
+  ff_pipeline: true
+  ff_mini_loop: true
+permission:
+  skill:
+    '*': allow
+  task:
+    building: allow
+    reviewing: allow
+    planning: allow
+    documenting: allow
+    ff-research: allow
+    explore: allow
+---
+
+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
+
+Work through the user's 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 the user hasn't provided a request yet, ask them 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.

package/dist/index.js

@@ -2,6 +2,7 @@ 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 { createWorkflowTools } from './tools/index.js';
 import { $ } from 'bun';
 /**
  * Feature Factory Plugin
@@ -42,8 +43,14 @@ export const FeatureFactoryPlugin = async (input) => {
     }
     // 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;
+};

package/dist/tools/parsers.js

@@ -0,0 +1,142 @@
+/**
+ * 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.
+ */
+// ---------------------------------------------------------------------------
+// Generic helpers
+// ---------------------------------------------------------------------------
+/** Extract the first integer found after a label in the text. */
+export function extractNumber(text, label, fallback = 0) {
+    // Try patterns like "CONSENSUS_SCORE: 85", "confidence: 92", "CONFIDENCE=95"
+    const patterns = [
+        new RegExp(`${label}[=:\\s]+([0-9]+)`, 'i'),
+        new RegExp(`${label}[^0-9]*([0-9]+)`, 'i'),
+    ];
+    for (const re of patterns) {
+        const m = text.match(re);
+        if (m)
+            return parseInt(m[1], 10);
+    }
+    return fallback;
+}
+/** Extract text between two section headers (markdown-style). */
+export function extractSection(text, heading) {
+    // Try numbered list style: "1. HEADING" or "## HEADING" or "**HEADING**"
+    const patterns = [
+        new RegExp(`(?:^|\\n)(?:\\d+\\.\\s*)?\\*{0,2}${heading}\\*{0,2}[:\\s]*\\n([\\s\\S]*?)(?=\\n(?:\\d+\\.\\s*)?\\*{0,2}[A-Z_]+|$)`, 'i'),
+        new RegExp(`(?:^|\\n)#{1,3}\\s*${heading}[:\\s]*\\n([\\s\\S]*?)(?=\\n#{1,3}\\s|$)`, 'i'),
+    ];
+    for (const re of patterns) {
+        const m = text.match(re);
+        if (m)
+            return m[1].trim();
+    }
+    return '';
+}
+/** Check if a YES/NO field is YES. */
+export function isYes(text, label) {
+    const m = text.match(new RegExp(`${label}[=:\\s]*(YES|NO)`, 'i'));
+    return m ? m[1].toUpperCase() === 'YES' : false;
+}
+// ---------------------------------------------------------------------------
+// Planning parsers
+// ---------------------------------------------------------------------------
+export function parsePlanProposal(tag, raw) {
+    return {
+        tag,
+        requirementsSummary: extractSection(raw, 'REQUIREMENTS_SUMMARY') || raw.slice(0, 200),
+        architectureValidation: extractSection(raw, 'ARCHITECTURE_VALIDATION'),
+        implementationSteps: extractSection(raw, 'IMPLEMENTATION_STEPS'),
+        risksAndMitigations: extractSection(raw, 'RISKS_AND_MITIGATIONS'),
+        testingStrategy: extractSection(raw, 'TESTING_AND_VALIDATION_STRATEGY'),
+        raw,
+    };
+}
+export function parseConsensusPlan(raw) {
+    return {
+        consensusScore: extractNumber(raw, 'CONSENSUS_SCORE'),
+        agreedElements: extractSection(raw, 'AGREED_ELEMENTS'),
+        divergentElements: extractSection(raw, 'DIVERGENT_ELEMENTS'),
+        synthesizedPlan: extractSection(raw, 'SYNTHESIZED_PLAN'),
+        openQuestions: extractSection(raw, 'OPEN_QUESTIONS'),
+        raw,
+    };
+}
+// ---------------------------------------------------------------------------
+// Review parsers
+// ---------------------------------------------------------------------------
+export function parseReviewReport(tag, raw) {
+    return {
+        tag,
+        findings: raw,
+        confidence: extractNumber(raw, 'confidence'),
+        raw,
+    };
+}
+export function parseReviewSynthesis(raw) {
+    const confidence = extractNumber(raw, 'confidence');
+    const unresolvedIssues = extractNumber(raw, 'unresolved');
+    const verdictMatch = raw.match(/verdict[=:\s]*(APPROVED|REWORK_REQUIRED)/i);
+    const verdict = (verdictMatch?.[1]?.toUpperCase() === 'APPROVED' ? 'APPROVED' : 'REWORK_REQUIRED');
+    const reworkSection = extractSection(raw, 'rework');
+    return {
+        overallConfidence: confidence,
+        consolidatedFindings: raw,
+        unresolvedIssues,
+        verdict,
+        reworkInstructions: reworkSection || undefined,
+        raw,
+    };
+}
+// ---------------------------------------------------------------------------
+// Doc parsers
+// ---------------------------------------------------------------------------
+export function parseDocUpdate(raw) {
+    return {
+        filesChanged: [], // The LLM lists these in the raw text; we keep the raw for the gate
+        rationale: raw,
+        raw,
+    };
+}
+export function parseDocReview(raw) {
+    const confidence = extractNumber(raw, 'confidence');
+    const unresolvedIssues = extractNumber(raw, 'unresolved');
+    const verdictMatch = raw.match(/verdict[=:\s]*(APPROVED|REWORK_REQUIRED)/i);
+    const verdict = (verdictMatch?.[1]?.toUpperCase() === 'APPROVED' ? 'APPROVED' : 'REWORK_REQUIRED');
+    const reworkSection = extractSection(raw, 'rework');
+    return {
+        verdict,
+        unresolvedIssues,
+        confidence,
+        reworkInstructions: reworkSection || undefined,
+        raw,
+    };
+}
+// ---------------------------------------------------------------------------
+// Implementation parsers
+// ---------------------------------------------------------------------------
+export function parseImplementationReport(raw) {
+    return {
+        filesChanged: [],
+        testsRun: [],
+        testsPassed: !raw.toLowerCase().includes('failed'),
+        openIssues: [],
+        raw,
+    };
+}
+// ---------------------------------------------------------------------------
+// Mini-loop review parser
+// ---------------------------------------------------------------------------
+export function parseMiniReview(raw) {
+    return {
+        confidence: extractNumber(raw, 'CONFIDENCE'),
+        changeRequested: isYes(raw, 'CHANGE_REQUESTED'),
+        unresolvedIssues: extractNumber(raw, 'UNRESOLVED_BLOCKING_ISSUES') ||
+            extractNumber(raw, 'UNRESOLVED_DOCUMENTATION_ISSUES'),
+        reworkInstructions: extractSection(raw, 'rework') || undefined,
+        raw,
+    };
+}

package/dist/tools/pipeline.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ff_pipeline — Full plan → build → review → document workflow tool.
+ *
+ * This is an entrypoint tool exposed to the LLM. It orchestrates the
+ * complete Feature Factory pipeline using deterministic control flow
+ * (TypeScript loops and gates) while delegating creative work to
+ * model-specific prompts via the SDK client.
+ */
+import { type Client } from '../workflow/orchestrator.js';
+export declare function createPipelineTool(client: Client): {
+    description: string;
+    args: {
+        requirements: import("zod").ZodString;
+        planning_models: import("zod").ZodOptional<import("zod").ZodString>;
+        review_models: import("zod").ZodOptional<import("zod").ZodString>;
+        orchestrator_model: import("zod").ZodOptional<import("zod").ZodString>;
+        build_model: import("zod").ZodOptional<import("zod").ZodString>;
+        validate_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;
+        planning_models?: string | undefined;
+        review_models?: string | undefined;
+        orchestrator_model?: string | undefined;
+        build_model?: string | undefined;
+        validate_model?: string | undefined;
+        doc_model?: string | undefined;
+        doc_review_model?: string | undefined;
+    }, context: import("@opencode-ai/plugin/tool").ToolContext): Promise<string>;
+};