@duypham93/openkit 0.2.0

package/docs/templates/implementation-plan-template.md

@@ -0,0 +1,32 @@
+---
+artifact_type: implementation_plan
+version: 1
+status: draft
+feature_id: FEATURE-000
+feature_slug: example-feature
+source_architecture: docs/architecture/YYYY-MM-DD-example-feature.md
+owner: TechLeadAgent
+approval_gate: tech_lead_to_fullstack
+---
+
+# Implementation Plan: <Feature Name>
+
+## Goal
+
+- State the implementation outcome this plan must deliver.
+
+## Dependencies
+
+- List the upstream brief, spec, architecture, commands, or runtime constraints that matter.
+
+## Tasks
+
+### [ ] Task 1: <Task Name>
+- Files:
+- Goal:
+- Validation:
+- Notes:
+
+## Risks
+
+## Rollback Notes

package/docs/templates/migration-baseline-checklist.md

@@ -0,0 +1,48 @@
+# Migration Baseline Checklist
+
+Use this checklist during `migration_baseline` to capture the current reality before any meaningful upgrade work starts.
+
+## Scope And Invariants
+
+- [ ] Migration goal is stated in one sentence.
+- [ ] Target stack or dependency destination is named explicitly.
+- [ ] In-scope surfaces are listed.
+- [ ] Out-of-scope surfaces are listed.
+- [ ] Preserved layout expectations are recorded.
+- [ ] Preserved flows and user journeys are recorded.
+- [ ] Preserved contracts are recorded: API payloads, routes, events, schemas, permissions, storage shapes.
+- [ ] Preserved core logic or business rules are recorded.
+- [ ] Any allowed behavior change is explicitly documented as an exception.
+
+## Baseline Evidence
+
+- [ ] Current versions of framework, runtime, and critical dependencies are recorded.
+- [ ] Existing build, test, typecheck, lint, codemod, or smoke commands are listed if they exist.
+- [ ] Missing validation tooling is called out honestly if commands do not exist.
+- [ ] Critical screens or flows have baseline screenshots, notes, or equivalent evidence.
+- [ ] Important request/response or contract samples are captured when relevant.
+- [ ] Known warnings, deprecations, and fragile areas are recorded.
+
+## Coupling And Blockers
+
+- [ ] Framework-coupled hotspots are identified.
+- [ ] Lifecycle, routing, state, fetching, rendering, or side-effect patterns that block upgrade are identified.
+- [ ] Business logic mixed into framework glue is identified.
+- [ ] Candidate seams, adapters, or compatibility shims are listed.
+- [ ] High-risk modules or pages are listed.
+
+## Risk And Sequencing Readiness
+
+- [ ] Compatibility risks are listed.
+- [ ] Rollback concerns are listed.
+- [ ] Unknowns that require spike or investigation are listed.
+- [ ] The work still fits migration semantics and is not drifting into rewrite or new-feature delivery.
+
+## Baseline Exit Gate
+
+Baseline is ready for `migration_strategy` only when:
+
+- preserved invariants are inspectable
+- baseline evidence is concrete enough to compare later
+- main blockers and likely seams are known
+- the validation path is honest

package/docs/templates/migration-plan-template.md

@@ -0,0 +1,52 @@
+---
+artifact_type: migration_plan
+version: 1
+status: draft
+feature_id: FEATURE-000
+feature_slug: example-migration
+source_architecture: docs/architecture/YYYY-MM-DD-example-migration.md
+owner: TechLeadAgent
+approval_gate: strategy_to_upgrade
+---
+
+# Migration Plan: <Migration Name>
+
+## Goal
+
+- State the target migration or upgrade outcome and the intended end-state stack.
+
+## Preserved Invariants
+
+- Layout or presentation details that must remain equivalent.
+- Core flows, contracts, and business logic that must remain equivalent.
+- Explicitly allowed behavior changes, if any.
+
+## Baseline Snapshot
+
+- Current versions, important dependencies, runtime assumptions, and known fragile areas.
+
+## Migration Blockers And Seams
+
+- Framework-coupled blockers that make direct upgrade unsafe.
+- Seams, adapters, or compatibility shims to create before or during the migration.
+
+## Upgrade Sequence
+
+### [ ] Step 1: <Task Name>
+- Files:
+- Goal:
+- Preserve:
+- Seam or adapter work:
+- Validation:
+- Rollback checkpoint:
+- Notes:
+
+## Compatibility Risks
+
+## Parity Verification
+
+- Baseline evidence to compare against after each slice.
+- Critical smoke or regression paths.
+- Manual or automated checks that prove behavior equivalence.
+
+## Rollback Notes

package/docs/templates/migration-report-template.md

