@syntesseraai/opencode-feature-factory 0.6.4 → 0.6.6

package/README.md

@@ -1,12 +1,10 @@
 # @syntesseraai/opencode-feature-factory
 
-OpenCode plugin that provides Feature Factory agents for structured software development workflows.
+OpenCode plugin that provides Feature Factory agents, skills, and pipeline commands.
 
 ## Installation
 
-### 1. Install the Plugin
-
-Add the plugin to your `opencode.json`:
+### 1) Add plugin to your project config
 
 ```json
 {
@@ -15,116 +13,59 @@ Add the plugin to your `opencode.json`:
 }
 ```
 
-### 2. Install Agents, Skills, and MCP (Optional)
-
-To install Feature Factory agents, skills, and MCP servers globally, run:
+### 2) Install global assets
 
 ```bash
 npx @syntesseraai/opencode-feature-factory install
 ```
 
-This will:
-
-- Copy agents to `~/.config/opencode/agents/`
-- Copy skills to `~/.config/opencode/skills/`
-- Configure MCP servers in `~/.config/opencode/opencode.json`
-
-## Agents Provided
-
-### Primary Agents
-
-- **`@ff-plan`** - Creates detailed implementation plans based on GitHub issues. Read-only, no code changes.
-- **`@ff-build`** - Implements features based on plans. Full tool access with bash permission guards.
-
-### Subagents
-
-- **`@ff-mini-plan`** - Quick 2-5 step plans for smaller tasks. Escalates to `@ff-plan` for complex work.
-- **`@ff-review`** - Code review for correctness, quality, and test coverage.
-- **`@ff-security`** - Deep security audits (auth, injection, secrets, OWASP Top 10).
-- **`@ff-unit-test`** - Generates comprehensive unit tests with 80%+ coverage target.
-- **`@ff-e2e-test`** - Creates end-to-end tests for user workflows (Playwright/Cypress).
-- **`@ff-acceptance`** - Binary pass/fail validation against acceptance criteria.
-- **`@ff-well-architected`** - Reviews code against AWS Well-Architected Framework pillars.
-
-### Pipeline Model Split
-
-The package also includes a multi-model pipeline orchestrator defined in `agents/pipeline.md`.
-
-For the building phase of that pipeline:
+This installer deploys to `~/.config/opencode/`:
 
-- **`ff-building-opus`** - breaks the approved plan into atomic tasks
-- **`ff-building-gemini`** - validates architecture and enriches each task with codebase context
-- **`ff-building-chatgpt`** - implements validated tasks and handles rework loops
+- `agents/`
+- `skills/`
+- `commands/`
 
-See the repository workflow doc at `docs/PIPELINE_ORCHESTRATION.md` for the end-to-end three-phase workflow: https://github.com/SyntesseraAI/feature-factory/blob/main/docs/PIPELINE_ORCHESTRATION.md
+It also updates `~/.config/opencode/opencode.json` non-destructively by merging missing Feature Factory MCP entries and plugins without deleting existing user configuration.
 
-## Behavior
+## Install Behavior
 
-- **Manual install**: Agents and skills are installed via the `npx install` command, not automatically
-- **Never overwrites**: If an agent or skill file already exists, it is never overwritten. This respects any user customizations.
-- **Global install**: Agents and skills are installed to `~/.config/opencode/` for use across all projects
+- **Always overwrites packaged assets**: installer unconditionally overwrites Feature Factory `agents`, `skills`, and `commands` on every install.
+- **`opencode.json` is non-destructive**: existing keys/values are preserved; only missing required plugin/MCP entries are added.
+- **Global scope**: assets are installed to `~/.config/opencode/` and shared across projects.
 
-## Agent Scope Boundaries
+## Pipeline Entrypoint
 
-Each agent has a focused responsibility and delegates to specialists:
+- Use `@pipeline` as the start experience.
+- The `@pipeline` agent handles intake and launches `/pipeline/start`.
+- Orchestration is implemented by the command tree under `commands/pipeline/` using subtask2 primitives (`return`, `parallel`, `loop`).
+- Coordinator and synthesis model is ChatGPT 5.4.
 
