@duypham93/openkit 0.2.0

package/docs/governance/README.md

@@ -0,0 +1,25 @@
+# Governance
+
+This directory defines durable policy for naming, severity, ADR usage, and definition of done.
+
+Use these documents to keep OpenKit maintainable as a reusable operating kit rather than a pile of one-off workflow notes.
+
+Current governance surface:
+
+- `naming-conventions.md`: filename, slug, and durable ID rules for workflow artifacts
+- `severity-levels.md`: issue severity language used by QA and rework routing
+- `adr-policy.md`: when to record a durable architecture decision
+- `definition-of-done.md`: minimum completion criteria for the current workflow contract
+
+Current-state guardrails:
+
+- Govern the live lane contract: `Quick Task`, `Migration`, and `Full Delivery`.
+- Treat `Quick Task+` as the live successor semantics of the existing quick lane, not as a third live mode or naming scheme.
+- Keep artifact names aligned with the directories and examples that actually exist in the repository.
+- Do not require build, lint, or test evidence that the repository has not adopted yet; when tooling is absent, require honest verification notes instead.
+- When runtime commands, workflow-state fields, or checked-in templates change, update the related smoke tests and operator docs in the same change.
+
+Maintainer note:
+
+- When runtime commands, workflow state fields, or artifact expectations change, update the relevant governance docs in the same change so policy stays aligned with the repository's real behavior.
+- When a change updates canonical workflow semantics, also review `doctor` consistency checks and any examples that act as runtime walkthroughs.

package/docs/governance/adr-policy.md

@@ -0,0 +1,27 @@
+# ADR Policy
+
+Create an ADR when a decision changes architecture boundaries, technology choices, or long-term operational behavior.
+
+For the profile/install-manifest layer, create an ADR when a change does any of the following:
+
+- changes the meaning or schema of `registry.json` or `.opencode/install-manifest.json`
+- changes the long-term semantics of profile selection, profile composition, or install-manifest ownership
+- adds, removes, or renames workflow-state CLI commands that operators rely on for runtime inspection or manifest management
+- changes session-start or runtime diagnostics in a way that materially affects how maintainers inspect or resume the kit
+- changes scaffold-artifact semantics beyond the current narrow `task_card`/`plan` scope, or changes the required workflow-state prerequisites for scaffolded artifacts
+- introduces a new extension policy that changes how agents, skills, commands, hooks, artifacts, or anchor docs must be registered
+
+A lighter decision log is usually enough when the change only:
+
+- adds a new registry entry for an already-established component type
+- adds a new profile that only recombines existing component categories without changing command or schema behavior
+- clarifies operator-facing docs, smoke tests, or examples to match existing runtime behavior
+- updates naming, descriptions, or local guidance without changing the runtime contract
+- tightens scaffold command guardrails, tests, or docs without expanding the supported artifact kinds or changing workflow-state meaning
+
+## Minimum ADR Content
+
+- Context
+- Decision
+- Consequences
+- Alternatives considered

package/docs/governance/definition-of-done.md

@@ -0,0 +1,17 @@
+# Definition Of Done
+
+A work item is only done when:
+
+1. The required artifact for the current stage exists.
+2. The relevant approval gate is recorded.
+3. Implementation and QA evidence are attached when code changes exist.
+4. Open critical and high issues are resolved.
+5. Workflow state reflects the final stage accurately.
+6. Handoff and closure notes are inspectable enough for a later session to understand why the item was allowed to advance or close.
+
+Current-state notes:
+
+- In `Quick Task`, this means the `quick_plan` checklist, acceptance bullets, verification path, QA Lite evidence, and `quick_verified` approval are recorded honestly; it does not imply a full artifact chain.
+- In `Full Delivery`, this means the required stage artifacts, handoff readiness, and approvals exist for the live full-delivery contract.
+- If the repository has no build, lint, or test tooling for the work, done status requires explicit reporting of the real verification path rather than invented automation claims.
+- Runtime or workflow maintenance work should leave the repository documentation aligned with any newly introduced commands or bootstrap behavior.

package/docs/governance/naming-conventions.md

@@ -0,0 +1,21 @@
+# Naming Conventions
+
+## Artifact Filenames
+
+- Use `YYYY-MM-DD-<slug>.md`
+- Keep slugs lowercase and hyphen-separated
+- Reuse the same slug across brief, spec, architecture, plan, and QA artifacts for one feature
+
+## IDs
+
+- Feature IDs use `FEATURE-###`
+- ADR IDs use `ADR-###`
+- QA issue IDs use `ISSUE-###`
+
+## Registry And Profile Metadata
+
+- Registry schemas use the form `openkit/<surface>@<version>`; current local metadata uses `openkit/component-registry@1` and `openkit/install-manifest@1`
+- Registry profile names use lowercase kebab-case such as `openkit-core`
+- Registry component IDs use `<category>.<slug>` such as `agent.master-orchestrator` or `command.quick-task`
+- Keep registry category names aligned with real checked-in repository surfaces, not planned future surfaces
+- Treat registry and install-manifest entries as local metadata describing this repository; do not name them as if they fetch remote packages

