@duypham93/openkit 0.2.0

package/assets/install-bundle/opencode/skills/writing-plans/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: writing-plans
+description: "Converts approved architecture and scope into bite-sized implementation plans with validation matched to the workflow mode."
+---
+
+# Skill: Writing Implementation Plans
+
+## Context
+
+This skill is used by the Tech Lead Agent. It turns design documents (spec and architecture) into concrete coding steps that the Fullstack Agent can execute.
+
+Each plan should be detailed enough that the Fullstack Agent can execute it without guesswork.
+
+## Core Rules of a Good Plan
+
+1. **Bite-sized tasks**: each task should take roughly 2-5 minutes. If a task looks like more than 10 minutes, split it smaller.
+2. **Atomic steps**: each step should be a complete, testable unit. Do not leave half-finished code behind.
+3. **Exact file paths**: specify the exact absolute path or repository-relative path for every file to create or edit.
+4. **Validation flow**: plan validation must match the active workflow mode. Full-delivery logic work should be TDD-first when the repository has suitable test tooling. Migration work should prioritize preserved invariants, blocker-decoupling steps, compatibility checks, staged verification, and targeted tests only where they are truly reliable and helpful. If the repo does not define a standard command yet, the plan must state the missing validation path instead of inventing one.
+
+## Execution Process
+
+### Step 1: Context Gathering
+Make sure you have read:
+- `docs/specs/YYYY-MM-DD-<feature>.md`
+- `docs/architecture/YYYY-MM-DD-<feature>.md`
+- `context/core/code-quality.md`
+
+### Step 2: Write the Plan Document
+
+Create `docs/plans/YYYY-MM-DD-<feature>.md` using this structure:
+
+```markdown
+# Implementation Plan: [Feature Name]
+
+## Dependencies
+- Are any additional packages required? (`npm install X`, `pip install Y`)
+- Are any environment variables required?
+
+## Implementation Steps
+
+For each task, follow a validation-aware structure:
+
+### [ ] Task 1: [Specific action name, e.g. Init Database Schema]
+- **File**: `path/to/file.ext`
+- **Goal**: [Brief description]
+- **Validation Command**: `[test/build/typecheck/smoke/manual verification command for this step, or an explicit note that no repo-native validation command exists yet]`
+- **Details**:
+  - State the baseline or expected change for this step
+  - State the implementation or upgrade action
+  - State how the result will be verified honestly
+
+### [ ] Task 2: [Next task]
+...
+```
+
+### Step 3: Review and Refine
+- Are the tasks small enough?
+- Does any task require changing more than 3 files at once? -> If yes, split it.
+- In full mode, does any logic task skip the "write test first" step without justification? -> Add the test requirement.
+- In migration mode, does the plan mix rewrite work into the migration instead of isolating blockers and proving parity? -> Rewrite the sequence.
+- In migration mode, does the plan rely on fake TDD instead of baseline, compatibility, and regression evidence? -> Rewrite the validation guidance.
+- Does the plan cover all acceptance criteria from the spec?
+
+## Anti-Patterns
+- "Task 1: Build the frontend, Task 2: Build the backend." (Far too large.)
+- No test guidance or test command, and no explicit note that the repo lacks a standard command.
+- A plan that does not specify which files need to be edited.

