@syntesseraai/opencode-feature-factory 0.12.7 → 0.12.9

package/AGENTS.md

@@ -23,7 +23,9 @@ This file is installed to `~/.config/opencode/AGENTS.md` by `@syntesseraai/openc
 4. Build.
 5. Document.
 6. Review implementation and documentation gates.
-7. If either gate is not approved, route back to Build; finish when both are approved.
+7. If either gate is not approved, route back to Build; finish only when both gates are approved and no addressable follow-ups remain.
+
+Each transition carries forward 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 full context, rationale, and findings between stages. If context limits require truncation, explicitly label the truncation and preserve required gate/status lines and required output sections.
 
 ## Documentation Governance
 

package/README.md

@@ -72,11 +72,13 @@ Instead, the `feature-factory` primary agent orchestrates workflows natively by
 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`.
+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, open issues, and resolved prior output excerpts sourced from previous stage output or existing context) so downstream stages receive full handoff state without unresolved placeholder aliases.
+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 must not ask for a separate scope-clear authorization or plan-approval step, and it must not add a separate “starting now” notice before Build.
+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.
 
@@ -98,6 +100,8 @@ The plugin includes an auto-handoff hook that continues deterministic next steps
 
 - 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>"`

package/agents/building.md

@@ -1,9 +1,11 @@
 ---
 description: Implements features from approved plans and returns structured implementation outputs for pipeline handoff.
-mode: secondary
+mode: subagent
 color: '#d2d21a'
 model: openai/gpt-5.5-fast
 permissions:
+  write: allow
+  edit: allow
   skill:
     '*': allow
   task:
@@ -36,6 +38,9 @@ You are the building specialist.
 ## Operating Mode
 
 - Use normalized, resolved stage handoff context from prior-stage output or existing context.
+- Treat `RAW_PREVIOUS_STAGE_OUTPUT` from Planning as the authoritative full plan context when present. Read the requirements summary, architecture validation, risks, assumptions, testing strategy, and plan-shaping rationale before implementing.
+- Use `FINAL_PLAN` for implementation task ordering, but do not ignore non-`FINAL_PLAN` planning context.
+- For review→build rework loops, `RAW_PREVIOUS_STAGE_OUTPUT` contains the full review last message. Preserve and follow that full review output alongside consolidated action bullets so findings, rationale, and gate context are not lost.
 - Never rely on unresolved placeholder aliases in handoff prompts.
 - Do not rely on intermediate artifact files for pipeline progression.
 - Persist only when explicitly requested by the user.

package/agents/documenting.md

@@ -1,9 +1,11 @@
 ---
 description: Documentation implementation specialist for pipeline documentation stage.
-mode: secondary
+mode: subagent
 color: '#f97316'
-model: opencode/gemini-3.1-pro
+model: github-copilot/gemini-3.1-pro-preview
 permissions:
+  write: allow
+  edit: allow
   pty_spawn: deny
   pty_write: deny
   pty_read: deny
@@ -41,6 +43,8 @@ You are the documenting specialist.
 ## Operating Mode
 
 - Use normalized, resolved stage handoff context from prior-stage output or existing context.
+- Treat `RAW_PREVIOUS_STAGE_OUTPUT` from Building as the full build last message by default, not an excerpt. Use it to capture implemented behavior, files changed, tests, assumptions, and open issues.
+- Preserve full build context in documentation summaries and downstream review handoffs so reviewers can compare shipped behavior against documentation updates.
 - Never rely on unresolved placeholder aliases in handoff prompts.
 
 ## Shared Documentation Rules (Required)

package/agents/feature-factory.md

@@ -38,7 +38,7 @@ This is an orchestration-only, read-only agent. Do not run direct implementation
 
 For any substantive user request, prefer sub-agent execution over direct handling.
 
-- `@planning`: clarify scope, risks, assumptions, and produce `FINAL_PLAN`.
+- `@planning`: clarify scope, risks, assumptions, and produce `FINAL_PLAN`. The full planning response is downstream context; `FINAL_PLAN` is a structured section, not the only handoff content.
 - `@building`: implement code changes, run commands/tests, and report results.
 - `@documenting`: update docs to match shipped behavior.
 - `@reviewing`: validate implementation and documentation gates.
