@duypham93/openkit 0.2.0

package/assets/install-bundle/opencode/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/assets/install-bundle/opencode/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/assets/install-bundle/opencode/context/core/lane-selection.md

@@ -0,0 +1,54 @@
+# Lane Selection
+
+This file is the detailed routing reference for choosing between `Quick Task`, `Migration`, and `Full Delivery`.
+
+Use `context/core/workflow.md` for the canonical live contract. Use this file when you need the stricter routing rubric, tie-breakers, anti-patterns, and examples.
+
+## Core Rule
+
+Choose the lane by the dominant uncertainty of the work, not by estimated size alone.
+
+- `Quick Task`: low local uncertainty inside already-understood behavior
+- `Migration`: compatibility uncertainty inside behavior-preserving modernization
+- `Full Delivery`: product, requirements, acceptance, or cross-boundary solution uncertainty
+
+## Routing Profile Dimensions
+
+Record and reason with these dimensions:
+
+- `work_intent`: `maintenance`, `modernization`, `feature`
+- `behavior_delta`: `preserve`, `extend`, `redefine`
+- `dominant_uncertainty`: `low_local`, `compatibility`, `product`
+- `scope_shape`: `local`, `adjacent`, `cross_boundary`
+
+Expected combinations:
+
+- `Quick Task` -> `maintenance`, `preserve`, `low_local`, `local|adjacent`
+- `Migration` -> `modernization`, `preserve`, `compatibility`, `local|adjacent|cross_boundary`
+- `Full Delivery` -> usually `feature`, `extend|redefine`, `product`, often `cross_boundary`
+
+## Tie-Breaker Priority
+
+Apply these in order:
+
+1. If `behavior_delta` is not `preserve`, choose `Full Delivery`.
+2. If `dominant_uncertainty` is `product`, choose `Full Delivery`.
+3. If `dominant_uncertainty` is `compatibility` and preserved behavior is known, choose `Migration`.
+4. If `dominant_uncertainty` is `low_local` and scope stays bounded, choose `Quick Task`.
+5. If uncertainty still cannot be classified honestly, choose `Full Delivery`.
+
+## Anti-Patterns
+
+- Do not choose `Quick Task` for a dependency or framework upgrade just because the code diff looks small.
+- Do not choose `Migration` when acceptance criteria or business semantics are being redefined.
+- Do not choose `Full Delivery` for straightforward modernization work only because internal architecture must change.
+- Do not let file count or estimated duration override the dominant uncertainty rule.
+
+## Fast Examples
+
+- Upgrade React 16 to React 19 with preserved screens -> `Migration`
+- Add a new billing workflow -> `Full Delivery`
+- Fix a typo in one operator doc -> `Quick Task`
+- Replace one deprecated helper with known equivalent behavior -> `Quick Task`
+- Modernize fetching to React Query while preserving UX and rules -> `Migration`
+- Upgrade framework and redesign onboarding flow -> `Full Delivery`