@@ -0,0 +1,74 @@
+---
+artifact_type: migration_report
+version: 1
+status: draft
+feature_id: FEATURE-000
+feature_slug: example-migration
+owner: MasterOrchestrator
+source_architecture: docs/architecture/YYYY-MM-DD-example-migration.md
+source_plan: docs/plans/YYYY-MM-DD-example-migration.md
+---
+
+# Migration Report: <Migration Name>
+
+## Goal
+
+- State the migration objective and the intended target stack.
+
+## Preserved Invariants
+
+- Layout or presentation expectations that must remain equivalent.
+- Core flows, contracts, and business logic that must remain equivalent.
+- Explicitly allowed behavior changes, if any.
+
+## Baseline Snapshot
+
+- Current versions and critical dependency state.
+- Existing validation commands, or a note that they do not exist.
+- Baseline screenshots, notes, request/response samples, or equivalent evidence.
+- Known warnings, deprecations, or fragile areas.
+
+## Migration Blockers And Seams
+
+- Framework-coupled blockers that make direct upgrade unsafe.
+- Candidate seams, adapters, or compatibility shims.
+- High-risk modules, pages, or integration points.
+
+## Strategy
+
+- Chosen migration approach.
+- Slice order and rollback checkpoints.
+- Validation approach for each slice.
+
+## Execution Log
+
+### Slice 1: <Task Name>
+- Goal:
+- Files or surfaces touched:
+- Seam or adapter work:
+- Upgrade work:
+- Validation:
+- Result:
+- Rollback note:
+
+## Verification Summary
+
+- Versions actually landed.
+- Parity checks completed.
+- Manual and automated evidence.
+- Remaining adapters or shims.
+
+## Issues And Risks
+
+### ISSUE-001: <Title>
+- Type:
+- Severity:
+- Rooted In:
+- Recommendation:
+- Evidence:
+
+## Conclusion
+
+- Overall migration status: PASS | FAIL | PARTIAL
+- Ready for `migration_done`: yes | no
+- Follow-up cleanup or escalation notes.

package/docs/templates/migration-verify-checklist.md

@@ -0,0 +1,39 @@
+# Migration Verify Checklist
+
+Use this checklist during `migration_verify` to judge whether the upgraded system still preserves the intended behavior under the new stack.
+
+## Upgrade Outcome
+
+- [ ] Target framework or dependency versions match the migration goal.
+- [ ] Planned upgrade slices were completed or deferred explicitly.
+- [ ] Temporary adapters or shims still present are listed with follow-up intent.
+
+## Parity Checks
+
+- [ ] Preserved layout expectations still hold.
+- [ ] Preserved user flows still hold.
+- [ ] Preserved contracts still hold: API payloads, routes, events, schemas, permissions, storage shapes.
+- [ ] Preserved core logic or business rules still hold.
+- [ ] Any approved exception is still the only intentional behavior difference.
+
+## Validation Evidence
+
+- [ ] Build, test, typecheck, lint, codemod, or smoke evidence is recorded when tooling exists.
+- [ ] Manual regression evidence is recorded for flows not covered by automation.
+- [ ] Before/after screenshots, notes, or equivalent parity evidence are attached or referenced when relevant.
+- [ ] Performance or runtime warnings introduced by the migration are recorded when relevant.
+
+## Issue Classification
+
+- [ ] Remaining defects are classified as implementation fallout, migration-strategy flaw, or requirement ambiguity.
+- [ ] Open risks and deferred items are listed.
+- [ ] Escalation to `full` is recommended if the issue is no longer primarily a technical migration problem.
+
+## Verify Exit Gate
+
+Migration is ready for `migration_done` only when:
+
+- parity evidence is inspectable
+- remaining issues are resolved or explicitly routed
+- rollback and residual-risk notes are clear
+- `migration_verified` can be approved honestly

package/docs/templates/product-brief-template.md

@@ -0,0 +1,32 @@
+---
+artifact_type: product_brief
+version: 1
+status: draft
+feature_id: FEATURE-000
+feature_slug: example-feature
+source_request: "Link or quote the originating user request"
+owner: PMAgent
+approval_gate: pm_to_ba
+---
+
+# Product Brief: <Feature Name>
+
+## Goal
+
+## Target Users
+
+## Problem Statement
+
+## High-Level Features
+- [ ]
+
+## Priorities
+- P0:
+- P1:
+- P2:
+
+## Success Metrics
+
+## Out of Scope
+
+## Open Questions

package/docs/templates/qa-report-template.md

