@duypham93/openkit 0.2.2 → 0.2.4

package/README.md

@@ -85,6 +85,22 @@ Preferred global path:
 4. Run `openkit upgrade` to refresh the installed global kit when a newer package version is available.
 5. Run `openkit uninstall [--remove-workspaces]` when you need to remove the global kit and optionally clear workspace state.
 
+Inside the OpenCode session opened by `openkit run`, OpenKit defaults to the `master-orchestrator` agent. Use `Ctrl+P` to open the command palette and run OpenKit commands like `/task`, `/quick-task`, `/migrate`, or `/delivery`.
+
+Quickstart:
+
+```bash
+npm install -g @duypham93/openkit
+openkit run
+```
+
+First session:
+
+1. Wait for OpenCode to open with the `master-orchestrator` agent.
+2. Press `Ctrl+P` to open the command palette.
+3. Run `/task` for the safest default entrypoint.
+4. Use `/quick-task`, `/migrate`, or `/delivery` only when you already know the right lane.
+
 In this worktree today:
 
 - the global install path is implemented for the `openkit` CLI and is now the preferred user experience.

package/agents/architect-agent.md

@@ -1,5 +1,4 @@
 ---
-name: ArchitectAgent
 description: "System Architect agent. Converts an approved spec into an architecture decision package that is ready for planning."
 mode: subagent
 ---
@@ -8,6 +7,11 @@ mode: subagent
 
 You are the System Architect for OpenKit full-delivery and migration work. `context/core/workflow.md` defines lane semantics and approval flow; this file defines only the runtime contract for `ArchitectAgent`.
 
+## Global runtime path rule
+
+- In globally installed OpenKit sessions, resolve OpenKit-owned context and templates from `OPENKIT_KIT_ROOT` instead of assuming the target repository contains `context/`, `docs/templates/`, or `.opencode/`.
+- Resolve workflow state from `OPENKIT_WORKFLOW_STATE` when resuming or validating handoff context.
+
 ## Required Inputs
 
 - approved requirements spec at `docs/specs/YYYY-MM-DD-<feature>.md`

package/agents/ba-agent.md

@@ -1,5 +1,4 @@
 ---
-name: BAAgent
 description: "Business Analyst agent. Converts an approved brief into a requirements spec with clear acceptance criteria and edge cases."
 mode: subagent
 ---
@@ -8,6 +7,11 @@ mode: subagent
 
 You are the Business Analyst for OpenKit full-delivery work. `context/core/workflow.md` defines lane behavior, stage order, and approvals; this file defines only the runtime contract for `BAAgent`.
 
+## Global runtime path rule
+
+- In globally installed OpenKit sessions, resolve OpenKit-owned context and templates from `OPENKIT_KIT_ROOT` instead of assuming the target repository contains `context/`, `docs/templates/`, or `.opencode/`.
+- Resolve workflow state from `OPENKIT_WORKFLOW_STATE` when resuming or validating handoff context.
+
 ## Required Inputs
 
 - approved product brief at `docs/briefs/YYYY-MM-DD-<feature>.md`

package/agents/code-reviewer.md

@@ -1,5 +1,4 @@
 ---
-name: CodeReviewer
 description: "Code reviewer subagent. Two-stage review: spec compliance first, then code quality. Dispatched by Fullstack Agent."
 mode: subagent
 permission:
@@ -13,6 +12,11 @@ permission:
 
 You are the Code Reviewer subagent, dispatched by the Fullstack Agent. You perform a two-stage review: spec compliance first, code quality second.
 
+## Global runtime path rule
+
+- In globally installed OpenKit sessions, resolve OpenKit-owned context from `OPENKIT_KIT_ROOT` instead of assuming the target repository contains `context/` or `.opencode/`.
+- Resolve workflow state from `OPENKIT_WORKFLOW_STATE` when resumable review context is needed.
+
 ## Important
 
 You are **stateless** - you do not carry context from previous sessions. The Fullstack Agent will provide all required context in the prompt.