package/assets/install-bundle/opencode/skills/brainstorming/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: brainstorming
+description: "Socratic design refinement process. Used before writing any specs or code to clarify intent and explore options."
+---
+
+# Skill: Brainstorming (Socratic Refinement)
+
+## Context
+
+When the user brings a new idea or request, or when the PM Agent or Architect Agent starts designing, this skill **must** be used before locking in a solution.
+
+Do NOT jump straight into writing a spec or code. You must go through the "ask questions - explore - converge" process first.
+
+## Execution Process
+
+### Phase 1: Context Exploration
+1. Read the user's initial request.
+2. Identify any relevant existing files.
+3. Ask clarifying questions. **Golden Rule: ask only ONE question at a time.**
+   - Do not dump a list of 5 questions on the user and overwhelm them.
+   - Ask the most important question first. Wait for the answer before asking the next one.
+   - Example: "Who is the primary user of this feature: Admin or Client?"
+
+### Phase 2: Option Generation
+Once you have enough information (no major open questions remain), do NOT choose a single solution on your own. You must present 2-3 approaches:
+
+**Proposal template:**
+```markdown
+Based on what you've shared, I see X main approaches:
+
+**Option 1: [Short name]**
+*   **How it works**: [Brief description]
+*   **Pros**: [...]
+*   **Cons / Trade-offs**: [...]
+
+**Option 2: [Short name]**
+*   **How it works**: [Brief description]
+*   **Pros**: [...]
+*   **Cons / Trade-offs**: [...]
+
+Which direction do you prefer, or do you want to combine ideas from both?
+```
+
+### Phase 3: Incremental Design
+After the user chooses an option, design the solution **one part at a time**.
+- Do not drop one giant design block on the user.
+- For example, design the database first and get feedback. Then design the API and get feedback.
+- Use visual tools when helpful (Mermaid diagrams, ASCII art).
+
+### Phase 4: Handoff
+Finish brainstorming by moving into a Product Brief or Architecture Document (depending on which agent is active), then hand off to the next agent in the pipeline.

package/assets/install-bundle/opencode/skills/code-review/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: code-review
+description: "Pre-review checklist and quality gates. Uses a two-stage approach: spec compliance then code quality."
+---
+
+# Skill: Code Review
+
+## Context
+
+Used by the Code Reviewer subagent, the QA Agent, or the Tech Lead Agent.
+The goal is to be the final gate that keeps bad code or off-spec code from reaching the main branch.
+
+## Required Inputs
+
+- What needs review? (files / commit / PR)
+- Comparison documents: spec (requirements), architecture (design), code standards.
+
+## Two-Stage Review Process
+
+Strictly follow these two stages in order. Do not talk about formatting or clean code if the feature itself is off-spec.
+
+### Stage 1: Spec Compliance
+**Ask exactly one question: "Does this code meet the acceptance criteria in the spec exactly, and does it avoid inventing extra features?"**
+
+- Inspect each acceptance criterion (Given - When - Then).
+- Does the code handle the edge cases the BA documented?
+- **Overscope Audit (Over-engineering)**: counter the developer instinct to "helpfully" add extra behavior. Has the code built convenience features that were never requested? (YAGNI)
+
+=> **Record Pass / Fail for Stage 1. If it fails, stop the review there and send it back to the developer. Do not continue to Stage 2.**
+
+### Stage 2: Code Quality
+Only reach this step if Stage 1 has passed. Use `context/core/code-quality.md` as the review baseline.
+
+Review by severity:
+1. **Critical / Security (Must fix immediately)**: SQL injection, leaked environment variables, crash-level memory issues.
+2. **Architecture (Needs consultation)**: wrong boundary ownership (for example, a controller doing database query logic). Escalate to Tech Lead.
+3. **Important Quality (Should fix)**: meaningless variable names (`let a = 1`), functions longer than 50 lines, badly degraded test coverage.
+4. **Minor**: brace and spacing debates. Follow the existing linter or formatter.
+
+## Checklist for a Good Review Report
+- [ ] Clearly state Stage 1 (Pass/Fail) and why.
+- [ ] Cite the exact file path and failing line number.
+- [ ] State severity clearly (Critical / Important / Minor).
+- [ ] Do not just criticize - include a concrete fix suggestion or example snippet.
+
+## Anti-Patterns to Avoid
+- Superficial review: "LGTM" without actually reading the files.
+- Fixing the code for the developer: "I'll just patch it quickly and approve." The reviewer must not touch the implementation. The developer stays responsible for the fix.