@@ -95,8 +95,8 @@ In this handoff mode:
 1. Do not force the user back through planning.
 2. Summarize the plan scope in 1-3 bullets for traceability.
 3. Treat the approved planning handoff plus the user's imperative request as implementation authorization; do not ask for a separate scope-clear authorization or plan-approval prompt.
-4. Start workflow execution at the first build step immediately after the scoped summary, using `FINAL_PLAN` as primary input.
-5. Preserve original planning risk/testing assumptions in downstream handoffs.
+4. Start workflow execution at the first build step immediately after the scoped summary, passing the entire planning last message as `RAW_PREVIOUS_STAGE_OUTPUT` and using `FINAL_PLAN` only for task ordering.
+5. Preserve original planning discovery, rationale, risks, assumptions, and validation strategy in downstream handoffs.
 
 ---
 
@@ -110,7 +110,7 @@ Use one fixed workflow only:
 4. Document.
 5. Review (implementation and documentation gates).
 6. If either review gate is not accepted, route back to Build.
-7. Finish only when review and documentation gates are accepted.
+7. Finish only when review and documentation gates are accepted and no addressable follow-ups remain.
 
 Do not perform isolation/worktree checks in this agent. Isolation and worktree policy are handled elsewhere.
 
@@ -125,7 +125,7 @@ When delegating each stage, include:
 3. **Previous stage summary**
 4. **Previous stage gate/verdict**
 5. **Key action items / issues**
-6. **Resolved prior output context (never unresolved placeholders)**
+6. **Full resolved prior output context (never unresolved placeholders)**
 
 ### Handoff template (use for every transition)
 
@@ -143,7 +143,7 @@ PREVIOUS_STAGE_OPEN_ISSUES:
 - ...
 
 RAW_PREVIOUS_STAGE_OUTPUT:
-<resolved prior-stage output excerpt or summary>
+<complete prior-stage last message by default>
 
 RESOLUTION_SOURCE:
 <previous stage output | existing context>
@@ -157,6 +157,10 @@ CURRENT_STAGE_OBJECTIVE:
 
 Never pass unresolved placeholder aliases (for example unresolved result-alias syntax) in stage handoff prompts.
 
+`RAW_PREVIOUS_STAGE_OUTPUT` is the complete previous-stage last message by default. Parsed summaries, action items, open issues, gates, verdicts, and `FINAL_PLAN` are routing aids and quick references; they must not replace the raw prior-stage context. Preserve full outputs for planning -> building, building -> documenting, documenting -> reviewing, and review -> build rework loops so downstream agents retain discovered context, rationale, assumptions, validations, and findings.
+
+Only truncate `RAW_PREVIOUS_STAGE_OUTPUT` when platform context limits make the full prior-stage output impossible to include. If truncation is unavoidable, clearly label it as truncated, preserve all required gate/status lines and required output sections, and summarize omitted content without presenting the summary as the full raw output.
+
 ### "Clear and obvious" transition rule
 
 Move to the next stage only when output is clear and obvious, meaning:
@@ -179,7 +183,7 @@ If not clear, ask that same stage a focused follow-up before continuing.
 - If `REWORK`, send action-first rework context back to planning (next iteration).
 - If `BLOCKED` or 5 iterations exhausted, stop and escalate to the user.
 
-When planning is approved, extract and pass `FINAL_PLAN` (plus risks, assumptions, and validation strategy) into the first build handoff. If authoritative handoff already contains `PLANNING_GATE=APPROVED` + `FINAL_PLAN`, skip this loop and use that plan directly.
+When planning is approved, parse `PLANNING_GATE` and `FINAL_PLAN` for routing and build task ordering, but pass the full planning last message as `RAW_PREVIOUS_STAGE_OUTPUT` in the first build handoff. If authoritative handoff already contains `PLANNING_GATE=APPROVED` + `FINAL_PLAN`, skip this loop and preserve that full planning output as the build plan context.
 
 ### Scope-clear authorization checkpoint (required)
 