package/agents/fullstack-agent.md

@@ -1,5 +1,4 @@
 ---
-name: FullstackAgent
 description: "Implementation specialist. Executes quick tasks directly and full-delivery work from approved plans with strong validation discipline."
 mode: subagent
 permission:
@@ -16,6 +15,12 @@ permission:
 
 You are the implementation specialist for OpenKit. `context/core/workflow.md` defines lane behavior and stage order; this file describes only the execution contract for `FullstackAgent` in each mode.
 
+## Global runtime path rule
+
+- In globally installed OpenKit sessions, resolve OpenKit-owned context from `OPENKIT_KIT_ROOT` instead of assuming the target repository contains `context/` or `.opencode/`.
+- Resolve workflow state from `OPENKIT_WORKFLOW_STATE` when resumable execution context is needed.
+- Use the target repository only for implementation work and project-native validation commands.
+
 ## Shared Responsibilities
 
 - Read `context/core/code-quality.md`, `context/core/workflow.md`, and `context/core/project-config.md` before implementing

package/agents/master-orchestrator.md

@@ -1,5 +1,4 @@
 ---
-name: MasterOrchestrator
 description: "Central brain of the AI Software Factory. Chooses workflow lane, routes tasks between agents, manages feedback loops, and classifies QA errors."
 mode: primary
 ---
@@ -8,6 +7,14 @@ mode: primary
 
 You are the coordinator for OpenKit. `context/core/workflow.md` is the canonical source for lane semantics, stage order, escalation rules, approval rules, and the quick/migration/full contract. This file keeps only `MasterOrchestrator` responsibilities.
 
+## Global runtime path rule
+
+- In globally installed OpenKit sessions, do not assume the target repository contains OpenKit kit files such as `AGENTS.md`, `context/`, `docs/templates/`, or `.opencode/`.
+- Resolve canonical OpenKit files under `OPENKIT_KIT_ROOT`. For example, `context/core/workflow.md` means `${OPENKIT_KIT_ROOT}/context/core/workflow.md`.
+- Resolve workflow state from `OPENKIT_WORKFLOW_STATE`.
+- For workflow-state CLI operations in global mode, use `node "${OPENKIT_KIT_ROOT}/.opencode/workflow-state.js" --state "${OPENKIT_WORKFLOW_STATE}" <command>`.
+- Use the target repository only for application code, project docs, and project-native validation paths.
+
 ## Core Responsibilities
 
 ### Lane selection ownership

package/agents/pm-agent.md

@@ -1,5 +1,4 @@
 ---
-name: PMAgent
 description: "Product Manager agent. Converts user intent into an approval-ready product brief for full-delivery work."
 mode: subagent
 ---
@@ -8,6 +7,11 @@ mode: subagent
 
 You are the Product Manager for OpenKit full-delivery work. `context/core/workflow.md` defines lane selection, stage order, and approval gates; this file defines only the runtime contract for `PMAgent`.
 
+## Global runtime path rule
+
+- In globally installed OpenKit sessions, resolve OpenKit-owned context and templates from `OPENKIT_KIT_ROOT` instead of assuming the target repository contains `context/`, `docs/templates/`, or `.opencode/`.
+- Resolve workflow state from `OPENKIT_WORKFLOW_STATE` when resuming or validating handoff context.
+
 ## Required Inputs
 
 - full-delivery intake from `MasterOrchestrator`

package/agents/qa-agent.md

@@ -1,5 +1,4 @@
 ---
-name: QAAgent
 description: "Quality Assurance agent. Runs QA Lite for quick tasks, migration QA for upgrades, and full QA for delivery work, classifying issues for feedback routing."
 mode: subagent
 permission:
@@ -15,6 +14,12 @@ permission:
 
 You are the QA engineer for OpenKit. `context/core/workflow.md` keeps the canonical lane semantics; this file describes only the QA contract, evidence expectations, and mode-specific behavior deltas. QA validates, classifies, and reports; it does not fix code.
 
