@syntesseraai/opencode-feature-factory 0.8.0 → 0.10.0

package/README.md

@@ -47,6 +47,7 @@ All shipped Feature Factory agent manifests under `agents/*.md` include a `color
 | `ff-research`     | `#6366f1` |
 
 These colors are intentionally unique to avoid collisions in OpenCode agent UIs and logs.
+
 ## Pipeline Entrypoint
 
 - Invoke `/pipeline/start <requirements-brief>` directly from any agent (e.g. `@building`).
@@ -60,11 +61,11 @@ These colors are intentionally unique to avoid collisions in OpenCode agent UIs
 
 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. |
+| 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
 
@@ -110,6 +111,44 @@ Models are declared in each command's frontmatter (`model:` field). Multi-model
 - Documentation approval: documentation reviewer verdict `APPROVED` with zero unresolved documentation issues.
 - Planning loop confirmation: after 5 unsuccessful planning iterations, pipeline asks user whether to continue.
 
+## Async Progress Notifications
+
+Both `ff_pipeline` and `ff_mini_loop` tools run asynchronously with real-time progress notifications:
+
+- **Immediate return**: Tools return instantly with a brief acknowledgment (e.g. `Pipeline started for: <summary>`), so the LLM can continue the conversation.
+- **Background orchestration**: The full pipeline or mini-loop runs in a detached `Promise`. All child session orchestration (fan-out, gates, loops) remains identical — it just executes after the tool returns.
+- **Progress updates via `promptAsync(noReply: true)`**: After each major phase completes, a structured notification is injected into the parent session as a visible chat message. These appear in the OpenCode TUI without triggering an LLM turn.
+- **Phase-by-phase visibility**: Users see updates for planning, building, each review iteration gate decision, each documentation iteration, and the final completion report.
+- **Error notifications**: If the background orchestration throws, a `<ff_pipeline_error>` or `<ff_mini_loop_error>` notification is sent with the last phase and error message.
+- **`context.metadata()` retained**: All existing metadata calls remain in place for future-proofing (when OpenCode's TUI renders tool metadata natively).
+
+### Notification Format
+
+Pipeline updates use XML-style tags for structured parsing:
+
+```
+<ff_pipeline_update>
+Phase: Planning
+Status: APPROVED
+Duration: 45.2s
+Next Phase: Building
+</ff_pipeline_update>
+```
+
+Mini-loop updates follow the same pattern:
+
+```
+<ff_mini_loop_update>
+Phase: Implementation
+Status: APPROVED
+Confidence: 97%
+Iteration: 2/10
+Duration: 32.1s
+</ff_mini_loop_update>
+```
+
+Final reports are wrapped in `<ff_pipeline_complete>` or `<ff_mini_loop_complete>` tags containing the full markdown report.
+
 ## Related Docs
 
 - `docs/PIPELINE_ORCHESTRATION.md`

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,6 +7,7 @@ tools:
   write: false
   edit: false
   bash: false
+  hashline_edit: false
   skill: true
   task: true
   ff_pipeline: true
@@ -28,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

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/mini-loop.d.ts

@@ -3,6 +3,10 @@
  *
  * A simpler two-stage workflow (no multi-model fan-out for planning).
  * Implements a build/review loop, then a documentation loop.
+ *
+ * The tool returns immediately with an acknowledgment. Orchestration
+ * runs asynchronously in the background, sending progress notifications
+ * to the parent session via `promptAsync(noReply: true)`.
  */
 import { type Client } from '../workflow/orchestrator.js';
 export declare function createMiniLoopTool(client: Client): {