package/assets/install-bundle/opencode/skills/writing-specs/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: writing-specs
+description: "Converts requirements into structured spec documents with concrete acceptance criteria."
+---
+
+# Skill: Writing Specs
+
+## Context
+
+This skill is used by the BA Agent to turn a high-level Product Brief into a detailed low-level spec that is ready for the Architect and the development team.
+
+## Execution Process
+
+### 1. Verification (Input Check)
+- Make sure you already have a Product Brief.
+- If the Product Brief is still vague (for example: "make it faster"), go back to the PM Agent or user and get measurable detail.
+
+### 2. User Stories Breakdown
+Break the feature into user flows (user stories).
+**Required format:** `As a [User Type], I want [Action], so that [Benefit/Value].`
+
+### 3. BDD Acceptance Criteria
+This is the hardest and most important section. Each user story must include Given-When-Then acceptance criteria.
+
+**Bad example (too vague):**
+> The submit button should be disabled when the data is invalid.
+
+**Good example (Given-When-Then):**
+> **Given** the user is on the "Create New" form
+> **And** the "Email" field is blank or invalid
+> **When** they try to click the "Submit" button
+> **Then** the "Submit" button must be disabled
+> **And** an empty/invalid-format error message appears under the "Email" field
+
+### 4. Edge Cases
+You must include a dedicated section for failure conditions and awkward scenarios:
+- What happens if the network drops mid-request?
+- What happens if the user double-clicks the button?
+- What happens with input that is too long, too short, or contains special characters?
+- Race conditions?
+
+### 5. Document Output
+Create the markdown file at `docs/specs/YYYY-MM-DD-<feature-name>.md`.
+
+## Anti-Patterns to Avoid
+- **Tech leaking**: putting technical implementation decisions in the spec (for example: "Use React `useState` to store the form"). A spec should describe behavior and requirements, not code.
+- **Unmeasurable goals**: "beautiful UI", "fast performance". Replace them with measurable requirements like "responsive on mobile" or "response time < 200ms".

package/assets/opencode.json.template

@@ -0,0 +1,11 @@
+{
+  "installState": {
+    "path": ".openkit/openkit-install.json",
+    "schema": "openkit/install-state@1"
+  },
+  "productSurface": {
+    "current": "global-openkit-install",
+    "installReadiness": "managed",
+    "installationMode": "openkit-managed"
+  }
+}

package/assets/openkit-install.json.template

@@ -0,0 +1,19 @@
+{
+  "schema": "openkit/install-state@1",
+  "stateVersion": 1,
+  "kit": {
+    "name": "OpenKit",
+    "version": "0.1.0"
+  },
+  "installation": {
+    "profile": "openkit-core",
+    "status": "installed",
+    "installedAt": "1970-01-01T00:00:00.000Z"
+  },
+  "assets": {
+    "managed": [],
+    "adopted": []
+  },
+  "warnings": [],
+  "conflicts": []
+}

package/bin/openkit.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli/index.js';
+
+const exitCode = await runCli(process.argv.slice(2));
+
+if (typeof exitCode === 'number' && exitCode !== 0) {
+  process.exit(exitCode);
+}

package/commands/brainstorm.md

@@ -0,0 +1,44 @@
+---
+description: "Starts Migration or Full Delivery design exploration with the brainstorming skill."
+---
+
+# Command: `/brainstorm`
+
+Use `/brainstorm` when work is already in `Migration` or `Full Delivery` mode and the team needs to refine design direction before implementation planning.
+
+## Preconditions
+
+- The current `mode` must be `full` or `migration`
+- The work needs design clarification, product exploration, architecture framing, or upgrade strategy exploration before plan execution
+- If work is resuming, the current state must be readable before the session continues
+
+## Canonical docs to load
+
+- `AGENTS.md`
+- `context/navigation.md`
+- `context/core/workflow.md`
+- `context/core/project-config.md`
+- `.opencode/workflow-state.json` when resuming
+- skill `brainstorming`
+
+For operator checks, use the current workflow-state utility surface: `status`, `doctor`, `show`, and `validate`.
+
+## Expected action
+
+- Confirm the work is in `Migration` or `Full Delivery` mode before starting brainstorming
+- Use the brainstorming skill to explore the problem, compare approaches, and converge on a design
+- In migration mode, use brainstorming to identify preserved invariants, migration blockers, seams, adapters, and slice boundaries before implementation planning
+- Create or refine the appropriate artifact for the active mode only when the skill outcome requires it
+- Point back to `context/core/workflow.md` for stage order, approvals, and escalation rules instead of restating them here
+
+## Rejection or escalation behavior
+
+- If the work is still in the quick lane, stop and escalate into `Migration` or `Full Delivery` before using this command
+- If the request is too incomplete to brainstorm safely, stop and ask for the missing context instead of fabricating direction
+- Do not use this command to imply an alternate workflow or any live parallel execution feature that the repository does not currently document
+
+## Validation guidance
+
+- Use `node .opencode/workflow-state.js show` or `node .opencode/workflow-state.js validate` when resumable state needs confirmation
+- Brainstorming output is design and workflow evidence, not app build/lint/test evidence
+- If the repository has no app-native validation commands for the eventual implementation, record that constraint honestly in downstream artifacts