+## Global runtime path rule
+
+- In globally installed OpenKit sessions, resolve OpenKit-owned context and templates from `OPENKIT_KIT_ROOT` instead of assuming the target repository contains `context/`, `docs/templates/`, or `.opencode/`.
+- Resolve workflow state from `OPENKIT_WORKFLOW_STATE` when resumable QA context is needed.
+- Use the target repository only for implementation evidence, validation commands, and project-specific artifacts.
+
 ## Shared Responsibilities
 
 - Receive completed implementation context through `MasterOrchestrator`

package/agents/tech-lead-agent.md

@@ -1,5 +1,4 @@
 ---
-name: TechLeadAgent
 description: "Tech Lead agent. Converts approved architecture into an execution-ready implementation plan and planning handoff."
 mode: subagent
 ---
@@ -8,6 +7,11 @@ mode: subagent
 
 You are the Tech Lead for OpenKit full-delivery and migration work. `context/core/workflow.md` defines lane behavior, stage order, and approvals; this file defines only the runtime contract for `TechLeadAgent`.
 
+## Global runtime path rule
+
+- In globally installed OpenKit sessions, resolve OpenKit-owned context and templates from `OPENKIT_KIT_ROOT` instead of assuming the target repository contains `context/`, `docs/templates/`, or `.opencode/`.
+- Resolve workflow state from `OPENKIT_WORKFLOW_STATE` when resuming or validating handoff context.
+
 ## Required Inputs
 
 - approved architecture document at `docs/architecture/YYYY-MM-DD-<feature>.md`

package/assets/install-bundle/opencode/agents/ArchitectAgent.md

@@ -1,5 +1,4 @@
 ---
-name: ArchitectAgent
 description: "System Architect agent. Converts an approved spec into an architecture decision package that is ready for planning."
 mode: subagent
 ---

package/assets/install-bundle/opencode/agents/BAAgent.md

@@ -1,5 +1,4 @@
 ---
-name: BAAgent
 description: "Business Analyst agent. Converts an approved brief into a requirements spec with clear acceptance criteria and edge cases."
 mode: subagent
 ---

package/assets/install-bundle/opencode/agents/CodeReviewer.md

@@ -1,5 +1,4 @@
 ---
-name: CodeReviewer
 description: "Code reviewer subagent. Two-stage review: spec compliance first, then code quality. Dispatched by Fullstack Agent."
 mode: subagent
 permission:

package/assets/install-bundle/opencode/agents/FullstackAgent.md

@@ -1,5 +1,4 @@
 ---
-name: FullstackAgent
 description: "Implementation specialist. Executes quick tasks directly and full-delivery work from approved plans with strong validation discipline."
 mode: subagent
 permission:

package/assets/install-bundle/opencode/agents/MasterOrchestrator.md

@@ -1,5 +1,4 @@
 ---
-name: MasterOrchestrator
 description: "Central brain of the AI Software Factory. Chooses workflow lane, routes tasks between agents, manages feedback loops, and classifies QA errors."
 mode: primary
 ---

package/assets/install-bundle/opencode/agents/PMAgent.md

@@ -1,5 +1,4 @@
 ---
-name: PMAgent
 description: "Product Manager agent. Converts user intent into an approval-ready product brief for full-delivery work."
 mode: subagent
 ---

package/assets/install-bundle/opencode/agents/QAAgent.md

@@ -1,5 +1,4 @@
 ---
-name: QAAgent
 description: "Quality Assurance agent. Runs QA Lite for quick tasks, migration QA for upgrades, and full QA for delivery work, classifying issues for feedback routing."
 mode: subagent
 permission:

package/assets/install-bundle/opencode/agents/TechLeadAgent.md

@@ -1,5 +1,4 @@
 ---
-name: TechLeadAgent
 description: "Tech Lead agent. Converts approved architecture into an execution-ready implementation plan and planning handoff."
 mode: subagent
 ---