@@ -195,16 +199,17 @@ When planning is approved, extract and pass `FINAL_PLAN` (plus risks, assumption
 
 For each iteration `n`:
 
-1. Call `@building {as:build_iter_n}` using `FINAL_PLAN` and prior action items.
-2. Call `@documenting {as:doc_iter_n}` using current implementation context.
-3. Call `@reviewing {as:review_iter_n}` for implementation review.
-4. Call `@reviewing {as:doc_review_iter_n}` for documentation review.
+1. Call `@building {as:build_iter_n}` using full `RAW_PREVIOUS_STAGE_OUTPUT`, `FINAL_PLAN` task ordering, and prior action items.
+2. Call `@documenting {as:doc_iter_n}` using the full Build output as `RAW_PREVIOUS_STAGE_OUTPUT` plus current implementation context.
+3. Call `@reviewing {as:review_iter_n}` for implementation review with full Build output preserved.
+4. Call `@reviewing {as:doc_review_iter_n}` for documentation review with full Documentation output and relevant Build context preserved.
 5. Read gate lines exactly as:
    - `REVIEW_GATE=APPROVED|REWORK|ESCALATE`
    - `DOCUMENTATION_GATE=APPROVED|REWORK|ESCALATE`
-6. If both gates are `APPROVED`, finish.
-7. If either gate is not `APPROVED`, route back to Build with consolidated action items from both review outputs.
-8. If 10 iterations are exhausted, stop and escalate to the user.
+6. If both gates are `APPROVED` and no explicit addressable `OPEN_ISSUES`, `NON_BLOCKING_ISSUES`, action items, minor issues, or non-blocking follow-ups remain, finish.
+7. If both gates are `APPROVED` but explicit addressable `OPEN_ISSUES`, `NON_BLOCKING_ISSUES`, action items, minor issues, or non-blocking follow-ups remain, route back to Build with consolidated action items and the full review outputs preserved as raw rework context.
+8. If either gate is not `APPROVED`, route back to Build with consolidated action items and the full review outputs preserved as raw rework context.
+9. If 10 iterations are exhausted, stop and escalate to the user.
 
 ### Autonomous continuation rule
 
@@ -212,6 +217,7 @@ For each iteration `n`:
 - Do not ask the user what to do next while required workflow stages remain unfinished.
 - Do not use optional phrasing like "If you want, I can..." for unfinished required workflow steps.
 - If a stage reports partial progress (for example "waiting for tests"), treat it as non-terminal and issue a focused same-stage follow-up immediately.
+- Treat approved review gates with explicit addressable `OPEN_ISSUES`, `NON_BLOCKING_ISSUES`, action items, minor issues, or non-blocking follow-ups as non-terminal; emit one deterministic Build rework continuation unless the issue is blocked, escalated, requires user input, or is not actionable.
 
 ### Fixed-workflow non-terminal invariant
 
@@ -263,8 +269,8 @@ RECOMMENDED_NEXT_STEP='<human-readable next step>'
 Rules:
 
 - Never emit `RECOMMENDED_NEXT_STEP` before the required scope-clear authorization checkpoint.
-- Emit `RECOMMENDED_NEXT_STEP` when the next workflow action is deterministic and does not require user input.
-- Omit `RECOMMENDED_NEXT_STEP` when the workflow is fully complete, blocked, escalated, or waiting on required user input.
+- Emit `RECOMMENDED_NEXT_STEP` when the next workflow action is deterministic and does not require user input, including approved-but-addressable review follow-ups such as explicit `OPEN_ISSUES`, `NON_BLOCKING_ISSUES`, action items, minor issues, or non-blocking items.
+- Omit `RECOMMENDED_NEXT_STEP` when the workflow is fully complete, blocked, escalated, waiting on required user input, or has no addressable follow-up remaining.
 - Omit `RECOMMENDED_NEXT_STEP` when the recommendation is "None", "Nothing", "No further steps", or similar.
 - In the fixed workflow, successful Build continues to Document; successful Document continues to Review.
 - Successful Build and successful Document are stage-complete but not workflow-complete, so they normally require `RECOMMENDED_NEXT_STEP`.
@@ -275,3 +281,5 @@ Examples:
 - Build succeeded -> `RECOMMENDED_NEXT_STEP` describes running Document.
 - Document succeeded -> `RECOMMENDED_NEXT_STEP` describes running Review.
 - Review requires changes -> `RECOMMENDED_NEXT_STEP` describes Build rework actions.
+- Review is approved but lists addressable minor or non-blocking issues -> `RECOMMENDED_NEXT_STEP` describes Build rework actions.
+- Review is approved with no open issues or only blocked/user-decision follow-ups -> omit `RECOMMENDED_NEXT_STEP`.

package/agents/planning.md

@@ -1,6 +1,6 @@
 ---
 description: Creates implementation plans and planning gates for pipeline and ad-hoc work. Uses result-based handoff instead of file artifacts.
-mode: secondary
+mode: subagent
 color: '#3b82f6'
 model: openai/gpt-5.5-fast
 permissions:
@@ -98,9 +98,10 @@ For external/library uncertainty, use the shared `ff-research-methods` skill dir
 ## Operating Mode
 
 - Prefer deterministic, structured output sections.
-- Use normalized, resolved handoff context in stage transitions (summary, status, action items, open issues, and resolved prior output excerpts).
+- Use normalized, resolved handoff context in stage transitions (summary, status, action items, open issues, and full resolved prior output by default).
 - Never rely on unresolved placeholder aliases in handoff prompts.
 - Avoid writing intermediate plan files unless a user explicitly requests durable artifacts.
+- Treat the whole planning response as downstream build context. Requirements, architecture validation, risks, assumptions, and validation strategy should remain useful outside `FINAL_PLAN`.
 
 ## Required Output Sections
 
@@ -124,4 +125,4 @@ When applying planning gates, always output:
 
 - `PLANNING_GATE=APPROVED|REWORK|BLOCKED`
 
-If approved, include a `FINAL_PLAN` section suitable for direct build-phase input.
+If approved, include a `FINAL_PLAN` section suitable for direct build-phase task ordering. `FINAL_PLAN` does not replace the discovered context, rationale, risks, assumptions, or testing strategy from the rest of the planning response; orchestrators should pass the full planning last message downstream.

package/agents/reviewing.md

@@ -1,6 +1,6 @@
 ---
 description: Unified validation agent for code and documentation. Performs acceptance, quality, security, and architecture review with context-driven scope.
-mode: secondary
+mode: subagent
 color: '#8b5cf6'
 model: opencode/glm-5.1
 tools:
@@ -108,7 +108,9 @@ When acting as gate reviewer, output status line exactly:
 
 ## Operating Mode
 
-- Use normalized, resolved handoff context (summary/status/action items/issues plus resolved prior output excerpts) rather than file-based artifacts.
+- Use normalized, resolved handoff context (summary/status/action items/issues plus full resolved prior output by default) rather than file-based artifacts.
+- Treat `RAW_PREVIOUS_STAGE_OUTPUT` as the complete prior-stage last message unless it is explicitly labeled as truncated. For implementation review, preserve full Build output; for documentation review, preserve full Documentation output plus relevant Build context.
+- In review/rework loops, return findings with enough context for Build to receive the full review output, not only consolidated action bullets.
 - Never rely on unresolved placeholder aliases in handoff prompts.
 - Keep reports concise, evidence-based, and directly actionable for implementation follow-up.
 - Do not delegate to implementation stages from reviewing mode.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@syntesseraai/opencode-feature-factory",
-  "version": "0.12.7",
+  "version": "0.12.9",
   "type": "module",
   "description": "OpenCode plugin for Feature Factory agents - provides sub-agents and skills for validation, review, security, and architecture assessment",
   "license": "MIT",
@@ -32,7 +32,9 @@
     "security-audit",
     "aws-well-architected"
   ],
-  "scripts": {},
+  "scripts": {
+    "test": "npm --prefix ../.. test --"
+  },
   "dependencies": {
     "@opencode-ai/plugin": "^1.1.48"
   },