package/commands/delivery.md

@@ -0,0 +1,45 @@
+---
+description: "Starts the Full Delivery lane for feature work and higher-risk changes."
+---
+
+# Command: `/delivery`
+
+Use `/delivery` when work needs the full lane from the start or when quick or migration work has already escalated.
+
+## Preconditions
+
+- The request satisfies one or more full-lane triggers in `context/core/workflow.md`
+- If this is resumed work, escalation context or the current full stage must be read from workflow state before continuing
+
+## Canonical docs to load
+
+- `AGENTS.md`
+- `context/navigation.md`
+- `context/core/workflow.md`
+- `context/core/lane-selection.md`
+- `context/core/approval-gates.md`
+- `context/core/project-config.md`
+- `.opencode/workflow-state.json` when resuming
+
+For operator checks, use the current workflow-state utility surface: `status`, `doctor`, `show`, and `validate`.
+
+## Expected action
+
+- The Master Orchestrator records `mode = full` and `mode_reason`
+- Initialize `full_intake`
+- Route to the PM Agent to begin the Full Delivery chain defined in `context/core/workflow.md`
+- Track approval gates in workflow state before each stage advance
+- Use this lane when the dominant uncertainty is product behavior, requirements, or cross-boundary solution design rather than compatibility modernization
+
+## Rejection or escalation behavior
+
+- If the command is entered from an active quick or migration context, preserve escalation metadata while moving into `full_intake`
+- If the command explicitly asks for full mode but the routing profile still shows behavior-preserving modernization with compatibility uncertainty, reject full admission and reroute to migration instead of silently widening the lane
+- If required full-mode context is missing or state is contradictory, stop at intake and report the mismatch instead of skipping a stage
+- Do not create a new lane, new stage, or alternate full-entry chain outside the canonical workflow doc
+
+## Validation guidance
+
+- Use `node .opencode/workflow-state.js show` or `node .opencode/workflow-state.js validate` when resumable full-mode state needs confirmation
+- Keep implementation and QA validation honest to the repository's actual tooling
+- Do not overstate automation when the repository still lacks app-native build, lint, or test commands

package/commands/execute-plan.md

@@ -0,0 +1,44 @@
+---
+description: "Executes an approved Full Delivery or Migration implementation plan."
+---
+
+# Command: `/execute-plan`
+
+Use `/execute-plan` when an approved Full Delivery or Migration implementation plan is ready to be carried out.
+
+## Preconditions
+
+- The current `mode` must be `full` or `migration`
+- An approved plan exists in `docs/plans/` for the current work item
+- Any required upstream approvals for the active mode are already recorded in workflow state
+
+## Canonical docs to load
+
+- `AGENTS.md`
+- `context/navigation.md`
+- `context/core/workflow.md`
+- `context/core/project-config.md`
+- `context/core/session-resume.md`
+- `context/core/workflow-state-schema.md`
+- `.opencode/workflow-state.json`
+
+For operator checks, use the current workflow-state utility surface: `status`, `doctor`, `show`, and `validate`.
+
+## Expected action
+
+- Confirm the current state is compatible with implementation work for the active mode
+- Read the approved plan and execute it without redefining the canonical workflow rules
+- Use the real implementation workflow available in the repository; do not imply live parallel execution support beyond what the checked-in runtime documents today
+- Report the actual validation path taken for each meaningful change
+
+## Rejection or escalation behavior
+
+- If the work is still in quick mode, stop and route it into `Migration` or `Full Delivery` before using this command
+- If workflow state is invalid, contradictory, or missing required approvals, stop and correct state or inputs before implementation
+- If the plan is missing, stale, or unapproved, stop and send the work back to the planning step instead of improvising a new plan inline
+
+## Validation guidance
+
+- Run `node .opencode/workflow-state.js validate` when you need to confirm workflow-state integrity before execution
+- Use repo-native app build, lint, or test commands only if they actually exist and are documented
+- If the repository still lacks app-native validation tooling, report manual checks or other real evidence instead of inventing automation