package/docs/governance/severity-levels.md

@@ -0,0 +1,12 @@
+# Severity Levels
+
+## Levels
+
+- `critical`: blocks release or risks security/data loss
+- `high`: breaks required behavior or approval criteria
+- `medium`: partial degradation or incorrect edge-case handling
+- `low`: minor quality issue that does not block workflow completion
+
+## Rule
+
+Critical and high issues block `qa_to_done` approval.

package/docs/maintainer/README.md

@@ -0,0 +1,51 @@
+# Maintainer Guide
+
+This directory is the maintainer-facing index layer for phase 1 information architecture.
+
+Use it to find canonical repository docs and upkeep surfaces quickly. Do not treat it as a canonical replacement for the docs it points to.
+
+## Phase-1 Authority Rule
+
+- this directory is an index, not a relocated source-of-truth layer
+- `AGENTS.md` remains the repository-wide rules and current-state guide
+- `context/core/workflow.md` remains the canonical live workflow-semantics document
+- companion operational details remain canonical in `context/core/`
+- governance, operations, and artifact docs remain canonical in their existing directories
+
+## Start Here
+
+- Read `AGENTS.md` first for repository rules, tooling caveats, and authority order
+- Read `context/navigation.md` next for context discovery across live docs and retained artifact surfaces
+- Read `context/core/project-config.md` when you need the maintained workflow-state command inventory
+
+## Maintainer Routes
+
+- Workflow semantics: `context/core/workflow.md`
+- Approval rules: `context/core/approval-gates.md`
+- Issue routing: `context/core/issue-routing.md`
+- Session resume: `context/core/session-resume.md`
+- Workflow-state schema: `context/core/workflow-state-schema.md`
+- Governance policy: `docs/governance/README.md`
+- Operations and diagnostics: `docs/operations/README.md`
+- Artifact guidance: `docs/briefs/README.md`, `docs/specs/README.md`, `docs/architecture/README.md`, `docs/plans/README.md`, `docs/qa/README.md`, `docs/adr/README.md`, `docs/templates/README.md`
+
+## Repository Internals To Keep Honest
+
+- `.opencode/opencode.json` remains the checked-in authoring and compatibility runtime manifest even though the preferred end-user install path is now global
+- `.opencode/workflow-state.json` remains the active compatibility mirror for the active work item
+- `.opencode/work-items/` remains the per-item backing store for managed runtime state
+- `registry.json` and `.opencode/install-manifest.json` remain additive local metadata, not destructive install machinery
+
+## Global Install Notes
+
+- The preferred end-user onboarding path is `npm install -g openkit` followed by `openkit run`.
+- The first `openkit run` materializes the managed kit into the OpenCode home directory automatically.
+- `openkit doctor` is the read-only check for the global install and workspace bootstrap state.
+- `openkit install-global`, `openkit install`, and `openkit init` remain available as manual or compatibility commands.
+- The package intentionally avoids npm `postinstall` side effects; setup happens inside the OpenKit CLI where failures and recovery steps are easier to explain.
+
+## Historical And Roadmap Notes
+
+- Most historical planning and archive docs were intentionally pruned from the working tree during cleanup.
+- Use git history when you need older rationale that is no longer kept as checked-in documentation.
+- If older guidance conflicts with checked-in runtime state, update docs to match reality rather than inventing missing infrastructure.

package/docs/operations/README.md