package/commands/brainstorm.md

@@ -6,6 +6,12 @@ description: "Starts Migration or Full Delivery design exploration with the brai
 
 Use `/brainstorm` when work is already in `Migration` or `Full Delivery` mode and the team needs to refine design direction before implementation planning.
 
+## Global OpenKit path rule
+
+- In globally installed OpenKit sessions, resolve OpenKit-owned docs from `OPENKIT_KIT_ROOT` instead of assuming the target repository contains `AGENTS.md`, `context/`, or `.opencode/`.
+- Resolve resumable workflow state from `OPENKIT_WORKFLOW_STATE`.
+- Use `node "${OPENKIT_KIT_ROOT}/.opencode/workflow-state.js" --state "${OPENKIT_WORKFLOW_STATE}" <command>` for workflow-state checks in global mode.
+
 ## Preconditions
 
 - The current `mode` must be `full` or `migration`
@@ -39,6 +45,6 @@ For operator checks, use the current workflow-state utility surface: `status`, `
 
 ## Validation guidance
 
-- Use `node .opencode/workflow-state.js show` or `node .opencode/workflow-state.js validate` when resumable state needs confirmation
+- Use the workflow-state utility against `OPENKIT_WORKFLOW_STATE` 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

@@ -6,6 +6,13 @@ description: "Starts the Full Delivery lane for feature work and higher-risk cha
 
 Use `/delivery` when work needs the full lane from the start or when quick or migration work has already escalated.
 
+## Global OpenKit path rule
+
+- In globally installed OpenKit sessions, resolve OpenKit-owned docs from `OPENKIT_KIT_ROOT` instead of assuming the target repository contains `AGENTS.md`, `context/`, or `.opencode/`.
+- For example, `context/core/workflow.md` means `${OPENKIT_KIT_ROOT}/context/core/workflow.md`.
+- Resolve resumable workflow state from `OPENKIT_WORKFLOW_STATE`.
+- Use `node "${OPENKIT_KIT_ROOT}/.opencode/workflow-state.js" --state "${OPENKIT_WORKFLOW_STATE}" <command>` for workflow-state checks in global mode.
+
 ## Preconditions
 
 - The request satisfies one or more full-lane triggers in `context/core/workflow.md`
@@ -40,6 +47,6 @@ For operator checks, use the current workflow-state utility surface: `status`, `
 
 ## Validation guidance
 
-- Use `node .opencode/workflow-state.js show` or `node .opencode/workflow-state.js validate` when resumable full-mode state needs confirmation
+- Use the workflow-state utility against `OPENKIT_WORKFLOW_STATE` 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

@@ -6,6 +6,12 @@ description: "Executes an approved Full Delivery or Migration implementation pla
 
 Use `/execute-plan` when an approved Full Delivery or Migration implementation plan is ready to be carried out.
 
+## Global OpenKit path rule
+
+- In globally installed OpenKit sessions, resolve OpenKit-owned docs from `OPENKIT_KIT_ROOT` instead of assuming the target repository contains `AGENTS.md`, `context/`, `docs/`, or `.opencode/`.
+- Resolve resumable workflow state from `OPENKIT_WORKFLOW_STATE`.
+- Use `node "${OPENKIT_KIT_ROOT}/.opencode/workflow-state.js" --state "${OPENKIT_WORKFLOW_STATE}" <command>` for workflow-state checks in global mode.
+
 ## Preconditions
 
 - The current `mode` must be `full` or `migration`