package/assets/install-bundle/opencode/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: subagent-driven-development
+description: "Execution engine. Dispatches fresh subagents for each task to avoid context pollution and ensures 2-stage review."
+---
+
+# Skill: Subagent-Driven Development
+
+## Context
+
+Used by the Fullstack Agent to execute an implementation plan.
+
+When working through a complex sequence of tasks, the primary agent can get overwhelmed or hallucinate because the context grows too large. Subagent-Driven Development solves this by splitting the work into tasks and dispatching a fresh subagent to handle each task individually.
+
+## Execution Process
+
+### 1. Preparation (Task Queueing)
+Read `docs/plans/YYYY-MM-DD-<feature>.md`.
+Build a queue of tasks.
+
+### 2. Batch Execution (Repeat for Each Task)
+
+Take Task N from the queue:
+
+#### Step 2a: Prepare the Subagent Payload
+Create a prompt (define it first, do not run it yet) with enough context for the subagent (usually the implementation-focused Fullstack Agent):
+- target files
+- exact code requirements from the plan
+- tests that must pass
+- explicit instruction: "Follow the active mode's validation model and the coding standards"; use TDD in full-delivery implementation work and migration validation in migration work
+
+#### Step 2b: Dispatch & Execution
+Call the tool or script that runs the subagent independently. (This may be a shell command, a `run_agent.sh` script, or an equivalent delegation mechanism.)
+
+The subagent must report one of 4 standard statuses:
+
+- `DONE`: task completed, ready for review
+- `DONE_WITH_CONCERNS`: task completed, but with concerns the controller must read before review
+- `NEEDS_CONTEXT`: missing context; must not guess
+- `BLOCKED`: cannot complete with the current scope or context
+
+#### Step 2c: Stop and Call a Reviewer (Code Reviewer Subagent)
+Do NOT mark the current task complete and continue.
+You must dispatch an independent `code-reviewer` subagent with a fresh context to evaluate the implementation.
+
+Two-stage review process (see `skills/code-review/SKILL.md`):
+- **Stage 1**: spec compliance
+- **Stage 2**: code quality
+
+Do not reverse this order.
+
+*If it fails*: send the task back to Step 2a with the review feedback.
+*If it passes*: mark the task as DONE and commit.
+
+### 3. Loop and Throughput
+Return to Step 2 for Task N+1.
+
+## Anti-Patterns to Eliminate
+- "I'll just take all 5 tasks in the plan and do them in one shot." -> **Seriously wrong**. The LLM will forget instructions midway and accumulate context garbage.
+- Skipping the code-review subagent because "I trust my own work." -> The implementer subagent can still be wrong. An independent reviewer is mandatory.
+- Letting the implementer reread the whole plan and choose scope when the controller already knows the current task. -> Wrong. The controller should provide the full task text and relevant context, not dump the whole world into the subagent.
+- Moving to the next task while spec review or quality review still has open issues. -> Wrong. A task is DONE only after it passes both gates.
+
+## Handling Implementer Status
+
+### `DONE`
+- move straight into spec review
+
+### `DONE_WITH_CONCERNS`
+- read the concerns first
+- if they affect correctness or scope, resolve them before review
+- if they are only maintainability notes, continue into review but keep them in mind for later work
+
+### `NEEDS_CONTEXT`
+- provide the missing context
+- re-dispatch the same task; do not let the implementer invent assumptions
+
+### `BLOCKED`
+- assess whether the blocker comes from missing context, an oversized task, or a bad plan
+- if needed, split the task smaller or escalate to the coordinating human or agent