@@ -0,0 +1,37 @@
+---
+artifact_type: qa_report
+version: 1
+status: draft
+feature_id: FEATURE-000
+feature_slug: example-feature
+source_plan: docs/plans/YYYY-MM-DD-example-feature.md
+owner: QAAgent
+approval_gate: qa_to_done
+---
+
+# QA Report: <Feature Name>
+
+## Overall Status
+- PASS | FAIL
+
+## Spec Compliance
+
+| Acceptance Criteria | Result | Notes |
+| --- | --- | --- |
+| | | |
+
+## Quality Checks
+
+## Test Evidence
+
+## Issues
+
+### ISSUE-001: <Title>
+- Type:
+- Severity:
+- Rooted In:
+- Recommended Owner:
+- Evidence:
+- Recommendation:
+
+## Conclusion

package/docs/templates/quick-task-template.md

@@ -0,0 +1,36 @@
+---
+artifact_type: quick_task_card
+version: 1
+status: draft
+feature_id: TASK-000
+feature_slug: example-task
+owner: MasterOrchestrator
+mode: quick
+approval_gate: quick_verified
+---
+
+# Quick Task: <Task Name>
+
+## Goal
+
+- State the smallest useful outcome this quick task must achieve.
+
+## Scope
+
+- List the files, surfaces, or boundaries this task is allowed to touch.
+
+## Acceptance Bullets
+- [ ]
+
+## Risk Note
+
+## Verification Path
+
+- Record the real command or manual check that will be used.
+
+## Touched Files
+-
+
+## Verification Result
+
+## Escalation Note

package/docs/templates/spec-template.md