-| Agent                 | Focus                       | Delegates to                                             |
-| --------------------- | --------------------------- | -------------------------------------------------------- |
-| `ff-plan`             | Deep planning, architecture | -                                                        |
-| `ff-build`            | Implementation              | All subagents                                            |
-| `ff-mini-plan`        | Quick plans (2-5 steps)     | `@ff-plan` for complex                                   |
-| `ff-review`           | Quality, correctness, tests | `@ff-security`, `@ff-well-architected`, `@ff-acceptance` |
-| `ff-security`         | Security only               | -                                                        |
-| `ff-unit-test`        | Unit tests only             | -                                                        |
-| `ff-e2e-test`         | E2E tests only              | -                                                        |
-| `ff-acceptance`       | Requirements validation     | -                                                        |
-| `ff-well-architected` | AWS pillars                 | `@ff-security` for deep security                         |
+## Command Tree
 
-## Customization
+- `/pipeline/start`
+- `/pipeline/planning/run`, `/pipeline/planning/run-opus`, `/pipeline/planning/run-gemini`, `/pipeline/planning/run-codex`, `/pipeline/planning/synthesize`, `/pipeline/planning/gate`
+- `/pipeline/building/run`, `/pipeline/building/breakdown`, `/pipeline/building/validate-batch`, `/pipeline/building/implement-batch`
+- `/pipeline/reviewing/run`, `/pipeline/reviewing/triage`, `/pipeline/reviewing/run-opus`, `/pipeline/reviewing/run-gemini`, `/pipeline/reviewing/run-codex`, `/pipeline/reviewing/synthesize`, `/pipeline/reviewing/gate`
+- `/pipeline/complete`
 
-After installation, you can edit any `ff-*.md` file in `.opencode/agent/` to customize behavior. The plugin will never overwrite your changes.
+## Model Split
 
-To reset an agent to defaults, delete the file and restart OpenCode.
+- Coordinator and synthesis: ChatGPT 5.4
+- Planning (with architecture validation): Codex, Gemini, Opus
+- Implementation: Codex only
+- Review (with architecture validation): Codex, Gemini, and Opus
+- Rework path: `/pipeline/reviewing/run` re-enters implementation via `/pipeline/building/implement-batch` when gate status is `REWORK`
 
-## Output Formats
+## Quality Gates
 
-All agents output structured JSON for consistent parsing:
-
-- Planning agents: `{ summary, steps[], files[], complexity, ... }`
-- Review/audit agents: `{ approved, confidence, findings[], recommendations[], ... }`
-- Acceptance: `{ accepted, criteriaMet[], criteriaNotMet[], ... }`
-
-## Release Process
-
-To publish a new version of `@syntesseraai/opencode-feature-factory`:
-
-```bash
-# 1. Clean the build output
-rm -rf packages/opencode-plugin/dist
-
-# 2. Bump the version in package.json
-#    Edit packages/opencode-plugin/package.json and increment "version"
-#    e.g. "0.4.6" → "0.4.7" (patch), "0.5.0" (minor), "1.0.0" (major)
-
-# 3. Rebuild the package
-cd packages/opencode-plugin && npx tsc && cd ../..
-
-# 4. Commit the changes
-git add packages/opencode-plugin/
-git commit -m "chore: bump opencode-plugin to vX.Y.Z"
-
-# 5. Push to remote
-git push
-
-# 6. Publish to npm
-cd packages/opencode-plugin && npm publish --access public && cd ../..
-```
+- Planning approval: `>=75%` consensus.
+- Review approval: `>=95%` confidence and zero unresolved issues.
+- Planning loop confirmation: after 5 unsuccessful planning iterations, pipeline asks user whether to continue.
 
-**Notes:**
+## Related Docs
 
-- The `dist/` directory must be deleted before rebuilding to ensure stale artifacts are removed.
-- The `npm publish --access public` flag is required because the package uses an `@syntesseraai` scope.
-- Verify the build output in `dist/` looks correct before publishing.
+- `docs/PIPELINE_ORCHESTRATION.md`
+- `docs/PLUGIN_PUBLISH.md`
 
 ## License
 

package/agents/{ff-building-chatgpt.md → ff-building-codex.md}

@@ -1,5 +1,5 @@
 ---
-description: 'Building specialist pinned to ChatGPT Codex. Implements features and makes code changes based on implementation plans. Use this sub-agent for ChatGPT-powered building via skill-based model routing.'
+description: 'Building specialist pinned to Codex. Implements features and makes code changes based on implementation plans.'
 model: openai/gpt-5.3-codex
 reasoning_effort: xhigh
 mode: subagent