@@ -39,6 +45,6 @@ For operator checks, use the current workflow-state utility surface: `status`, `
 
 ## Validation guidance
 
-- Run `node .opencode/workflow-state.js validate` when you need to confirm workflow-state integrity before execution
+- Run the workflow-state utility against `OPENKIT_WORKFLOW_STATE` 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

@@ -6,6 +6,13 @@ description: "Starts the Migration lane for upgrades, framework migrations, and
 
 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.
 
+## Global OpenKit path rule
+
+- In globally installed OpenKit sessions, resolve OpenKit-owned docs from `OPENKIT_KIT_ROOT` instead of assuming the target repository contains `AGENTS.md`, `context/`, `docs/templates/`, or `.opencode/`.
+- For example, `context/core/workflow.md` means `${OPENKIT_KIT_ROOT}/context/core/workflow.md`, and `docs/templates/migration-baseline-checklist.md` means `${OPENKIT_KIT_ROOT}/docs/templates/migration-baseline-checklist.md`.
+- Resolve resumable workflow state from `OPENKIT_WORKFLOW_STATE`.
+- Use `node "${OPENKIT_KIT_ROOT}/.opencode/workflow-state.js" --state "${OPENKIT_WORKFLOW_STATE}" <command>` for workflow-state checks in global mode.
+
 Core migration principle:
 
 - preserve behavior first, decouple blockers where necessary, and migrate incrementally instead of rewriting the product

package/commands/quick-task.md

@@ -6,6 +6,13 @@ description: "Starts the Quick Task lane for narrow, low-risk work."
 
 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.
 
+## Global OpenKit path rule
+
+- In globally installed OpenKit sessions, treat `AGENTS.md`, `context/`, `docs/`, and `.opencode/` as kit-owned assets under `OPENKIT_KIT_ROOT`, not as files in the target repository.
+- Resolve canonical docs like `context/core/workflow.md` as `${OPENKIT_KIT_ROOT}/context/core/workflow.md`.
+- Resolve resumable workflow state from `OPENKIT_WORKFLOW_STATE`.
+- Use `node "${OPENKIT_KIT_ROOT}/.opencode/workflow-state.js" --state "${OPENKIT_WORKFLOW_STATE}" <command>` for workflow-state checks in global mode.
+
 ## Preconditions
 
 - The request must satisfy quick-lane criteria in `context/core/workflow.md`
@@ -42,4 +49,4 @@ For operator checks, use the current workflow-state utility surface: `status`, `
 
 - 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
+- Use the workflow-state utility against `OPENKIT_WORKFLOW_STATE` only for workflow-state checks, not as a substitute for application testing

package/commands/task.md

@@ -6,6 +6,14 @@ description: "Default entry command. Lets the Master Orchestrator classify work
 
 Use `/task` when the user wants the default entrypoint and expects the Master Orchestrator to choose the lane.
 
+## Global OpenKit path rule
+
+- In globally installed OpenKit sessions, do not assume the target repository contains `AGENTS.md`, `context/`, `docs/`, or `.opencode/` from the OpenKit kit.
+- Resolve canonical OpenKit docs under the absolute kit root from `OPENKIT_KIT_ROOT`. For example, `context/core/workflow.md` means `${OPENKIT_KIT_ROOT}/context/core/workflow.md`.
+- Resolve workflow state from `OPENKIT_WORKFLOW_STATE`, not from the target repository, unless you are intentionally operating inside the OpenKit repository itself.
+- For workflow-state CLI operations in global mode, use `node "${OPENKIT_KIT_ROOT}/.opencode/workflow-state.js" --state "${OPENKIT_WORKFLOW_STATE}" <command>`.
+- Use the target repository only for product/application code, local build tooling, and project-specific docs.
+
 ## Preconditions
 
 - A user request exists with enough information to summarize the initial goal, scope, and risk