package/assets/install-bundle/opencode/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: systematic-debugging
+description: "4-phase root cause process to debug scientifically instead of blindly guessing."
+---
+
+# Skill: Systematic Debugging
+
+## Context
+
+This skill is used by any developer agent (Fullstack, QA, Tech Lead) when it hits a bug, a build error, or an unexpected test failure. LLMs tend to guess and jump into random fixes. This skill forces an engineering-style debugging path.
+
+## The Golden Rule
+**Do NOT change or fix any line of code until the ROOT CAUSE is clear.**
+
+## Additional Guardrails
+
+- Test only 1 primary hypothesis at a time
+- Do not stack multiple fixes into the same experiment
+- If you have already tried 3 fixes and the original bug keeps returning, question the pattern or architecture instead of attempting a fourth fix
+
+## 4-Phase Bug-Fix Process
+
+### Phase 1: Context and Reproduction
+Do not read code first. Go collect evidence.
+1. Capture the exact error stack trace.
+2. Identify the file and line that fails.
+3. Reproduce the failure: which environment (dev/prod) and which input trigger it?
+4. If the system has multiple boundaries (CLI -> controller -> rules, hook -> state file, command -> artifact), gather evidence at each boundary instead of jumping straight to the last layer.
+
+### Phase 2: Hypothesis Generation
+Based on the evidence, propose hypotheses for why it fails. Do NOT talk about fixes yet.
+
+* Weak guess: "Variable X does not exist, so `.length` fails."
+* Better hypothesis: "Function A expects an array, but the backend API returns `{ data: [] }` (an object), so calling `.map()` crashes."
+
+List 2-3 hypotheses. Then narrow them down by grepping and reading code until you identify the most likely root cause.
+
+⚠️ Test only 1 primary hypothesis. Do not fix three hypotheses at once and expect the tests to explain which one was correct.
+
+### Phase 3: Propose Fix
+Propose the Minimal Fix (the fewest lines changed across the fewest files).
+
+⚠️ **RED ALERT: fixing many places usually means architecture surgery.** If you realize the plan requires changing 3-4 separate logic files at once (scattered changes), stop. You are probably not fixing a bug anymore - you are papering over a broken system or bad architecture. Escalate back to the Master Orchestrator and bring in the Architect to review the system.
+
+### Phase 4: Implementation
+Follow the active mode's validation model:
+- In full-delivery implementation work, follow TDD (see `skills/test-driven-development/SKILL.md`): write a test, confirm it fails, apply the minimal fix, and confirm it passes.
+- In migration work, capture the failing compatibility evidence first, apply the minimal fix, then rerun the strongest real regression or compatibility check available.
+- In every mode, keep the fix minimal and evidence-based.
+
+If the fix does not work:
+
+1. STOP
+2. go back to Phase 1 with the new evidence
+3. if you have already tried 3 fixes and the core failure still remains, report to `MasterOrchestrator` that this may be an architecture or pattern problem rather than a local bug
+
+## Rationalization Checklist
+- [ ] Am I blindly spraying `console.log` everywhere instead of concentrating on the root cause? (If yes -> STOP)
+- [ ] Am I about to wrap everything in `try...catch` and silently swallow errors? (If yes -> STOP)
+- [ ] Have I already tried a third workaround and the same failure still looks unchanged? (The real problem may be cache or environment state. Re-check the environment instead of editing more code.)
+- [ ] Am I changing many scattered files just to make the tests green again without proving the root cause? (If yes -> STOP)

