@duypham93/openkit 0.2.0

package/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.

package/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/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/src/audit/vietnamese-detection.js

@@ -0,0 +1,259 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+import { OPENKIT_ASSET_MANIFEST } from '../install/asset-manifest.js';
+
+const TEXT_EXTENSIONS = new Set(['.md', '.txt']);
+const MACHINE_EXTENSIONS = new Set(['.json', '.js']);
+const VIETNAMESE_DIACRITIC_REGEX = /[\u00C0-\u1EF9]/u;
+const EXCLUDED_TOP_LEVEL_NAMES = new Set(['.git', '.worktrees', 'node_modules']);
+const EXCLUDED_RELATIVE_PREFIXES = ['.git/', '.worktrees/', 'node_modules/'];
+
+const HIGH_PRIORITY_PREFIXES = ['skills/', 'agents/', 'commands/', '.opencode/README.md'];
+const MEDIUM_PRIORITY_PREFIXES = ['docs/', 'assets/install-bundle/opencode/'];
+
+function walkFiles(rootPath, relativePath = '') {
+  const targetPath = relativePath ? path.join(rootPath, relativePath) : rootPath;
+  if (!fs.existsSync(targetPath)) {
+    return [];
+  }
+
+  const stat = fs.statSync(targetPath);
+  if (stat.isFile()) {
+    return [relativePath || path.basename(targetPath)];
+  }
+
+  const files = [];
+  for (const entry of fs.readdirSync(targetPath, { withFileTypes: true })) {
+    const childRelativePath = relativePath ? path.join(relativePath, entry.name) : entry.name;
+    if (entry.isDirectory() && shouldExcludePath(childRelativePath)) {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      files.push(...walkFiles(rootPath, childRelativePath));
+      continue;
+    }
+    if (shouldExcludePath(childRelativePath)) {
+      continue;
+    }
+    files.push(childRelativePath);
+  }
+
+  return files;
+}
+
+function listTrackedFiles(projectRoot) {
+  const result = spawnSync('git', ['ls-files', '--cached', '--others', '--exclude-standard'], {
+    cwd: projectRoot,
+    encoding: 'utf8',
+  });
+
+  if (result.status !== 0) {
+    return null;
+  }
+
+  const trackedFiles = new Set();
+
+  for (const line of result.stdout.split('\n')) {
+    const normalizedPath = line.trim();
+    if (!normalizedPath) {
+      continue;
+    }
+
+    const absolutePath = path.join(projectRoot, normalizedPath);
+    if (!fs.existsSync(absolutePath)) {
+      continue;
+    }
+
+    const stat = fs.statSync(absolutePath);
+    if (!stat.isFile()) {
+      continue;
+    }
+
+    trackedFiles.add(normalizedPath);
+  }
+
+  return trackedFiles;
+}
+
+function listCheckedInFiles(projectRoot) {
+  const gitTrackedFiles = spawnSync('git', ['ls-files', '--cached'], {
+    cwd: projectRoot,
+    encoding: 'utf8',
+  });
+
+  if (gitTrackedFiles.status === 0) {
+    const files = new Set();
+
+    for (const line of gitTrackedFiles.stdout.split('\n')) {
+      const normalizedPath = line.trim();
+      if (!normalizedPath) {
+        continue;
+      }
+
+      const absolutePath = path.join(projectRoot, normalizedPath);
+      if (!fs.existsSync(absolutePath)) {
+        continue;
+      }
+
+      const stat = fs.statSync(absolutePath);
+      if (!stat.isFile()) {
+        continue;
+      }
+
+      files.add(normalizedPath);
+    }
+
+    return files;
+  }
+
+  return new Set(walkFiles(projectRoot));
+}
+
+function shouldExcludePath(filePath) {
+  const normalizedPath = filePath.split(path.sep).join('/');
+  if (EXCLUDED_TOP_LEVEL_NAMES.has(normalizedPath)) {
+    return true;
+  }
+
+  return EXCLUDED_RELATIVE_PREFIXES.some(
+    (prefix) => normalizedPath === prefix.slice(0, -1) || normalizedPath.startsWith(prefix)
+  );
+}
+
+function isTextCandidate(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  return TEXT_EXTENSIONS.has(extension) || MACHINE_EXTENSIONS.has(extension);
+}
+
+function isMachineFacing(filePath) {
+  return MACHINE_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+
+function readUtf8(projectRoot, relativePath) {
+  return fs.readFileSync(path.join(projectRoot, relativePath), 'utf8');
+}
+
+function classifyPriority(filePath) {
+  if (HIGH_PRIORITY_PREFIXES.some((prefix) => filePath === prefix || filePath.startsWith(prefix))) {
+    return 'high';
+  }
+
+  if (MEDIUM_PRIORITY_PREFIXES.some((prefix) => filePath === prefix || filePath.startsWith(prefix))) {
+    return 'medium';
+  }
+
+  return 'low';
+}
+
+function buildPairingMap() {
+  const derivedPairs = OPENKIT_ASSET_MANIFEST.bundle.assets
+    .filter((asset) => asset.sourcePath !== asset.bundledPath)
+    .map((asset) => ({
+      sourcePath: asset.sourcePath,
+      derivedPath: asset.bundledPath,
+      assetId: asset.id,
+      derived: true,
+    }));
+
+  derivedPairs.push({
+    sourcePath: '.opencode/README.md',
+    derivedPath: 'assets/install-bundle/opencode/README.md',
+    assetId: 'opencode.bundle.runtime-readme',
+    derived: true,
+  });
+
+  return derivedPairs.sort((left, right) => left.sourcePath.localeCompare(right.sourcePath));
+}
+
+export function detectVietnameseInventory(projectRoot) {
+  const filesToScan = listCheckedInFiles(projectRoot);
+
+  const textFiles = [...filesToScan].filter(isTextCandidate).sort((left, right) => left.localeCompare(right));
+  const humanFacingMatches = [];
+  const machineFacingMatches = [];
+
+  for (const filePath of textFiles) {
+    const contents = readUtf8(projectRoot, filePath);
+    if (!VIETNAMESE_DIACRITIC_REGEX.test(contents)) {
+      continue;
+    }
+
+    const match = {
+      path: filePath,
+      priority: classifyPriority(filePath),
+      machineFacing: isMachineFacing(filePath),
+    };
+
+    if (match.machineFacing) {
+      machineFacingMatches.push(match);
+      continue;
+    }
+
+    humanFacingMatches.push(match);
+  }
+
+  const pairingMap = buildPairingMap();
+  const matchedPaths = new Set(humanFacingMatches.map((match) => match.path));
+  const pairingSummary = pairingMap.map((pair) => ({
+    ...pair,
+    sourceHasVietnamese: matchedPaths.has(pair.sourcePath),
+    derivedHasVietnamese: matchedPaths.has(pair.derivedPath),
+  }));
+
+  const priorityCounts = {
+    high: humanFacingMatches.filter((match) => match.priority === 'high').length,
+    medium: humanFacingMatches.filter((match) => match.priority === 'medium').length,
+    low: humanFacingMatches.filter((match) => match.priority === 'low').length,
+  };
+
+  return {
+    detectionMode: 'heuristic',
+    detectionScope: 'repo-wide checked-in files',
+    explicitExclusions: [...EXCLUDED_TOP_LEVEL_NAMES],
+    scannedFileCount: textFiles.length,
+    vietnameseBearingFiles: humanFacingMatches,
+    machineFacingMatches,
+    machineFacingOutOfScope: machineFacingMatches.length === 0,
+    priorityCounts,
+    pairingMap: pairingSummary,
+  };
+}
+
+export function renderVietnameseInventoryReport(inventory) {
+  const lines = [];
+  lines.push(`Inventory status: ${inventory.vietnameseBearingFiles.length > 0 ? 'matches-found' : 'clear'}`);
+  lines.push(`Detection scope: ${inventory.detectionScope}`);
+  lines.push(`Detection mode: ${inventory.detectionMode}`);
+  lines.push('Heuristic review: required for false positives and false negatives');
+  lines.push(`Scanned files: ${inventory.scannedFileCount}`);
+  lines.push(
+    `Priority counts: high=${inventory.priorityCounts.high}, medium=${inventory.priorityCounts.medium}, low=${inventory.priorityCounts.low}`
+  );
+  lines.push(`Explicit exclusions: ${inventory.explicitExclusions.join(', ')}`);
+  lines.push(
+    `Machine-facing literals: ${inventory.machineFacingOutOfScope ? 'out-of-scope confirmed' : 'review needed'}`
+  );
+
+  const completePairingCoverage = inventory.pairingMap.every(
+    (pair) => pair.sourceHasVietnamese === pair.derivedHasVietnamese
+  );
+  lines.push(`Pairing map coverage: ${completePairingCoverage ? 'complete' : 'mismatch-detected'}`);
+  lines.push('');
+  lines.push('Vietnamese-bearing checked-in files:');
+
+  for (const match of inventory.vietnameseBearingFiles) {
+    lines.push(`- [${match.priority}] ${match.path}`);
+  }
+
+  lines.push('');
+  lines.push('Source-versus-derived pairing map:');
+  for (const pair of inventory.pairingMap) {
+    lines.push(
+      `- ${pair.sourcePath} -> ${pair.derivedPath} [source=${pair.sourceHasVietnamese ? 'vi' : 'clear'}, derived=${pair.derivedHasVietnamese ? 'vi' : 'clear'}]`
+    );
+  }
+
+  return `${lines.join('\n')}\n`;
+}

package/src/cli/commands/detect-vietnamese.js

@@ -0,0 +1,24 @@
+import { detectVietnameseInventory, renderVietnameseInventoryReport } from '../../audit/vietnamese-detection.js';
+
+function detectVietnameseHelp() {
+  return [
+    'Usage: openkit internal-audit-vietnamese',
+    '',
+    'Run the maintainer audit helper for heuristic Vietnamese detection across repo-wide checked-in files.',
+    'This helper uses heuristics and still requires review for false positives and false negatives.',
+  ].join('\n');
+}
+
+export const detectVietnameseCommand = {
+  name: 'internal-audit-vietnamese',
+  async run(args = [], io) {
+    if (args.includes('--help') || args.includes('-h')) {
+      io.stdout.write(`${detectVietnameseHelp()}\n`);
+      return 0;
+    }
+
+    const inventory = detectVietnameseInventory(process.cwd());
+    io.stdout.write(renderVietnameseInventoryReport(inventory));
+    return 0;
+  },
+};

package/src/cli/commands/doctor.js

@@ -0,0 +1,33 @@
+import { inspectGlobalDoctor, renderGlobalDoctorSummary } from '../../global/doctor.js';
+
+function doctorHelp() {
+  return [
+    'Usage: openkit doctor',
+    '',
+    'Check whether the global OpenKit install and the current workspace are ready.',
+  ].join('\n');
+}
+
+export const doctorCommand = {
+  name: 'doctor',
+  async run(args = [], io) {
+    if (args.includes('--help') || args.includes('-h')) {
+      io.stdout.write(`${doctorHelp()}\n`);
+      return 0;
+    }
+
+    const result = inspectGlobalDoctor({
+      projectRoot: process.cwd(),
+      env: process.env,
+    });
+    const output = renderGlobalDoctorSummary(result);
+
+    if (result.canRunCleanly) {
+      io.stdout.write(output);
+      return 0;
+    }
+
+    io.stdout.write(output);
+    return 1;
+  },
+};

package/src/cli/commands/help.js

@@ -0,0 +1,33 @@
+function topLevelHelp() {
+  return [
+    'Usage: openkit <command> [options]',
+    '',
+    'Quickstart:',
+    '  npm install -g openkit',
+    '  openkit run',
+    '',
+    'Commands:',
+    '  help      Show CLI help',
+    '  install-global  Manual global setup command',
+    '  init      Compatibility alias for install-global',
+    '  install   Compatibility alias for install-global',
+    '  run       Launch OpenCode and perform first-time setup if needed',
+    '  upgrade   Refresh the global OpenKit install',
+    '  uninstall Remove the global OpenKit install',
+    '  doctor    Inspect global OpenKit and workspace readiness',
+  ].join('\n');
+}
+
+export const helpCommand = {
+  name: 'help',
+  async run(args = [], io, context = {}) {
+    const [target] = args;
+
+    if (target && context.commands?.[target]) {
+      return context.commands[target].run(['--help'], io, context);
+    }
+
+    io.stdout.write(`${topLevelHelp()}\n`);
+    return 0;
+  },
+};

package/src/cli/commands/init.js

@@ -0,0 +1,25 @@
+import { materializeGlobalInstall } from '../../global/materialize.js';
+
+function initHelp() {
+  return [
+    'Usage: openkit init',
+    '',
+    'Compatibility alias for manual global setup.',
+    'Most users should run `openkit run`.',
+  ].join('\n');
+}
+
+export const initCommand = {
+  name: 'init',
+  async run(args = [], io) {
+    if (args.includes('--help') || args.includes('-h')) {
+      io.stdout.write(`${initHelp()}\n`);
+      return 0;
+    }
+
+    const result = materializeGlobalInstall({ env: process.env });
+    io.stdout.write('Installed OpenKit globally.\n');
+    io.stdout.write(`Kit root: ${result.kitRoot}\n`);
+    return 0;
+  },
+};

package/src/cli/commands/install-global.js

@@ -0,0 +1,26 @@
+import { materializeGlobalInstall } from '../../global/materialize.js';
+
+function installGlobalHelp() {
+  return [
+    'Usage: openkit install-global',
+    '',
+    'Manually install OpenKit globally into the OpenCode home directory.',
+    'Most users should run `openkit run`, which performs first-time setup automatically.',
+  ].join('\n');
+}
+
+export const installGlobalCommand = {
+  name: 'install-global',
+  async run(args = [], io) {
+    if (args.includes('--help') || args.includes('-h')) {
+      io.stdout.write(`${installGlobalHelp()}\n`);
+      return 0;
+    }
+
+    const result = materializeGlobalInstall({ env: process.env });
+    io.stdout.write(`Installed OpenKit globally.\n`);
+    io.stdout.write(`Kit root: ${result.kitRoot}\n`);
+    io.stdout.write(`Profile root: ${result.profilesRoot}\n`);
+    return 0;
+  },
+};

package/src/cli/commands/install.js

@@ -0,0 +1,25 @@
+import { materializeGlobalInstall } from '../../global/materialize.js';
+
+function installHelp() {
+  return [
+    'Usage: openkit install',
+    '',
+    'Compatibility alias for manual global setup.',
+    'Most users should run `openkit run`.',
+  ].join('\n');
+}
+
+export const installCommand = {
+  name: 'install',
+  async run(args = [], io) {
+    if (args.includes('--help') || args.includes('-h')) {
+      io.stdout.write(`${installHelp()}\n`);
+      return 0;
+    }
+
+    const result = materializeGlobalInstall({ env: process.env });
+    io.stdout.write('Installed OpenKit globally.\n');
+    io.stdout.write(`Kit root: ${result.kitRoot}\n`);
+    return 0;
+  },
+};