@@ -41,6 +49,6 @@ For operator checks, use the current workflow-state utility surface: `status`, `
 
 ## 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
+- Use the workflow-state utility against `OPENKIT_WORKFLOW_STATE` to inspect resumable state before rerouting when needed
+- Use the workflow-state utility against `OPENKIT_WORKFLOW_STATE` to validate stale or manually edited state when needed
 - Do not imply repo-native app build, lint, or test commands exist when this repository has not defined them

package/commands/write-plan.md

@@ -6,6 +6,12 @@ description: "Triggers the writing-plans skill to create bite-sized tasks from s
 
 Use `/write-plan` to create an implementation plan for work currently in `Full Delivery` or `Migration` mode.
 
+## Global OpenKit path rule
+
+- In globally installed OpenKit sessions, resolve OpenKit-owned docs and templates from `OPENKIT_KIT_ROOT` instead of assuming the target repository contains `AGENTS.md`, `context/`, `docs/templates/`, or `.opencode/`.
+- Resolve resumable workflow state from `OPENKIT_WORKFLOW_STATE`.
+- Use `node "${OPENKIT_KIT_ROOT}/.opencode/workflow-state.js" --state "${OPENKIT_WORKFLOW_STATE}" <command>` for workflow-state checks in global mode.
+
 ## Preconditions
 
 - The current `mode` must be `full` or `migration`
@@ -47,4 +53,4 @@ For operator checks, use the current workflow-state utility surface: `status`, `
 - 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
+- Use the workflow-state utility against `OPENKIT_WORKFLOW_STATE` only to confirm workflow state, not to stand in for implementation verification

package/docs/operations/internal-records/2026-03-24-release-checklist.md

@@ -1,4 +1,4 @@
-# OpenKit 0.2.1 Release Checklist
+# OpenKit 0.2.3 Release Checklist
 
 Date: 2026-03-24
 
@@ -11,7 +11,7 @@ Date: 2026-03-24
 
 ## Pre-Publish
 
-- confirm `package.json` version is `0.2.1`
+- confirm `package.json` version is `0.2.3`
 - confirm docs describe `npm install -g @duypham93/openkit` and `openkit run` as the preferred path
 - confirm release note draft is up to date in `docs/operations/internal-records/2026-03-24-simplified-install-ux.md`
 - run:
@@ -26,13 +26,14 @@ node --test tests/cli/openkit-cli.test.js tests/global/*.test.js tests/runtime/*
 npm pack
 ```
 
-- verify the tarball name is `duypham93-openkit-0.2.1.tgz`
+- verify the tarball name is `duypham93-openkit-0.2.3.tgz`
 
 ## Local Smoke Test
 
 - install the tarball into a temporary prefix
 - verify `openkit --help` shows the new quickstart
 - verify `openkit run` performs first-time setup and hands off to `opencode`
+- verify the materialized kit can load the `master-orchestrator` agent and OpenKit commands through the OpenCode config directory
 
 ## Publish
 
@@ -40,7 +41,7 @@ npm pack
 - publish the package from the repository root:
 
 ```bash
-npm publish
+npm publish --access public
 ```
 
 - if using the packed tarball path explicitly, publish the generated archive instead

package/docs/operator/README.md

@@ -17,9 +17,19 @@ Use it to find the right live docs quickly. Do not treat it as a canonical repla
 - Read `README.md` for the top-level product and runtime boundary summary
 - Read `docs/operations/runbooks/openkit-daily-usage.md` for the detailed day-to-day usage path in this repository
 - Install the CLI with `npm install -g @duypham93/openkit`, then run `openkit run` for first-time setup and `openkit doctor` to verify readiness
+- Once OpenCode is open, use `Ctrl+P` and choose `/task`, `/quick-task`, `/migrate`, or `/delivery` to enter the right workflow lane
 - Use `/task` unless you already know the work must start in `Quick Task`, `Migration`, or `Full Delivery`
 - Use `context/navigation.md` when you need to locate deeper workflow or standards references
 
+## Minimal First Session
+
+- `npm install -g @duypham93/openkit`
+- `openkit run`
+- Wait for OpenCode to open with `master-orchestrator`
+- Press `Ctrl+P`
+- Run `/task <what you want to do>`
+- Fall back to `/quick-task`, `/migrate`, or `/delivery` only when the lane is obvious
+
 ## Operator Routes
 
 - Workflow contract: `context/core/workflow.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duypham93/openkit",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "files": [
     ".opencode/",