@syntesseraai/opencode-feature-factory

OpenCode plugin that provides Feature Factory agents, skills, commands, and native stage orchestration guidance.

Notable bundled skills include ff-mini-plan, ff-todo-management, ff-oo (context-efficient shell command output compression with oo wrappers), ff-github (GitHub CLI-first workflows with repo-local temp file guidance), and ff-documentation-rules (shared docs/, INDEX.md, and root README.md documentation governance).

External research is provided as a shared skill (ff-research-methods) that stage agents load directly when they need to investigate external libraries, APIs, or best practices.

Installation

1) Add plugin to your project config

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@syntesseraai/opencode-feature-factory"]
}

2) Install global assets

npx @syntesseraai/opencode-feature-factory install

The installer deploys to ~/.config/opencode/:

• agents/
• skills/
• commands/
• AGENTS.md

It also updates ~/.config/opencode/opencode.json non-destructively by merging missing Feature Factory MCP entries and plugins without deleting existing user configuration.

Install Behavior

• Always overwrites packaged assets: installer unconditionally overwrites Feature Factory agents, skills, commands, and AGENTS.md files on every install.
• opencode.json is non-destructive: existing keys/values are preserved; only missing required plugin/MCP entries are added.
• No automatic plugin removals: existing plugin entries are preserved as-is, including entries no longer in current defaults.
• Global scope: assets are installed to ~/.config/opencode/ and shared across projects.

Global AGENTS Guide

~/.config/opencode/AGENTS.md is installed from this package and provides Feature Factory-specific operating guidance, including the fixed workflow path and preferred tool patterns (semantic search, edit workflow, and bash-first command execution).

Documentation Governance

The plugin bundles ff-documentation-rules, which the main workflow agents use whenever work affects repository documentation. It standardizes:

• Long-form documentation under docs/
• An INDEX.md in every docs/ directory and subdirectory
• Same-level document links, child-index forward references, parent-index back references, and brief descriptions for every linked item
• Root README.md links into the repository's primary documentation entry points

Workflow Orchestration

The plugin no longer exposes ff_pipeline, ff_mini_loop, or ff_list_models as MCP tools.

Instead, the feature-factory primary agent orchestrates workflows natively by delegating to stage sub-agents:

• feature-factory (orchestrator) -> default model openai/gpt-5.5-fast
  • planning -> default model openai/gpt-5.5-fast
  • building -> default model openai/gpt-5.5-fast
  • reviewing -> default model opencode/glm-5.1
  • documenting -> default model opencode/gemini-3.1-pro

Fixed execution path

1. Plan if needed (or consume approved planning handoff).
2. Scope-clear authorization checkpoint; once scope is clear, summarize it in 1-3 bullets, and treat clear imperative requests as authorization to proceed.
3. Build.
4. Document.
5. Review implementation + documentation gates.
6. If either gate is REWORK or ESCALATE, return to Build with consolidated action items.
7. Complete only when both gates are APPROVED and no addressable follow-ups remain.

Each transition carries forward normalized prior-stage context (summary, gate/verdict, action items, and open issues) plus the complete previous-stage last message as RAW_PREVIOUS_STAGE_OUTPUT by default. Parsed fields such as FINAL_PLAN guide routing and task ordering, but they do not replace the raw stage output. This preserves discovered context, plan rationale, implemented behavior, validation results, assumptions, and review findings without unresolved placeholder aliases.

When an approved planning handoff already includes PLANNING_GATE=APPROVED + FINAL_PLAN, the orchestrator proceeds automatically to Build once scope is clear and summarized. It passes the full Planning last message into Build as plan context, uses FINAL_PLAN for task ordering, must not ask for a separate scope-clear authorization or plan-approval step, and must not add a separate “starting now” notice before Build.

If platform context limits force truncation, the handoff must label the raw output as truncated, preserve required gate/status lines and output sections, and summarize omitted material explicitly.

The same rule applies to imperative follow-on requests derived from prior workflow outputs such as OPEN_ISSUES, action items, or non-blocking items: if the instruction is clear, the orchestrator should proceed without an extra approval turn.