@@ -0,0 +1,79 @@
+# Operations
+
+This directory is the routing index for operational support docs.
+
+Use it to decide whether you need an executable runbook, an internal record, operator-facing routing, or lower-level runtime command details.
+
+This is an index layer for operations support, not a replacement for canonical workflow docs or audience routing.
+
+The current operations surface includes both the global OpenKit install path and the checked-in registry/install-manifest metadata used by this repository as an authoring and compatibility surface.
+
+## Directory Routes
+
+- `runbooks/README.md`: executable operator guidance and repeatable maintenance procedures
+- `internal-records/README.md`: durable project memory and lightweight record-keeping guidance
+- `docs/operator/README.md`: audience-facing operator routing before deeper operational detail
+- `docs/maintainer/README.md`: audience-facing maintainer routing before lower-level runtime detail
+
+## Key Docs
+
+- `runbooks/openkit-daily-usage.md`: detailed day-to-day usage guidance for the global install path plus the checked-in compatibility runtime
+- `runbooks/workflow-state-smoke-tests.md`: smoke checks for both the global install path and the workflow-state/session-start internals
+- `internal-records/README.md`: policy for when to keep a sparse durable operational record in-tree
+
+## Primary Operator Path
+
+Prefer the global install path first for everyday use. Use the checked-in repository/runtime path when maintaining or validating the authoring source in this repository.
+
+When OpenKit is installed globally, start with:
+
+- `npm install -g openkit`
+- `openkit run`
+- `openkit doctor` for global install readiness, drift, and missing-prerequisite checks
+- `openkit run <args>` for the supported global launcher path and first-time setup
+- `openkit upgrade` to refresh the global kit bundle
+- `openkit uninstall [--remove-workspaces]` to remove the global kit and optionally clear workspace state
+
+When the global layer is not installed or when you are maintaining the checked-in runtime itself, use the compatibility surface directly through `node .opencode/workflow-state.js ...` and the canonical docs under `context/core/`.
+
+## Lower-Level Runtime Command Surface
+
+Current repository/runtime command surface under the checked-in compatibility runtime:
+
+- inspection and diagnostics: `show`, `status`, `doctor`, `version`, `profiles`, `show-profile <name>`, `validate`
+- install-manifest metadata: `sync-install-manifest <name>`
+- compatibility entrypoints: `start-feature <feature_id> <feature_slug>` and `start-task <mode> <feature_id> <feature_slug> <mode_reason>`
+- work-item management: `create-work-item <mode> <feature_id> <feature_slug> <mode_reason>`, `list-work-items`, `show-work-item <work_item_id>`, `activate-work-item <work_item_id>`
+- feature-state mutation: `advance-stage <stage>`, `set-approval <gate> <status> [approved_by] [approved_at] [notes]`, `link-artifact <kind> <path>`, `scaffold-artifact <task_card|plan|migration_report> <slug>`
+- task-board management: `list-tasks <work_item_id>`, `create-task <work_item_id> <task_id> <title> <kind> [branch] [worktree_path]`, `claim-task <work_item_id> <task_id> <owner> <requested_by>`, `release-task <work_item_id> <task_id> <requested_by>`, `reassign-task <work_item_id> <task_id> <owner> <requested_by>`, `assign-qa-owner <work_item_id> <task_id> <qa_owner> <requested_by>`, `set-task-status <work_item_id> <task_id> <status>`, `validate-work-item-board <work_item_id>`
+- issue routing: `record-issue <issue_id> <title> <type> <severity> <rooted_in> <recommended_owner> <evidence> <artifact_refs>`, `clear-issues`, `route-rework <issue_type> [repeat_failed_fix=true|false]`
+
+Task-board guardrail:
+
+- task-board commands remain full-delivery only; quick and migration work items stay task-board free in the current runtime
+
+## Global Install Vs. Runtime Checks
+
+Keep this distinction explicit:
+
+- `openkit doctor` checks the supported global installation path.
+- `node .opencode/workflow-state.js doctor` checks the underlying repository/runtime state.
+- Both are useful, but they answer different questions and should not be described as interchangeable.
+
+## Route By Need
+
+- audience-specific operator routing: `docs/operator/README.md`
+- workflow and command reality: `context/core/project-config.md`
+- workflow semantics and resume rules: `context/core/workflow.md` and `context/core/session-resume.md`
+- daily operator path and command usage: `runbooks/openkit-daily-usage.md`
+- status, diagnostics, and repeatable verification steps: `runbooks/workflow-state-smoke-tests.md`
+- durable-record policy and any intentionally kept records: `internal-records/README.md`
+
+## Index Guardrails
+
+Current-state guardrails:
+
+- These docs describe repository runtime support only. They do not imply application build, lint, or test tooling.
+- Keep this file index-first; procedural verification belongs in `runbooks/` and durable project memory belongs in `internal-records/`.
+- Keep global-kit language aligned with the current repository reality: global install is the preferred user path, while the checked-in runtime remains the maintainer and compatibility surface.
+- Keep lower-level command details concise here and route canonical command behavior to `context/core/project-config.md`.

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