package/commands/migrate.md

@@ -0,0 +1,61 @@
+---
+description: "Starts the Migration lane for upgrades, framework migrations, and dependency modernization."
+---
+
+# Command: `/migrate`
+
+Use `/migrate` when work is primarily a project migration or upgrade effort such as framework version jumps, dependency replacement, legacy API removal, or compatibility remediation.
+
+Core migration principle:
+
+- preserve behavior first, decouple blockers where necessary, and migrate incrementally instead of rewriting the product
+
+## Preconditions
+
+- The request is centered on upgrading or migrating an existing codebase rather than delivering a net-new feature
+- The work needs discovery of the current baseline, compatibility risks, and staged upgrade execution
+- The migration is expected to preserve existing layout, flows, contracts, and core logic unless an explicit exception is documented
+- If work is resuming, the current migration state must be readable before continuing
+- Product requirements are mostly known already, even if the technical upgrade path is still uncertain
+
+## Canonical docs to load
+
+- `AGENTS.md`
+- `context/navigation.md`
+- `context/core/workflow.md`
+- `context/core/lane-selection.md`
+- `context/core/approval-gates.md`
+- `context/core/project-config.md`
+- `docs/templates/migration-baseline-checklist.md`
+- `docs/templates/migration-verify-checklist.md`
+- `.opencode/workflow-state.json` when resuming
+
+For operator checks, use the current workflow-state utility surface: `status`, `doctor`, `show`, and `validate`.
+
+## Expected action
+
+- The Master Orchestrator records `mode = migration` and `mode_reason`
+- Initialize `migration_intake`
+- Route to the migration baseline and strategy stages defined in `context/core/workflow.md`
+- Freeze the preserved invariants before major edits, then identify only the framework-coupled blockers that must be decoupled
+- Use adapters, seams, or compatibility shims when they make the migration safer
+- Use `docs/templates/migration-baseline-checklist.md` during `migration_baseline` and `docs/templates/migration-verify-checklist.md` during `migration_verify`
+- If the team wants one living migration artifact, scaffold `migration_report` during `migration_baseline` or `migration_strategy`
+- Keep validation focused on baseline capture, compatibility evidence, staged execution, and regression checks rather than defaulting to TDD-first execution
+
+## Rejection or escalation behavior
+
+- If the request is actually bounded low-risk work, reject migration entry and reroute to the quick lane
+- If the request is actually a net-new feature or requirement-definition problem, reject migration entry and reroute to `full_intake`
+- If the command explicitly asks for migration but the routing profile points to `quick` or `full`, reject migration admission instead of preserving a contradictory lane
+- If migration work uncovers product or requirements ambiguity, preserve escalation metadata while moving into `full_intake`
+- If the proposed approach is effectively a rewrite instead of a behavior-preserving migration, stop and restate the migration slices before continuing
+- If the main uncertainty is product behavior rather than compatibility or modernization, stop using migration and reroute to `full`
+
+## Validation guidance
+
+- Prefer real build, test, codemod, type-check, smoke-test, and manual regression evidence from the target project
+- Prefer parity checks against the preserved baseline: screenshots, behavior notes, contracts, smoke paths, and targeted regression evidence
+- Prefer `migration_report` when baseline notes, execution log, and verification evidence need to stay in one continuously updated file
+- If repository-native validation commands do not exist, record the missing validation path and the baseline evidence honestly
+- Do not claim TDD-first validation for migration work unless the migration plan explicitly identifies a safe test-first sub-slice with working tooling

package/commands/quick-task.md