package/assets/install-bundle/opencode/skills/test-driven-development/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: test-driven-development
+description: "RED-GREEN-REFACTOR cycle. Enforces strictly writing failing tests before production code."
+---
+
+# Skill: Test-Driven Development (TDD)
+
+## Context
+
+This is the Iron Law for the Fullstack Agent. You are NOT ALLOWED to write any production code until a failing test proves that code needs to exist.
+
+## Execution Process (RED-GREEN-REFACTOR)
+
+### Step 1: RED (Write a Failing Test)
+1. Pick one small task from the implementation plan.
+2. Write **one** test case for that behavior.
+3. Run the repository's defined test command for the language or framework in use. If the repo does not define a standard command, stop and report the missing validation path instead of guessing.
+4. **Mandatory validation**: the test MUST fail. It must fail for the right reason (for example, `ReferenceError: function is not defined`, or `Expected true but got false`).
+   - If the test passes immediately -> the test is wrong, delete it and rewrite it.
+
+### Step 2: GREEN (Write the Minimum Code)
+1. Write **only enough code to make that one test pass**.
+2. **Lazy Code Rule**: return a hardcoded value if that is enough to make the test pass. Do not think about future needs (YAGNI - You Aren't Gonna Need It).
+3. Run the tests again.
+4. **Mandatory validation**: the test must PASS. If it does not, keep fixing until it passes. Do not add extra features.
+
+### Step 3: REFACTOR
+When (and only when) all tests are green:
+1. Review the code: is there duplication (DRY)? Are names understandable? Is the design still sound?
+2. Refactor the code.
+3. Run the tests again. If any test fails -> revert the refactor immediately or repair it quickly.
+
+## Anti-Patterns to Eliminate and Required Responses
+
+| Rationalization | Required response |
+|-----------------|-------------------|
+| "This is too simple, writing a test will take longer, I'll just code it." | **STOP.** Delete the code you just wrote and write the test first, even for a simple `add(a, b)` function. |
+| "I'll write 5 tests at once and then code it all in one pass." | **Stop.** One RED, one GREEN, one REFACTOR. Do not batch them together. |
+| "UI testing is too hard, I'll skip TDD for this part." | You may skip it only if the user explicitly allows it. Prefer separating logic from UI so the logic can still be tested. |
+| "The test failed and I already know the issue, so I'll fix files A, B, and C at once." | The root cause still lives in one place. Find it and fix the right place. Read `systematic-debugging`. |
+
+## Checklist for a Complete Cycle
+- [ ] Test written and run (FAIL)
+- [ ] Error message read and understood
+- [ ] Minimal production code written
+- [ ] Test rerun (PASS)
+- [ ] Nearby code cleaned up (REFACTOR)
+- [ ] Commit made (each GREEN/REFACTOR is a chance for a small commit)

package/assets/install-bundle/opencode/skills/using-skills/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: using-skills
+description: "Meta-skill: Teaches agents how to discover, evaluate, and invoke skills. Loaded at session start."
+---
+
+# Skill Usage Guide - Meta-Skill
+
+## What Skills Mean
+
+In the AI Software Factory, "Skills" are standard operating procedures that define how the system should work. When a situation matches a skill, you **must** follow that skill instead of improvising from raw LLM instinct.
+
+## Instruction Priority
+
+When instructions conflict, apply this order (1 is highest):
+
+1. **Current user prompt**: direct instructions from the user in the current message
+2. **Skill instructions**: guidance inside the active `SKILL.md`
+3. **Agent role instructions**: the agent's role and constraints (for example, `QA Agent does not edit code`)
+4. **General system prompt**: the base LLM behavior
+
+## How to Use a Skill
+
+When you identify a situation (for example: need to write a plan, fix a bug, or test code), follow these steps:
+
+1. **Identify**: "I need to create an implementation plan"
+2. **Discover**: "Let me use the tool to read `skills/writing-plans/SKILL.md`"
+3. **Read**: use `view_file` (or the equivalent tool) to read the ENTIRE `SKILL.md`
+4. **Execute**: apply the steps from that file
+
+## Warning: Rationalization Prevention
+
+LLM instinct often tries to short-circuit the process. Watch for these faulty thoughts:
+
+| Bad thought (Rationalization) | Correct action |
+|--------------------------------|----------------|
+| "This file is easy, I'll just fix it without reporting to the Master Orchestrator." | Stop. Follow the role boundary. Report to the Master Orchestrator first. |
+| "I already know how to write plans, I don't need to reread `skills/writing-plans/SKILL.md`." | No. Every time you write a plan, reread the skill so you are using the latest checklist. |
+| "This bug is obvious, I can skip root-cause analysis and fix it directly." | No. Use `systematic-debugging`. Root cause analysis is mandatory first. |
+| "The user said it's urgent, so I'll skip the test-writing step (TDD)." | In full-delivery implementation, TDD remains the default unless the user **very explicitly** says "Skip TDD". In migration mode, follow the migration validation model instead of forcing fake TDD. |

package/assets/install-bundle/opencode/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: verification-before-completion
+description: "Use before claiming work is complete, fixed, or passing. Requires fresh verification evidence before any success claim."
+---
+
+# Skill: Verification Before Completion
+
+## Context
+
+Use this skill immediately before the agent:
+
+- says the work is done
+- claims tests pass / the fix is done / the workflow is complete
+- creates a commit, PR, or merge
+- moves the task to the next step as if it were already complete
+
+OpenKit prioritizes **evidence before assertion**. Without fresh verification evidence, you must not speak as if the work is already sound.
+
+## Iron Law
+
+```
+DO NOT CLAIM COMPLETION WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you have not run the command that proves the claim in the current working session, the agent must report the real status as "not yet verified" instead of guessing.
+
+## Gate Function
+
+Before making any statement that implies success:
+
+1. IDENTIFY which command proves the claim
+2. RUN the full command
+3. READ the real output without inventing meaning
+4. CHECK the exit code, error count, and pass/fail counts
+5. ONLY THEN speak as if the outcome succeeded
+
+If the command fails, or if no verification path exists yet, report that exact reality.
+
+## What Counts as Valid Evidence
+
+### Tests
+
+Valid example:
+
+- `node --test ".opencode/tests/*.test.js"` with real passing output
+
+Not valid:
+
+- "it passed earlier"
+- "the code looks right"
+- "part of the suite passed so the rest is probably fine"
+
+### Runtime behavior
+
+Valid examples:
+
+- run `node .opencode/workflow-state.js status`
+- run `node .opencode/workflow-state.js doctor`
+- run a manual smoke test with clearly described observed input and output
+
+Not valid:
+
+- "this hook probably prints the right output because the unit test passed" when the claim is about integrated runtime behavior that has not been checked appropriately
+
+### Requirements / plan completion
+
+Valid example:
+
+- compare every item in the brief, spec, or plan against the diff and verification output
+
+Not valid:
+
+- "tests passed, so the requirements must all be done"
+
+## Current OpenKit Reality
+
+OpenKit does not currently define repo-wide build, lint, or test commands for general application code.
+
+So this skill must stay honest to the actual repo state:
+
+- if the repo has workflow-runtime tests, use them
+- if it only has runtime CLI checks or manual checks, say clearly that those are the real verification paths
+- if no suitable validation path exists, report that gap instead of inventing a command
+
+## Common Failure Patterns
+
+| Claim | Required evidence | Not enough |
+|------|-------------------|------------|
+| "Tests pass" | latest test-command output | old run, memory, assumption |
+| "Bug fixed" | symptom reproduction + passing verification | code changes alone |
+| "Ready to commit" | passing verification for the relevant scope | only looking at the diff |
+| "Requirements met" | checklist against spec/plan + verification | partial test success |
+| "Agent task done" | inspect changes + verify behavior | trusting a subagent report |
+
+## Red Flags
+
+If you catch yourself thinking these phrases, stop:
+
+- “should work now”
+- “looks correct”
+- “probably fine”
+- “just this once”
+- “the old test already passed”
+- “I'm pretty sure”
+
+Those are signs the agent is shifting from engineering into guessing.
+
+## Required Output Style When Verification Fails or Is Missing
+
+If verification fails:
+
+- state the command you ran
+- state the real failure status
+- include the important output or summary
+- do not use fuzzy wording like "almost done"
+
+If no verification path exists:
+
+- say clearly that the repo does not yet have an appropriate command
+- describe any manual check you did perform
+- explain the remaining limitation
+
+## Before Commit / PR / Merge
+
+Immediately before commit, PR, or merge, the agent must check:
+
+- which claim is about to be made
+- which command proves it
+- whether fresh output actually exists
+
+Do not use commit or merge as a way to "close the task and move on" when verification is still missing.
+
+## Bottom Line
+
+**Evidence before claims. Always.**
+
+OpenKit may still lack tooling in many areas, but it must never lack honesty about verification status.