@@ -0,0 +1,79 @@
+# OpenKit 0.2.0 Release Checklist
+
+Date: 2026-03-24
+
+## Scope
+
+- simplified onboarding with `npm install -g openkit` followed by `openkit run`
+- automatic first-run global kit setup when the install is missing
+- doctor guidance with `Next:` and `Recommended command:` output
+- manual and compatibility retention for `openkit install-global`, `openkit install`, and `openkit init`
+
+## Pre-Publish
+
+- confirm `package.json` version is `0.2.0`
+- confirm docs describe `npm install -g 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:
+
+```bash
+node --test tests/cli/openkit-cli.test.js tests/global/*.test.js tests/runtime/*.test.js tests/install/*.test.js
+```
+
+- run:
+
+```bash
+npm pack
+```
+
+- verify the tarball name is `openkit-0.2.0.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`
+
+## Publish
+
+- authenticate to npm if needed
+- publish the package from the repository root:
+
+```bash
+npm publish
+```
+
+- if using the packed tarball path explicitly, publish the generated archive instead
+
+## Post-Publish
+
+- verify the published version:
+
+```bash
+npm view openkit version
+```
+
+- install globally on a clean machine or temporary prefix:
+
+```bash
+npm install -g openkit
+```
+
+- verify:
+
+```bash
+openkit --help
+openkit run
+openkit doctor
+```
+
+- confirm `openkit run` auto-installs the managed kit when the global install is missing
+- confirm invalid-install guidance points users to `openkit upgrade`
+
+## Suggested Commit Message
+
+```text
+simplify global OpenKit onboarding
+
+Make `openkit run` perform first-time global setup automatically so users can start with `npm install -g openkit` and launch immediately. Update doctor guidance, command help, docs, and tests to support the new onboarding flow while keeping manual install commands for compatibility.
+```

package/docs/operations/internal-records/2026-03-24-simplified-install-ux.md

@@ -0,0 +1,36 @@
+# Simplified Install UX
+
+Date: 2026-03-24
+
+## Change Summary
+
+- the preferred onboarding flow is now `npm install -g openkit` followed by `openkit run`
+- `openkit run` performs first-time global kit setup automatically when the install is missing
+- `openkit doctor` now reports next-step guidance and recommended commands
+- `openkit install-global`, `openkit install`, and `openkit init` remain available as manual or compatibility commands
+
+## Why This Changed
+
+- the previous onboarding path required users to remember `openkit install-global` before they could do useful work
+- the new flow reduces friction for first-time users while keeping install behavior explicit and debuggable inside the OpenKit CLI
+- the project intentionally avoids npm `postinstall` side effects so failures remain easier to explain and recover from
+
+## Operator Impact
+
+- new-user quickstart:
+
+```bash
+npm install -g openkit
+openkit run
+openkit doctor
+```
+
+- if the global install is invalid rather than missing, `openkit run` stops and points the user to `openkit upgrade`
+- if `opencode` is missing from `PATH`, first-time setup can still complete, but launch fails with a clear launcher error
+
+## Release Notes Draft
+
+- Simplified onboarding so users can install the CLI with `npm install -g openkit` and start with `openkit run`
+- Added automatic first-run global kit setup when the managed install is missing
+- Added doctor guidance with `Next:` and `Recommended command:` output for missing, invalid, healthy, and workspace-issue states
+- Kept `openkit install-global`, `openkit install`, and `openkit init` for manual and compatibility workflows

package/docs/operations/internal-records/README.md

@@ -0,0 +1,18 @@
+# Internal Records
+
+This directory holds project memory for operations work.
+
+Use these docs to preserve durable context, lightweight records, and guidance that explains how to capture operational history.
+
+Guardrails:
+
+- keep these docs descriptive, not procedural
+- store repeatable command walkthroughs in `docs/operations/runbooks/`
+- prefer concise records that help future maintainers recover context quickly
+- escalate architecture-shaping decisions to ADRs when repository policy requires it
+
+Current state:
+
+- no standing internal-record files are kept checked in after the repository cleanup pass
+- add a focused record here only when it preserves durable operational context that does not belong in an ADR or runbook
+- prefer one clearly named file per topic and delete stale records once they stop helping maintainers

package/docs/operations/runbooks/README.md

@@ -0,0 +1,23 @@
+# Runbooks
+
+This directory holds executable operator guidance.
+
+Use these docs when you need step-by-step checks, commands, or repeatable maintenance procedures.
+
+Current runbooks:
+
+- `openkit-daily-usage.md`: practical day-to-day operator flow for the checked-in runtime
+- `workflow-state-smoke-tests.md`: repeatable smoke checks for runtime and wrapper-related surfaces
+
+Related reusable migration checklists live under `docs/templates/`:
+
+- `migration-baseline-checklist.md`
+- `migration-verify-checklist.md`
+- `migration-report-template.md`
+
+Guardrails:
+
+- keep runbooks action-oriented and safe to follow
+- include command expectations when they materially reduce ambiguity
+- move historical notes or durable project memory to `docs/operations/internal-records/`
+- do not treat this directory as the canonical workflow contract; keep that in `context/core/`