@@ -0,0 +1,45 @@
+---
+description: "Starts the Quick Task lane for narrow, low-risk work."
+---
+
+# Command: `/quick-task`
+
+Use `/quick-task` when the user wants to enter the quick lane directly for bounded small-to-medium work that stays within the quick-lane limits, remains lower risk, and uses a short verification path.
+
+## Preconditions
+
+- The request must satisfy quick-lane criteria in `context/core/workflow.md`
+- If work is resuming, the current state must be compatible with continuing quick work or starting a new task
+
+## Canonical docs to load
+
+- `AGENTS.md`
+- `context/navigation.md`
+- `context/core/workflow.md`
+- `context/core/lane-selection.md`
+- `context/core/project-config.md`
+- `.opencode/workflow-state.json` when resuming
+
+For operator checks, use the current workflow-state utility surface: `status`, `doctor`, `show`, and `validate`.
+
+## Expected action
+
+- The Master Orchestrator confirms quick eligibility
+- Record `mode = quick` and `mode_reason`
+- Initialize `quick_intake`, prepare the quick intake context, then advance to `quick_plan`
+- Once the required `quick_plan` context is ready, route into `quick_build` with the Fullstack Agent
+- Create an optional task card only when traceability is genuinely useful
+- Reject quick entry if compatibility or modernization risk is the dominant reason the user asked for the work
+
+## Rejection or escalation behavior
+
+- If the request does not meet quick criteria, reject quick entry and reroute through `migration_intake` or `full_intake` based on the canonical workflow rules
+- If the command explicitly asks for quick mode but the routing profile would classify the work as `migration` or `full`, reject quick admission instead of silently keeping the wrong lane
+- If an escalation condition appears during the quick loop, the Master Orchestrator must switch the work into `full_intake`
+- If useful for operator clarity, explain that the work now belongs in Full Delivery without redefining the command surface
+
+## Validation guidance
+
+- Keep quick-task validation short and real, following `context/core/project-config.md`
+- If no app-native test or lint command exists, document the manual or artifact-based verification path clearly
+- Use `node .opencode/workflow-state.js validate` only for workflow-state checks, not as a substitute for application testing

package/commands/task.md

@@ -0,0 +1,46 @@
+---
+description: "Default entry command. Lets the Master Orchestrator classify work into Quick Task, Migration, or Full Delivery."
+---
+
+# Command: `/task`
+
+Use `/task` when the user wants the default entrypoint and expects the Master Orchestrator to choose the lane.
+
+## Preconditions
+
+- A user request exists with enough information to summarize the initial goal, scope, and risk
+- If the workflow is resuming, the current workflow state must be readable before rerouting
+
+## Canonical docs to load
+
+- `AGENTS.md`
+- `context/navigation.md`
+- `context/core/workflow.md`
+- `context/core/lane-selection.md`
+- `context/core/project-config.md`
+- `.opencode/workflow-state.json` when resuming
+
+For operator checks, use the current workflow-state utility surface: `status`, `doctor`, `show`, and `validate`.
+
+## Expected action
+
+- The Master Orchestrator chooses `quick`, `migration`, or `full` using the canonical workflow rules
+- Record `mode` and `mode_reason` in workflow state
+- If the task enters the quick lane, initialize quick intake context and continue through the canonical quick stage chain
+- If the task enters the migration lane, initialize `migration_intake` and continue through the canonical migration stage chain
+- If the task enters the full lane, initialize `full_intake` and route to the PM agent
+- When choosing migration, prefer a behavior-preserving path that decouples blockers before changing the stack broadly
+- Use the lane tie-breaker from `context/core/workflow.md`: product ambiguity goes to `full`, compatibility uncertainty with preserved behavior goes to `migration`, and only bounded low-risk work goes to `quick`
+
+## Rejection or escalation behavior
+
+- If the request is ambiguous because product behavior, requirements, or acceptance are unclear, route it to `Full Delivery` per `context/core/workflow.md`
+- If the request is uncertain mainly because of upgrade or compatibility risk while the target behavior is already known, route it to `Migration`
+- If the request is too incomplete to open even `full_intake`, stop at intake and ask for clarification instead of guessing
+- If the quick lane is not appropriate under `context/core/workflow.md`, route directly to the migration or full lane that best matches the request
+
+## Validation guidance
+
+- Use `node .opencode/workflow-state.js status` or `node .opencode/workflow-state.js show` to inspect resumable state before rerouting when needed
+- Use `node .opencode/workflow-state.js validate` if the saved state looks stale or manually edited
+- Do not imply repo-native app build, lint, or test commands exist when this repository has not defined them

