@syntesseraai/opencode-feature-factory 0.7.3 → 0.9.0

package/README.md

@@ -56,6 +56,20 @@ These colors are intentionally unique to avoid collisions in OpenCode agent UIs
 - Coordinator and synthesis model defaults to ChatGPT 5.4 via frontmatter `model:` declarations in orchestrator commands.
 - All orchestrator commands include an explicit **orchestrator constraint**: they must NOT directly read, edit, modify, write, or create any code/config/repository files — they only dispatch sub-commands, pass structured data via `{as:name}` / `$RESULT[name]`, and evaluate gate/loop conditions.
 
+## Tools
+
+The plugin exposes three MCP tools via the `feature-factory` agent:
+
+| Tool | Description |
+|------|-------------|
+| `ff_pipeline` | Full multi-model pipeline: planning → build → review → documentation. Uses hardcoded per-role model defaults (see Model Routing below). |
+| `ff_mini_loop` | Lightweight build → review → documentation loop. **Does not hardcode model defaults** — all roles inherit the current session model when omitted. |
+| `ff_list_models` | Read-only discovery tool. Queries the OpenCode SDK to list all available providers, models, capability badges, connected status, and defaults. |
+
+### Mini-Loop Model Inheritance
+
+When `ff_mini_loop` model parameters are omitted, child sessions inherit the parent session's model (the SDK `model` field is omitted entirely from the prompt body). The `doc_model` has a cascade: if `build_model` is explicitly set but `doc_model` is not, the documentation step uses the same model as build. Users can call `ff_list_models` to discover available `provider/model` strings before overriding.
+
 ## Command Tree
 
 - `/pipeline/start`

package/agents/building.md

@@ -7,6 +7,7 @@ tools:
   write: true
   edit: true
   bash: true
+  hashline_edit: true
   skill: true
   task: true
 permission:
@@ -33,6 +34,29 @@ You are the building specialist.
 - Do not rely on intermediate artifact files for pipeline progression.
 - Persist only when explicitly requested by the user.
 
+## Hashline Workflow (Required)
+
+File reads and edits use hashline-annotated tools. The `read` tool returns lines annotated with `#HL <line>:<hash>|<content>` and a `#HL REV:<hash>` header. Follow this workflow:
+
+1. **Always `read` before editing.** Note the `REV` value from the `#HL REV:<hash>` header — you need it for edits.
+2. **Use `hashline_edit`** for targeted, hash-referenced edits. Operations: `replace`, `delete`, `insert_before`, `insert_after`. Example:
+   ```json
+   { "path": "src/app.ts", "operation": "replace", "startRef": "5:a3f", "replacement": "const value = 2", "fileRev": "72c4946c" }
+   ```
+3. **Use built-in `edit`/`write`** for standard edits — hashline prefixes are automatically stripped before the tool executes.
+4. **After any edit/write**, re-read the file to get fresh refs before further edits.
+
+Never fabricate refs — always use exactly the refs returned by `read`.
+
+## Semantic Code Search
+
+Use `cocoindex-code_search` for semantic 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
+
+Prefer this over `grep` when searching by concept rather than exact text.
+
 ## Execution Rules
 
 1. Implement task batches in dependency order.

package/agents/documenting.md

@@ -6,7 +6,8 @@ tools:
   read: true
   write: true
   edit: true
-  bash: true
+  bash: false
+  hashline_edit: true
   skill: true
   task: true
 permission:
@@ -25,6 +26,24 @@ You are the documenting specialist.
 - Keep docs concise, consistent, and free of stale references.
 - Return a structured summary for documentation review.
 