@@ -94,7 +94,7 @@ At the start of EVERY building task:
 6. **Load the ff-mini-plan skill** and create an execution plan
 7. **Load the ff-todo-management skill** and create a todo list for tracking progress
 8. **Load the ff-severity-classification skill** to assess risks of changes
-9. **Document your context** - Use `ff-agents-update` tool to create `.feature-factory/agents/ff-building-chatgpt-{UUID}.md`
+9. **Document your context** - Use `ff-agents-update` tool to create `.feature-factory/agents/ff-building-codex-{UUID}.md`
 10. **Check for existing plans** - Use `ff-plans-list` and `ff-plans-get` to find implementation plans
 
 ## Git Workflow
@@ -127,7 +127,7 @@ You have access to specialized file tools. **CRITICAL:** Only use WRITE tools fo
 
 ### Agent Context Files (.feature-factory/agents/) - READ/WRITE
 
-- **ff-agents-update** - ⭐ CREATE/UPDATE your own agent context file (ff-building-chatgpt-{UUID}.md)
+- **ff-agents-update** - ⭐ CREATE/UPDATE your own agent context file (ff-building-codex-{UUID}.md)
 - **ff-agents-get** - Read agent context files (other agents' results)
 - **ff-agents-list** - List all agent files
 - **ff-agents-show** - Show detailed context for a specific agent
@@ -274,7 +274,7 @@ Before invoking @reviewing:
 3. **Read relevant contexts** - `ff-agents-show()` to build on others' work
 4. **Generate UUID** - Create unique ID for this building instance
 5. **Load required skills** (ff-delegation, ff-mini-plan, ff-todo-management, ff-severity-classification)
-6. **Document context** - Use `ff-agents-update` tool to create `.feature-factory/agents/ff-building-chatgpt-{UUID}.md`
+6. **Document context** - Use `ff-agents-update` tool to create `.feature-factory/agents/ff-building-codex-{UUID}.md`
 7. **Load or create** implementation plan (use `ff-plans-get` to read existing plans)
 8. **Create todo list** for execution
 9. **Execute implementation** steps

package/agents/{ff-planning-chatgpt.md → ff-planning-codex.md}

@@ -1,5 +1,5 @@
 ---
-description: 'Planning specialist pinned to ChatGPT. Creates comprehensive implementation plans before making any code changes. Use this sub-agent for ChatGPT-powered planning via skill-based model routing.'
+description: 'Planning specialist for pipeline planning and coordination tasks. Creates comprehensive implementation plans before making any code changes.'
 model: openai/gpt-5.4
 reasoning_effort: xhigh
 mode: subagent
@@ -77,7 +77,7 @@ At the start of EVERY planning task:
 6. **Load the ff-mini-plan skill** and assess task complexity
 7. **Load the ff-todo-management skill** and create a todo list for the planning process
 8. **Load the ff-report-templates skill** for standardized output formatting
-9. **Document your context** - Use `ff-agents-update` tool to create `.feature-factory/agents/ff-planning-chatgpt-{UUID}.md`
+9. **Document your context** - Use `ff-agents-update` tool to create `.feature-factory/agents/ff-planning-codex-{UUID}.md`
 
 ## File Management Tools
 
@@ -87,7 +87,7 @@ You have access to specialized file tools. **CRITICAL:** Only use WRITE tools fo
 
 **USE THESE for your own context:**
 
-- **ff-agents-update** - ⭐ CREATE/UPDATE your own agent context file (ff-planning-chatgpt-{UUID}.md)
+- **ff-agents-update** - ⭐ CREATE/UPDATE your own agent context file (ff-planning-codex-{UUID}.md)
 - **ff-agents-get** - Read agent context files from other agents
 - **ff-agents-list** - List all agent files
 - **ff-agents-show** - Show detailed context for a specific agent
@@ -184,7 +184,7 @@ Delegate these simultaneously at the start:
 ### Delegation Process
 
 1. **Generate your UUID** - `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`
-2. **Document your context** - Write to `.feature-factory/agents/ff-planning-chatgpt-{UUID}.md`
+2. **Document your context** - Write to `.feature-factory/agents/ff-planning-codex-{UUID}.md`
 3. **Generate child UUIDs** - One for each delegated agent
 4. **Delegate in parallel** - Use Task tool with specific instructions
 5. **Track in your context** - Add `delegated_to: [child-uuid-1, child-uuid-2]`
@@ -298,7 +298,7 @@ Use ff-report-templates skill for Mini Plan format:
 4. **Check for stale plan files** - Use `ff-plans-list` to see if old plans exist; if found, ask user if they should be cleaned up before proceeding
 5. **Generate UUID** - Create unique ID for this planning instance
 6. **Load required skills** (ff-delegation, ff-mini-plan, ff-todo-management, ff-report-templates)
-7. **Document context** - Use `ff-agents-update` tool to create `.feature-factory/agents/ff-planning-chatgpt-{UUID}.md`
+7. **Document context** - Use `ff-agents-update` tool to create `.feature-factory/agents/ff-planning-codex-{UUID}.md`
 8. **Delegate in parallel**:
    - Task(ff-research): "Research [technology] best practices. Save context via `ff-agents-update` as `ff-research-{UUID}.md`."
    - Task(ff-acceptance): "Validate acceptance criteria. Save context via `ff-agents-update` as `ff-acceptance-{UUID}.md`."

package/agents/{ff-reviewing-chatgpt.md → ff-reviewing-codex.md}

@@ -1,5 +1,5 @@
 ---
-description: 'Reviewing specialist pinned to ChatGPT. Comprehensive validation agent that reviews implementation quality across all dimensions. Use this sub-agent for ChatGPT-powered reviewing via skill-based model routing.'
+description: 'Reviewing specialist for pipeline review and coordination tasks. Comprehensive validation agent that reviews implementation quality across all dimensions.'
 model: openai/gpt-5.4
 reasoning_effort: xhigh
 mode: subagent
@@ -76,7 +76,7 @@ At the start of EVERY review task:
 5. **Load the ff-todo-management skill** and create a todo list for tracking review progress
 6. **Load the ff-report-templates skill** for standardized output formatting
 7. **Load the ff-severity-classification skill** to classify findings consistently
-8. **Document your context** - Use `ff-agents-update` tool to create `.feature-factory/agents/ff-reviewing-chatgpt-{UUID}.md`
+8. **Document your context** - Use `ff-agents-update` tool to create `.feature-factory/agents/ff-reviewing-codex-{UUID}.md`
 
 ## File Management Tools
 
@@ -84,7 +84,7 @@ You have access to specialized file tools. **CRITICAL:** Only use WRITE tools fo
 
 ### Agent Context Files (.feature-factory/agents/) - READ/WRITE
 
-- **ff-agents-update** - ⭐ CREATE/UPDATE your own agent context file (ff-reviewing-chatgpt-{UUID}.md)
+- **ff-agents-update** - ⭐ CREATE/UPDATE your own agent context file (ff-reviewing-codex-{UUID}.md)
 - **ff-agents-get** - Read agent context files from validation sub-agents
 - **ff-agents-list** - List all agent files
 - **ff-agents-show** - Show detailed context for a specific agent
@@ -122,7 +122,7 @@ Perform these validation activities directly:
 ## Validation Process
 
 1. **Generate your UUID** - `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`
-2. **Document your context** - Write to `.feature-factory/agents/ff-reviewing-chatgpt-{UUID}.md`
+2. **Document your context** - Write to `.feature-factory/agents/ff-reviewing-codex-{UUID}.md`
 3. **Review all dimensions** - Systematically validate acceptance, quality, security, and architecture
 4. **Classify findings** - Use ff-severity-classification for consistent severity assignment
 5. **Consolidate results** - Combine all findings into comprehensive report
@@ -230,7 +230,7 @@ Use ff-todo-management:
 3. **Read relevant contexts** - `ff-agents-show()` to build on others' work
 4. **Generate UUID** - Create unique ID for this reviewing instance
 5. **Load required skills** (ff-todo-management, ff-report-templates, ff-severity-classification)
-6. **Document context** - Use `ff-agents-update` tool to create `.feature-factory/agents/ff-reviewing-chatgpt-{UUID}.md`
+6. **Document context** - Use `ff-agents-update` tool to create `.feature-factory/agents/ff-reviewing-codex-{UUID}.md`
 7. **Create review todo list**
 8. **Perform acceptance validation**
 9. **Perform code quality review**