package/commands/write-plan.md

@@ -0,0 +1,50 @@
+---
+description: "Triggers the writing-plans skill to create bite-sized tasks from specs."
+---
+
+# Command: `/write-plan`
+
+Use `/write-plan` to create an implementation plan for work currently in `Full Delivery` or `Migration` mode.
+
+## Preconditions
+
+- The current `mode` must be `full` or `migration`
+- The required architecture artifact already exists for the current work item
+- If the work is in `full`, the required spec artifact already exists for the current feature
+- The Tech Lead Agent is at the stage where `docs/plans/...` should be created
+
+## Canonical docs to load
+
+- `AGENTS.md`
+- `context/navigation.md`
+- `context/core/workflow.md`
+- `context/core/project-config.md`
+- `.opencode/workflow-state.json`
+- `docs/templates/implementation-plan-template.md`
+- `docs/templates/migration-report-template.md` when migration work benefits from one running artifact
+- skill `writing-plans`
+
+For operator checks, use the current workflow-state utility surface: `status`, `doctor`, `show`, and `validate`.
+
+## Expected action
+
+- Create or update `docs/plans/YYYY-MM-DD-<feature>.md`
+- Keep the plan aligned with the current stage and approval context for the active mode
+- In migration mode, record preserved invariants, seam or adapter steps, and parity checks explicitly
+- In migration mode, recommend scaffolding or updating `migration_report` when baseline, plan, execution, and verification should stay visible in one artifact
+- Record the real validation path, or a missing-validation-path note when the repository has no suitable command
+- Return the plan for review and approval through the canonical workflow for the active mode
+
+## Rejection or escalation behavior
+
+- If work is still in quick mode, reject this command and route the task into Migration or Full Delivery first
+- If required architecture input is incomplete, stop and require that upstream artifact before writing the plan
+- If work is in `full` and the spec input is incomplete, stop and require that upstream artifact before writing the plan
+- Do not use this command to open a new full lane implicitly or bypass the approval chain
+
+## Validation guidance
+
+- The plan should name the strongest real validation path available in the repository
+- In migration mode, use `migration_report` when handoffs would benefit from a single running narrative instead of scattered notes
+- If no repo-native app build, lint, or test command exists, say that explicitly in the plan instead of guessing a stack command
+- Use `node .opencode/workflow-state.js validate` only to confirm workflow state, not to stand in for implementation verification

package/context/core/approval-gates.md