+## Hashline Workflow (Required)
+
+File reads and edits use hashline-annotated tools. The `read` tool returns lines annotated with `#HL <line>:<hash>|<content>` and a `#HL REV:<hash>` header. Follow this workflow:
+
+1. **Always `read` before editing.** Note the `REV` value — you need it for edits.
+2. **Use `hashline_edit`** for targeted, hash-referenced edits. Operations: `replace`, `delete`, `insert_before`, `insert_after`. Example:
+   ```json
+   { "path": "docs/FILE.md", "operation": "replace", "startRef": "5:a3f", "replacement": "Updated text", "fileRev": "72c4946c" }
+   ```
+3. **Use built-in `edit`/`write`** for standard edits — hashline prefixes are automatically stripped.
+4. **After any edit/write**, re-read the file to get fresh refs before further edits.
+
+Never fabricate refs — always use exactly the refs returned by `read`.
+
+## Semantic Code Search
+
+Use `cocoindex-code_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.
+
 ## Rules
 
 1. Do not change product behavior while editing docs.

package/agents/feature-factory.md

@@ -7,10 +7,12 @@ tools:
   write: false
   edit: false
   bash: false
+  hashline_edit: false
   skill: true
   task: true
   ff_pipeline: true
   ff_mini_loop: true
+  ff_list_models: true
 permission:
   skill:
     '*': allow
@@ -27,6 +29,12 @@ You are the Feature Factory workflow assistant. Your job is to guide the user th
 
 Work through this process step by step. Do NOT skip steps or launch a tool until all steps are complete.
 
+## Semantic Code Search
+
+Use `cocoindex-code_search` to quickly understand the codebase when clarifying requirements:
+- Search by meaning (e.g., "user authentication flow", "API rate limiting") to understand existing architecture
+- Use this to give informed answers when the user asks about current behavior
+
 ---
 
 ## Step 1: Understand the request
@@ -64,7 +72,7 @@ Ask the user which workflow they prefer. If they are unsure, recommend one based
 
 Present the default models that will be used for the chosen workflow:
 
-**Pipeline defaults:**
+**Pipeline defaults:** (hardcoded per-role model assignments)
 - 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
@@ -73,13 +81,14 @@ Present the default models that will be used for the chosen workflow:
 - 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
+**Mini-loop defaults:** (inherits the current session model)
+- All roles (build, review, documentation, doc review) default to the **current session model** — no hardcoded model is forced.
+- This means the mini-loop automatically uses whatever model you're currently chatting with.
+- You can override any individual role if desired (e.g., use a different model for review).
+
+For the **Pipeline**, ask: "Would you like to use these default models, or would you like to override any of them?"
 
-Ask: "Would you like to use these default models, or would you like to override any of them?"
+For the **Mini-loop**, ask: "The mini-loop will use your current session model for all roles by default. Would you like to override any specific roles (build, review, doc, doc_review)? You can call `ff_list_models` to see available providers and models."
 
 If they want to override, collect the provider/model strings for each role they want to change.
 

package/agents/ff-research.md

@@ -7,6 +7,7 @@ tools:
   write: false
   edit: false
   bash: false
+  hashline_edit: false
   skill: true
   task: false
 permission:
@@ -22,6 +23,31 @@ You are the research specialist.
 - Compare trade-offs and recommend practical defaults.
 - Provide source-backed outputs that planning/building/reviewing can apply directly.
 
+## Available MCP Tools
+
+You have access to powerful external research tools. **Use them proactively:**
+
+### Web Search & Reading
+- **`jina-ai_search_web`** — Search the web for current information, docs, articles. Use for up-to-date library info, best practices, changelogs.
+- **`jina-ai_read_url`** — Read and extract content from any URL. Use to read official documentation, blog posts, READMEs.
+- **`jina-ai_expand_query`** — Expand search queries for broader coverage.
+- **`jina-ai_parallel_search_web`** — Run multiple searches in parallel for comprehensive coverage.
+- **`jina-ai_parallel_read_url`** — Read multiple URLs in parallel.
+
+### Library Documentation
+- **`context7_resolve-library-id`** — Resolve a library name to a Context7 ID. Call this first before querying docs.
+- **`context7_query-docs`** — Query up-to-date library documentation with code examples. Excellent for API usage, configuration, and best practices.
+
+### Code Examples
+- **`gh_grep_searchGitHub`** — Find real-world code examples from public GitHub repos. Search for literal code patterns (e.g., `useState(`, `import React from`), NOT keywords. Use to see how real projects implement specific patterns.
+
+### Academic Papers
+- **`jina-ai_search_arxiv`** — Search arXiv for research papers (AI, CS, physics, math).
+- **`jina-ai_search_ssrn`** — Search SSRN for social science research.
+
+### Semantic Code Search
+- **`cocoindex-code_search`** — Search the local codebase by meaning. Use to understand the project's existing patterns before recommending changes.
+
 ## Method
 
 1. Load `ff-research-methods`.

package/agents/planning.md

@@ -7,6 +7,7 @@ tools:
   write: false
   edit: false
   bash: false
+  hashline_edit: false
   skill: true
   task: true
 permission:
@@ -25,6 +26,28 @@ You are the planning specialist.
 - Identify risks, assumptions, and validation strategy.
 - Apply planning gate criteria and emit explicit status lines.
 
+## Hashline Workflow (Required)
+
+Use the `read` tool to inspect files. Lines are annotated with `#HL <line>:<hash>|<content>` and a `#HL REV:<hash>` header. Use these refs when planning edit operations — include the `startRef` values in your implementation steps so the builder can apply them directly.
+
+You are a read-only agent — you do not write or edit files.
+
+## Semantic Code Search
+
+Use `cocoindex-code_search` for semantic code search 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
+
+Prefer this over `grep` when searching by concept rather than exact text.
+
+## External Research
+
+Use `@ff-research` for external/library uncertainty. The research agent has access to:
+- `jina-ai_search_web` / `jina-ai_read_url` for web search and documentation
+- `context7_query-docs` for library-specific documentation
+- `gh_grep_searchGitHub` for real-world code examples
+
 ## Operating Mode
 
 - Prefer deterministic, structured output sections.

package/agents/reviewing.md

@@ -7,6 +7,7 @@ tools:
   write: false
   edit: false
   bash: false
+  hashline_edit: false
   skill: true
   task: true
 permission:
@@ -25,6 +26,21 @@ You are the unified reviewing specialist.
 - Apply scope based on context: acceptance, code quality, security, architecture, documentation.
 - Return actionable findings with severity and confidence.
 
+## Hashline Workflow (Required)
+
+Use the `read` tool to inspect files. Lines are annotated with `#HL <line>:<hash>|<content>` and a `#HL REV:<hash>` header. Use these refs to cite specific lines in your review findings.
+
+You are a read-only agent — you do not write or edit files.
+
+## Semantic Code Search
+
+Use `cocoindex-code_search` for semantic code search 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
+
+Prefer this over `grep` when searching by concept rather than exact text.
+
 ## Skills to Load by Scope
 
 - `ff-reviewing-code-quality`

package/bin/ff-deploy.js

@@ -57,7 +57,7 @@ const DEFAULT_PLUGINS = [
   '@franlol/opencode-md-table-formatter@latest',
   '@spoons-and-mirrors/subtask2@latest',
   'opencode-pty@latest',
-  '@angdrew/opencode-hashline-plugin@latest',
+  'opencode-hashline@latest',
 ];
 
 function getPackageBaseName(plugin) {

package/dist/plugin-config.js

@@ -10,7 +10,7 @@ export const DEFAULT_PLUGINS = [
     '@franlol/opencode-md-table-formatter@latest',
     '@spoons-and-mirrors/subtask2@latest',
     'opencode-pty@latest',
-    '@angdrew/opencode-hashline-plugin@latest',
+    'opencode-hashline@latest',
 ];
 /**
  * Extract the base package name from a plugin specifier, stripping the

package/dist/tools/index.d.ts

@@ -2,9 +2,9 @@
  * 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.
+ * Only entrypoint tools (pipeline, mini-loop) and discovery tools
  * Internal workflow steps are orchestrated programmatically, not as
- * individually callable tools.
+ * individually callable tools. The list-models tool is a read-only discovery helper.
  */
 import type { ToolDefinition } from '@opencode-ai/plugin/tool';
 import type { Client } from '../workflow/fan-out.js';

package/dist/tools/index.js

@@ -2,12 +2,13 @@
  * 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.
+ * Only entrypoint tools (pipeline, mini-loop) and discovery tools
  * Internal workflow steps are orchestrated programmatically, not as
- * individually callable tools.
+ * individually callable tools. The list-models tool is a read-only discovery helper.
  */
 import { createPipelineTool } from './pipeline.js';
 import { createMiniLoopTool } from './mini-loop.js';
+import { createListModelsTool } from './list-models.js';
 /**
  * Build the tool map to be merged into the plugin's `Hooks.tool` output.
  *
@@ -17,5 +18,6 @@ export function createWorkflowTools(client) {
     return {
         ff_pipeline: createPipelineTool(client),
         ff_mini_loop: createMiniLoopTool(client),
+        ff_list_models: createListModelsTool(client),
     };
 }

package/dist/tools/list-models.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ff_list_models — Discovery tool for available providers and models.
+ *
+ * Read-only tool that queries the OpenCode SDK to list all available
+ * providers and their models, so users can see what's available before
+ * overriding mini-loop or pipeline model parameters.
+ */
+import type { Client } from '../workflow/fan-out.js';
+export declare function createListModelsTool(client: Client): {
+    description: string;
+    args: {};
+    execute(args: Record<string, never>, context: import("@opencode-ai/plugin/tool").ToolContext): Promise<string>;
+};

package/dist/tools/list-models.js

@@ -0,0 +1,67 @@
+/**
+ * ff_list_models — Discovery tool for available providers and models.
+ *
+ * Read-only tool that queries the OpenCode SDK to list all available
+ * providers and their models, so users can see what's available before
+ * overriding mini-loop or pipeline model parameters.
+ */
+import { tool } from '@opencode-ai/plugin/tool';
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+export function createListModelsTool(client) {
+    return tool({
+        description: 'List all available AI providers and their models. ' +
+            'Use this to discover which provider/model strings can be passed to ff_pipeline or ff_mini_loop.',
+        args: {},
+        async execute() {
+            const response = await client.provider.list();
+            const data = response.data;
+            if (!data) {
+                return 'Unable to retrieve provider list from the OpenCode SDK.';
+            }
+            const { all: providers, connected, default: defaults } = data;
+            const lines = ['# Available Providers and Models\n'];
+            // Show default model assignments
+            if (defaults && Object.keys(defaults).length > 0) {
+                lines.push('## Defaults\n');
+                for (const [role, model] of Object.entries(defaults)) {
+                    lines.push(`- **${role}**: ${model}`);
+                }
+                lines.push('');
+            }
+            // Show connected providers
+            if (connected.length > 0) {
+                lines.push(`## Connected Providers\n`);
+                lines.push(connected.map((p) => `\`${p}\``).join(', '));
+                lines.push('');
+            }
+            // List all providers and their models
+            for (const provider of providers) {
+                const isConnected = connected.includes(provider.id);
+                const statusBadge = isConnected ? '✅' : '⚠️ (not connected)';
+                lines.push(`## ${provider.name} ${statusBadge}\n`);
+                lines.push(`Provider ID: \`${provider.id}\`\n`);
+                const modelEntries = Object.entries(provider.models);
+                if (modelEntries.length === 0) {
+                    lines.push('_No models available._\n');
+                    continue;
+                }
+                lines.push('| Model ID | Name | Reasoning | Tool Calls | Attachments |');
+                lines.push('|----------|------|-----------|------------|-------------|');
+                for (const [, model] of modelEntries) {
+                    const flags = [
+                        model.reasoning ? '✅' : '—',
+                        model.tool_call ? '✅' : '—',
+                        model.attachment ? '✅' : '—',
+                    ];
+                    lines.push(`| \`${provider.id}/${model.id}\` | ${model.name} | ${flags[0]} | ${flags[1]} | ${flags[2]} |`);
+                }
+                lines.push('');
+            }
+            lines.push('---\n' +
+                'Use the `provider_id/model_id` format when overriding models in `ff_mini_loop` or `ff_pipeline`.');
+            return lines.join('\n');
+        },
+    });
+}

package/dist/tools/mini-loop.js

@@ -5,7 +5,7 @@
  * 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 { promptSession, evaluateMiniLoopImplGate, evaluateMiniLoopDocGate, parseModelString, } from '../workflow/orchestrator.js';
 import { miniBuildPrompt, miniReviewPrompt, documentPrompt, docReviewPrompt } from './prompts.js';
 import { parseMiniReview, parseDocReview } from './parsers.js';
 // ---------------------------------------------------------------------------
@@ -16,7 +16,7 @@ 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.',
+            'All model parameters are optional — when omitted, child sessions inherit the current session model.',
         args: {
             requirements: tool.schema
                 .string()
@@ -24,39 +24,39 @@ export function createMiniLoopTool(client) {
             build_model: tool.schema
                 .string()
                 .optional()
-                .describe('provider/model for building and implementation. Defaults to openai/gpt-5.3-codex.'),
+                .describe('provider/model for building and implementation. When omitted, inherits the session model.'),
             review_model: tool.schema
                 .string()
                 .optional()
-                .describe('provider/model for implementation review. Defaults to openai/gpt-5.4.'),
+                .describe('provider/model for implementation review. When omitted, inherits the session model.'),
             doc_model: tool.schema
                 .string()
                 .optional()
-                .describe('provider/model for documentation writing. Defaults to the build model.'),
+                .describe('provider/model for documentation writing. When omitted, defaults to build_model if provided, otherwise inherits the session model.'),
             doc_review_model: tool.schema
                 .string()
                 .optional()
-                .describe('provider/model for documentation review. Defaults to opencode/gemini-3.1-pro.'),
+                .describe('provider/model for documentation review. When omitted, inherits the session model.'),
         },
         async execute(args, context) {
             const totalStartMs = Date.now();
             const sessionId = context.sessionID;
             const { requirements } = args;
-            // Resolve models — use provided overrides or fall back to defaults
+            // Resolve models — use provided overrides or undefined (inherit session model)
             const buildModel = args.build_model
                 ? parseModelString(args.build_model)
-                : BUILD_MODEL;
+                : undefined;
             const reviewModel = args.review_model
                 ? parseModelString(args.review_model)
-                : ORCHESTRATOR_MODEL;
+                : undefined;
             const docModel = args.doc_model
                 ? parseModelString(args.doc_model)
                 : args.build_model
                     ? buildModel
-                    : DOC_MODEL;
+                    : undefined;
             const docReviewModel = args.doc_review_model
                 ? parseModelString(args.doc_review_model)
-                : DOC_REVIEW_MODEL;
+                : undefined;
             const report = [];
             const addReport = (phase, msg) => {
                 report.push(`## ${phase}\n${msg}`);

package/dist/workflow/fan-out.d.ts

@@ -12,7 +12,7 @@
 import type { NamedModel, ModelId } from './types.js';
 /**
  * Opaque client type — the plugin receives `ReturnType<typeof createOpencodeClient>`
- * but we only need `.session.create` and `.session.prompt`.
+ * but we only need a subset of the SDK surface.
  * We keep it loosely typed so this module doesn't import the full SDK.
  */
 export type Client = {
@@ -53,6 +53,33 @@ export type Client = {
             };
         }>;
     };
+    provider: {
+        list(options?: {
+            query?: {
+                directory?: string;
+            };
+        }): Promise<{
+            data?: {
+                all: Array<{
+                    id: string;
+                    name: string;
+                    models: {
+                        [key: string]: {
+                            id: string;
+                            name: string;
+                            attachment: boolean;
+                            reasoning: boolean;
+                            tool_call: boolean;
+                        };
+                    };
+                }>;
+                connected: Array<string>;
+                default: {
+                    [key: string]: string;
+                };
+            };
+        }>;
+    };
 };
 /** Extract all text parts from an SDK prompt response. */
 export declare function extractText(parts: Array<{

package/dist/workflow/fan-out.js

@@ -41,13 +41,20 @@ async function promptInChildSession(client, parentSessionId, prompt, options) {
         throw new Error('Failed to create child session');
     }
     // 2. Send the prompt to the child session
+    //    When model is undefined, omit it entirely so the child session
+    //    inherits the parent session's model (SDK default behavior).
+    const body = {
+        parts: [{ type: 'text', text: prompt }],
+    };
+    if (options?.model) {
+        body.model = options.model;
+    }
+    if (options?.agent) {
+        body.agent = options.agent;
+    }
     const response = await client.session.prompt({
         path: { id: childId },
-        body: {
-            model: options?.model,
-            agent: options?.agent,
-            parts: [{ type: 'text', text: prompt }],
-        },
+        body,
     });
     // 3. Extract and return the text
     return extractText(response.data?.parts ?? []);

package/package.json

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