Writable stage agents (building, documenting) prefer native edit (and write for new files) when needed. Read-only agents keep edit disabled.

Stage-agent code discovery is graph-first: planning/building/reviewing/documenting prefer codebase-memory MCP tools (codebase-memory-mcp_search_graph, codebase-memory-mcp_get_architecture, codebase-memory-mcp_trace_call_path, codebase-memory-mcp_get_code_snippet) for repository-local analysis, and use gh_grep_searchGitHub when investigating public GitHub source examples.

Agent tool-access policy

Feature Factory agent assets primarily use OpenCode agent frontmatter to keep stage capabilities explicit.

• reviewing now uses a tools block instead of permissions because some OpenCode models (including GLM/Kimi-family models) have compatibility issues with permission-based agent configs.
• reviewing remains read-only by disabling write, edit, bash, all PTY tools, and task directly in the tools block.
• Other stage agents may still use more granular permission-based shell allowances where model compatibility allows it.

Plugin auto-handoff safety net

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.

• The orchestrator emits RECOMMENDED_NEXT_STEP for deterministic stage progression and for approved-but-addressable review follow-ups, including explicit OPEN_ISSUES, NON_BLOCKING_ISSUES, action items, minor issues, or non-blocking items that can be resolved without user input.

• The orchestrator omits RECOMMENDED_NEXT_STEP when the workflow is complete, blocked, escalated, waiting on required user input, or has no addressable follow-up remaining.

• 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 machine-readable formats (outer quotes are optional, may be single or double quotes, and are stripped when present):

  • RECOMMENDED_NEXT_STEP: "<human-readable next step>"
  • 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

The plugin installs global custom slash commands in ~/.config/opencode/commands/:

• /ff-review [optional prompt]
  • Agent: reviewing
  • Subtask: false (runs as a main agent)
  • Mode: manual standalone helper (does not continue the full pipeline automatically)
  • Default prompt when no argument is provided: Review the changes so far
• /ff-document [optional prompt]
  • Agent: documenting
  • Subtask: false (runs as a main agent)
  • Mode: manual standalone helper (does not continue the full pipeline automatically)
  • Default prompt when no argument is provided: Document all the changes so far
• /ff-rework [optional prompt]
  • Agent: building
  • Subtask: false (runs as a main agent)
  • Mode: manual standalone helper (does not continue the full pipeline automatically)
  • Default prompt when no argument is provided: apply the rework recommendations

Examples:

• /ff-review
• /ff-review Focus on security and regression risk
• /ff-document
• /ff-document Summarize API and migration changes only
• /ff-rework
• /ff-rework Address review blockers and apply suggested fixes

Global Config Defaults

The plugin merges the following MCP servers into global OpenCode config when missing:

• jina-ai
• gh_grep

codebase-memory-mcp is currently treated as an optional prerequisite (not auto-provisioned by this plugin) because it commonly requires repository-specific indexing/setup.

The plugin also merges the following default plugins when they are missing:

• @syntesseraai/opencode-feature-factory@latest
• @nick-vi/opencode-type-inject@latest
• @franlol/opencode-md-table-formatter@latest
• opencode-pty@latest

Merge Outcomes

DEFAULT_MCP_SERVERS currently includes 2 servers (jina-ai, gh_grep).

The merge behavior is additive and non-destructive:

• Empty or missing existing MCP config -> 2 servers after merge.
• Existing config with 1 custom server and a customized gh_grep entry -> 3 servers after merge (custom + customized gh_grep + 1 missing default).
• Existing server definitions are preserved and never overwritten by defaults.

Plugin merge behavior is also additive and non-destructive:

• Existing plugin entries are preserved and never removed.
• Matching is by package base name, so pinned versions (for example [email protected]) prevent adding the @latest variant.
• Legacy @spoons-and-mirrors/subtask2 entries in user config remain untouched if already present, but are no longer added to new installs/default merges.

Related Docs

• docs/PIPELINE_ORCHESTRATION.md
• docs/PLUGIN_PUBLISH.md

License

MIT