@@ -0,0 +1,146 @@
+# Approval Gates
+
+This file defines how stage transitions are recorded and approved.
+
+For the canonical workflow contract, including lane semantics, stage order, and artifact expectations, use `context/core/workflow.md`.
+
+Approval behavior is mode-aware. `Quick Task`, `Migration`, and `Full Delivery` do not share the same gate set.
+
+## Gate States
+
+- `pending`: work exists but approval has not been granted
+- `approved`: transition may proceed
+- `rejected`: transition is blocked until feedback is addressed
+
+## Required Fields Per Gate
+
+Each gate entry mirrored in `.opencode/workflow-state.json` for the active work item must contain:
+
+- `status`
+- `approved_by`
+- `approved_at`
+- `notes`
+
+## Quick Task Gates
+
+Quick mode uses one required gate:
+
+- `quick_verified`
+
+Meaning:
+
+- the user request is treated as implicit approval to start quick work unless the task is ambiguous or risky
+- `quick_verified` becomes `approved` only after QA Lite passes
+- `QA Agent` is the approval authority for `quick_verified`
+- the builder may supply evidence and recommended disposition, but cannot self-approve the gate
+
+Transition rule:
+
+- `quick_verify -> quick_done` requires `quick_verified = approved`
+
+`quick_plan` does not add a second quick approval gate. It is a required planning stage, but quick-mode completion still depends on `quick_verified` after QA Lite passes.
+
+Readiness rule before `quick_verified` approval:
+
+- quick checklist and acceptance bullets are inspectable
+- intended verification path is inspectable
+- QA Lite evidence is inspectable in workflow state or session artifacts
+- unresolved design or requirement issues are escalated instead of approved through
+
+## Migration Gates
+
+Migration mode uses four required gates:
+
+- `baseline_to_strategy`
+- `strategy_to_upgrade`
+- `upgrade_to_verify`
+- `migration_verified`
+
+Meaning:
+
+- `baseline_to_strategy` confirms the baseline, compatibility map, and likely breakpoints are inspectable enough for staged planning
+- `strategy_to_upgrade` confirms the staged upgrade sequence, rollback checkpoints, and validation path are ready for execution
+- `upgrade_to_verify` confirms upgrade execution evidence is inspectable enough for regression and compatibility QA
+- `migration_verified` becomes `approved` only after regression, smoke, and compatibility verification are judged sufficient
+
+Approval authorities:
+
+- `baseline_to_strategy`: `Tech Lead Agent`
+- `strategy_to_upgrade`: `Fullstack Agent`
+- `upgrade_to_verify`: `QA Agent`
+- `migration_verified`: `QA Agent`
+
+Transition rules:
+
+- `migration_baseline -> migration_strategy` uses `baseline_to_strategy`
+- `migration_strategy -> migration_upgrade` uses `strategy_to_upgrade`
+- `migration_upgrade -> migration_verify` uses `upgrade_to_verify`
+- `migration_verify -> migration_done` uses `migration_verified`
+
+Readiness rule before migration approvals:
+
+- current baseline and target upgrade intent are inspectable
+- staged execution notes and rollback checkpoints are inspectable
+- validation evidence uses real project commands or honest manual evidence
+- requirement ambiguity is escalated to full delivery instead of being approved through migration
+
+## Full Delivery Gates
+
+Full mode keeps the explicit handoff chain:
+
+- `pm_to_ba`
+- `ba_to_architect`
+- `architect_to_tech_lead`
+- `tech_lead_to_fullstack`
+- `fullstack_to_qa`
+- `qa_to_done`
+
+Approval authorities:
+
+- `pm_to_ba`: `BA Agent`
+- `ba_to_architect`: `Architect Agent`
+- `architect_to_tech_lead`: `Tech Lead Agent`
+- `tech_lead_to_fullstack`: `Fullstack Agent`
+- `fullstack_to_qa`: `QA Agent`
+- `qa_to_done`: `MasterOrchestrator`
+
+Transition rules:
+
+- `full_brief -> full_spec` uses `pm_to_ba`
+- `full_spec -> full_architecture` uses `ba_to_architect`
+- `full_architecture -> full_plan` uses `architect_to_tech_lead`
+- `full_plan -> full_implementation` uses `tech_lead_to_fullstack`
+- `full_implementation -> full_qa` uses `fullstack_to_qa`
+- `full_qa -> full_done` uses `qa_to_done`
+
+Readiness checklist for every full-delivery gate:
+
+- the outgoing stage artifact or evidence exists and is inspectable
+- unresolved assumptions, risks, and open questions are called out in notes
+- the receiving role has enough detail to begin without reconstructing missing intent
+- the approver records approval notes or rejection notes in workflow state
+
+Boundary-specific handoff focus:
+
+- `pm_to_ba`: problem statement, goals, constraints, and product unknowns are clear
+- `ba_to_architect`: scope, behaviors, and acceptance expectations are clear
+- `architect_to_tech_lead`: design decisions, boundaries, and dependencies are clear
+- `tech_lead_to_fullstack`: execution steps, sequencing, and validation expectations are clear
+- `fullstack_to_qa`: implementation evidence, changed surfaces, and known limitations are clear
+- `qa_to_done`: verification outcome, remaining issue status, and closure recommendation are clear
+
+## Operational Rule
+
+Do not advance the active work item stage, and do not refresh `.opencode/workflow-state.json`, until the matching gate for the active mode is `approved`.
+
+Do not mark a gate `approved` when the evidence is missing, not inspectable, or relies on unstated conversation context.
+
+## Escalation Rule
+
+When quick or migration work escalates to full delivery:
+
+- do not try to reuse quick or migration gates as full-delivery approvals
+- record the escalation metadata in state
+- initialize the full-delivery approval chain with pending values
+
+This escalation behavior remains unchanged in the current live contract.