@@ -0,0 +1,31 @@
+---
+artifact_type: specification
+version: 1
+status: draft
+feature_id: FEATURE-000
+feature_slug: example-feature
+source_brief: docs/briefs/YYYY-MM-DD-example-feature.md
+owner: BAAgent
+approval_gate: ba_to_architect
+---
+
+# Spec: <Feature Name>
+
+## Summary
+
+## User Stories
+
+### US-001: <Title>
+As a <user type>, I want <action>, so that <benefit>.
+
+**Acceptance Criteria**
+- Given ... When ... Then ...
+
+**Edge Cases**
+-
+
+## Non-Functional Requirements
+
+## Out of Scope
+
+## Open Questions

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${OPENCODE_PLUGIN_ROOT:-$(pwd)}/hooks/session-start\"",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/session-start

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+
+# This script runs when an AI session starts.
+# It teaches the agent how to use the Skills library by injecting the meta-skill.
+
+set -e
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+KIT_ROOT="${OPENKIT_KIT_ROOT:-$(dirname "$DIR")}"
+PROJECT_ROOT="${OPENKIT_PROJECT_ROOT:-$(pwd)}"
+META_SKILL_PATH="$KIT_ROOT/skills/using-skills/SKILL.md"
+STATE_PATH="${OPENKIT_WORKFLOW_STATE:-$PROJECT_ROOT/.opencode/workflow-state.json}"
+MANIFEST_PATH="$KIT_ROOT/.opencode/opencode.json"
+PYTHON_BIN="${OPENKIT_PYTHON_BIN:-python3}"
+RUNTIME_SUMMARY_MODULE="$KIT_ROOT/.opencode/lib/runtime-summary.js"
+
+KIT_NAME="OpenKit AI Software Factory"
+KIT_VERSION="unknown"
+ENTRY_AGENT="unknown"
+JSON_HELPER_STATUS="ok"
+
+if [ -f "$MANIFEST_PATH" ] && command -v "$PYTHON_BIN" >/dev/null 2>&1; then
+    KIT_INFO_RAW=$("$PYTHON_BIN" - "$MANIFEST_PATH" <<'PY' || true
+import json
+import sys
+
+manifest_path = sys.argv[1]
+
+try:
+    with open(manifest_path, "r", encoding="utf-8") as fh:
+        manifest = json.load(fh)
+except Exception:
+    sys.exit(0)
+
+kit = manifest.get("kit") or {}
+print(kit.get("name", "OpenKit AI Software Factory"))
+print(kit.get("version", "unknown"))
+print(kit.get("entryAgent", "unknown"))
+PY
+)
+    KIT_INFO_1=$(printf '%s\n' "$KIT_INFO_RAW" | sed -n '1p')
+    KIT_INFO_2=$(printf '%s\n' "$KIT_INFO_RAW" | sed -n '2p')
+    KIT_INFO_3=$(printf '%s\n' "$KIT_INFO_RAW" | sed -n '3p')
+    if [ -n "$KIT_INFO_1" ] && [ -n "$KIT_INFO_2" ] && [ -n "$KIT_INFO_3" ]; then
+        KIT_NAME="$KIT_INFO_1"
+        KIT_VERSION="$KIT_INFO_2"
+        ENTRY_AGENT="$KIT_INFO_3"
+    else
+        JSON_HELPER_STATUS="degraded"
+    fi
+elif [ -f "$MANIFEST_PATH" ]; then
+    JSON_HELPER_STATUS="degraded"
+fi
+
+if [ -n "${OPENKIT_SESSION_START_NO_SKILL:-}" ]; then
+    SKILL_STATUS="skipped"
+elif [ -f "$META_SKILL_PATH" ]; then
+    SKILL_STATUS="loaded"
+else
+    SKILL_STATUS="missing"
+fi
+
+echo "<openkit_runtime_status>"
+echo "kit: $KIT_NAME v$KIT_VERSION"
+echo "entry agent: $ENTRY_AGENT"
+echo "state file: $STATE_PATH"
+echo "startup skill: $SKILL_STATUS"
+echo "json helper: $JSON_HELPER_STATUS"
+echo "help: node .opencode/workflow-state.js status"
+echo "doctor: node .opencode/workflow-state.js doctor"
+echo "show: node .opencode/workflow-state.js show"
+echo "</openkit_runtime_status>"
+
+if [ -z "${OPENKIT_SESSION_START_NO_SKILL:-}" ] && [ -f "$META_SKILL_PATH" ]; then
+    echo "<skill_system_instruction>"
+    echo "You are running within the Open Kit AI Software Factory framework."
+    echo "Below are the rules for how you must discover and invoke your skills."
+    echo ""
+    cat "$META_SKILL_PATH"
+    echo "</skill_system_instruction>"
+fi
+
+if [ -f "$STATE_PATH" ] && [ "$JSON_HELPER_STATUS" = "ok" ] && command -v "$PYTHON_BIN" >/dev/null 2>&1; then
+    "$PYTHON_BIN" - "$STATE_PATH" "$RUNTIME_SUMMARY_MODULE" <<'PY' || true
+import json
+import os
+import pathlib
+import subprocess
+import sys
+
+state_path = sys.argv[1]
+runtime_summary_module = sys.argv[2]
+runtime_root = str(pathlib.Path(state_path).resolve().parents[1])
+
+try:
+    with open(state_path, "r", encoding="utf-8") as fh:
+        state = json.load(fh)
+except Exception:
+    sys.exit(0)
+
+mode = state.get("mode")
+stage = state.get("current_stage")
+status = state.get("status")
+owner = state.get("current_owner")
+feature_id = state.get("feature_id")
+feature_slug = state.get("feature_slug")
+work_item_id = state.get("work_item_id")
+
+if not all([mode, stage, status, owner]):
+    sys.exit(0)
+
+task_summary = None
+active_tasks = []
+
+if mode == "full" and work_item_id:
+    try:
+        node_cmd = [
+            "node",
+            "-e",
+            (
+                "const { getRuntimeContext } = require(process.argv[1]);"
+                "const context = getRuntimeContext(process.argv[2], JSON.parse(process.argv[3]));"
+                "process.stdout.write(JSON.stringify(context));"
+            ),
+            runtime_summary_module,
+            runtime_root,
+            json.dumps(state),
+        ]
+        result = subprocess.run(node_cmd, check=True, capture_output=True, text=True)
+        runtime_context = json.loads(result.stdout.strip() or "{}")
+        board_summary = runtime_context.get("taskBoardSummary")
+        if board_summary:
+            task_summary = (
+                f"task board: {board_summary.get('total', 0)} tasks | "
+                f"ready {board_summary.get('ready', 0)} | active {board_summary.get('active', 0)}"
+            )
+            active_tasks = board_summary.get("activeTasks") or []
+    except Exception:
+        task_summary = None
+        active_tasks = []
+
+print("<workflow_resume_hint>")
+print("OpenKit workflow resume context detected.")
+print(f"mode: {mode}")
+print(f"stage: {stage}")
+print(f"status: {status}")
+print(f"owner: {owner}")
+if feature_id and feature_slug:
+    print(f"work item: {feature_id} ({feature_slug})")
+if work_item_id:
+    print(f"active work item id: {work_item_id}")
+if task_summary:
+    print(task_summary)
+if active_tasks:
+    print(f"active tasks: {'; '.join(active_tasks)}")
+print("Read first: AGENTS.md -> context/navigation.md -> context/core/workflow.md -> .opencode/workflow-state.json")
+print("Then load resume guidance from context/core/session-resume.md.")
+if mode == "full" and active_tasks:
+    print("Parallel task support is not yet assumed safe by this hook; confirm with `node .opencode/workflow-state.js doctor` before relying on it.")
+print("</workflow_resume_hint>")
+PY
+fi

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@duypham93/openkit",
+  "version": "0.2.0",
+  "type": "module",
+  "files": [
+    ".opencode/",
+    "agents/",
+    "assets/",
+    "bin/",
+    "commands/",
+    "context/",
+    "docs/",
+    "hooks/",
+    "skills/",
+    "src/",
+    "tests/",
+    "AGENTS.md",
+    "README.md",
+    "registry.json"
+  ],
+  "bin": {
+    "openkit": "bin/openkit.js"
+  }
+}