openmoneta-dev-kit 1.9.0

package/hooks.json

@@ -0,0 +1,30 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "bash $HOME/.cursor/hooks/inject-process-context.sh"
+      }
+    ],
+    "preToolUse": [
+      {
+        "matcher": "Write|StrReplace|EditNotebook|Delete",
+        "command": "bash $HOME/.cursor/hooks/check-plan-exists.sh"
+      },
+      {
+        "matcher": "Read|Glob|Grep",
+        "command": "bash $HOME/.cursor/hooks/enforce-docs-first.sh"
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "command": "bash $HOME/.cursor/hooks/track-changes.sh"
+      }
+    ],
+    "stop": [
+      {
+        "command": "bash $HOME/.cursor/hooks/verify-completion.sh"
+      }
+    ]
+  }
+}

package/opencode/AGENTS.md.tpl

@@ -0,0 +1,38 @@
+# OpenMoneta Dev Kit for OpenCode
+
+> Global OpenCode rules installed by OpenMoneta Dev Kit. Project-level `AGENTS.md` still has priority and should be created/synced with `bash ~/.cursor/scripts/init-project.sh .` or the project init workflow documented by this kit.
+
+## Nguyên tắc
+
+1. Luôn trả lời bằng tiếng Việt.
+2. Khi project có `docs/INDEX.md`, đọc file đó trước khi đọc source code để dùng Token Routing.
+3. Dùng OpenMoneta workflow 6 bước: phân tích yêu cầu, thiết kế module, adaptive planning, triển khai, update docs/close plan, safe push khi user yêu cầu push.
+4. Task nhỏ/rõ ràng có thể không cần plan. Task lớn/rủi ro/mơ hồ phải tạo repo plan `Status: Draft`, trình user review, chỉ triển khai sau khi user approve và đổi `Status: In Progress`.
+5. Nếu có plan `In Progress`, chỉ sửa file trong `## Files ảnh hưởng` / `## Files thay đổi`.
+6. Khi user yêu cầu push, phải fetch/rebase remote ngay trước push; không dùng `git push --force` trên shared branch.
+
+## OpenCode Notes
+
+- OpenCode đọc global rules từ `~/.config/opencode/AGENTS.md`.
+- OpenCode đọc project rules từ `AGENTS.md` ở project root. Project rules là source of truth cho từng repo.
+- OpenMoneta skills được cài vào `~/.config/opencode/skills/*/SKILL.md` và agent nên load bằng skill tool khi cần.
+- OpenMoneta subagents được cài vào `~/.config/opencode/agents/`.
+- OpenCode plugin guard trong `~/.config/opencode/plugins/openmoneta-guard.ts` enforce một phần workflow tương đương Cursor hooks.
+
+## Khi Bắt Đầu Task
+
+Nếu project có OpenMoneta files:
+
+1. Read `docs/INDEX.md`.
+2. Read `plans/INDEX.md` để kiểm tra plan active.
+3. Chọn 1-3 module liên quan qua Token Routing.
+4. Read `docs/modules/<module>/README.md` nếu có.
+5. Chỉ sau đó đọc source liên quan.
+
+Nếu project chưa có OpenMoneta files, nhắc user chạy:
+
+```bash
+bash ~/.config/opencode/scripts/init-project.sh .
+```
+
+hoặc hỏi user có muốn khởi tạo project-level files không.

package/opencode/agents/qa-autonomous.md

@@ -0,0 +1,42 @@
+---
+description: ON-DEMAND ONLY. Viết unit/integration test khi user yêu cầu, tự chạy test, debug, fix loop đến khi pass hoặc gặp blocker rõ.
+mode: subagent
+permission:
+  edit: ask
+  bash: ask
+---
+
+Bạn là **qa-autonomous** của OpenMoneta Dev Kit trong OpenCode.
+
+Chỉ dùng khi user yêu cầu viết test hoặc primary agent cần isolation cho test loop.
+
+## Workflow
+
+1. Đọc plan active và Acceptance Criteria/Test Plan nếu có.
+2. Đọc skill `test-strategy` nếu available.
+3. Phát hiện stack qua config (`package.json`, `pyproject.toml`, `go.mod`, ...).
+4. Viết test focused theo behavior, không skip test.
+5. Chạy test liên quan, đọc lỗi đầy đủ, fix root cause, retest.
+6. Dừng sau tối đa 5 vòng nếu không fix được, báo root cause và blocker.
+
+## Quy tắc
+
+- Fix code khi code sai; chỉ sửa test khi assertion/test setup sai.
+- Không dùng `.skip`, `xit`, comment-out test để pass.
+- Một lần thay đổi, một lần verify.
+
+## Output
+
+```markdown
+## QA Result
+
+PASS | FAIL
+
+- Tool:
+- Attempts:
+- Tests added/changed:
+- AC verified:
+- Blocker nếu fail:
+```
+
+Luôn trả lời bằng tiếng Việt.

package/opencode/agents/requirement-analyst.md

@@ -0,0 +1,51 @@
+---
+description: Phân tích yêu cầu phức tạp, đọc tài liệu/codebase, sinh giả thuyết, edge case, rủi ro và đề xuất câu hỏi cho user. Không code.
+mode: subagent
+permission:
+  edit: deny
+  bash: ask
+---
+
+Bạn là **requirement-analyst** của OpenMoneta Dev Kit trong OpenCode.
+
+## Vai trò
+
+Bạn được gọi khi yêu cầu user mơ hồ, lớn, hoặc cần explore rộng. Bạn không edit file. Output là báo cáo phân tích để primary agent quyết định hỏi user hoặc tạo plan.
+
+## Workflow
+
+1. Đọc `docs/INDEX.md` nếu có.
+2. Đọc `plans/INDEX.md` để kiểm tra plan active/overlap.
+3. Đọc module README liên quan qua Token Routing.
+4. Đọc source vừa đủ để hiểu impact, không scan toàn bộ repo.
+5. Tóm tắt yêu cầu, giả thuyết, edge cases, rủi ro, impact.
+6. Đề xuất câu hỏi critical để làm rõ yêu cầu. Mục đích: làm rõ yêu cầu người dùng, phân tích tất cả trường hợp có thể xảy ra, phản biện và đề xuất phương án tối ưu hơn nếu có. Đặt đủ câu hỏi cần thiết, không giới hạn số lượng.
+
+## Output
+
+```markdown
+# Requirement Analysis Report
+
+## Yêu cầu
+<diễn đạt lại ngắn>
+
+## Giả thuyết
+- ...
+
+## Edge cases
+- ...
+
+## Rủi ro
+- ...
+
+## Impact
+- `path/module` — High/Medium/Low — ...
+
+## Câu hỏi đề xuất hỏi user
+1. ...
+
+## Khuyến nghị tiếp theo
+<hỏi user / đủ info để tạo plan / đủ info để code>
+```
+
+Luôn trả lời bằng tiếng Việt, súc tích.

package/opencode/agents/security-auditor.md

@@ -0,0 +1,46 @@
+---
+description: ON-DEMAND ONLY. Audit OWASP Top 10, scan secrets, kiểm tra dependency CVE. Read-only, không edit.
+mode: subagent
+permission:
+  edit: deny
+  bash: ask
+---
+
+Bạn là **security-auditor** của OpenMoneta Dev Kit trong OpenCode.
+
+Chỉ dùng khi user yêu cầu security audit hoặc task chạm auth/payment/PII/admin/permission và primary agent muốn audit độc lập.
+
+## Workflow
+
+1. Xác định scope từ `.cursor/.session-changes.json` nếu có, hoặc từ plan active trong `plans/`.
+2. Audit OWASP Top 10 trong phạm vi file liên quan.
+3. Scan secrets bằng công cụ read-only (`rg`, `git ls-files`, audit package manager nếu phù hợp).
+4. Chỉ report HIGH/CRITICAL dependency CVE nếu có.
+5. Không sửa file.
+
+## Output
+
+```markdown
+# Security Audit Report
+
+## Scope
+- ...
+
+## OWASP Checklist
+- A01 Access Control: Pass/Issue/N/A — ...
+- ...
+
+## Secrets Scan
+- ...
+
+## Dependency CVE
+- ...
+
+## Recommendations
+1. ...
+
+## Verdict
+PASS | FAIL — <kết luận ngắn>
+```
+
+Luôn trả lời bằng tiếng Việt.

package/opencode/agents/ui-tester.md

@@ -0,0 +1,43 @@
+---
+description: ON-DEMAND ONLY. Playwright UI/UX testing multi-viewport, screenshot, loop fix CSS/component khi user yêu cầu UI test.
+mode: subagent
+permission:
+  edit: ask
+  bash: ask
+---
+
+Bạn là **ui-tester** của OpenMoneta Dev Kit trong OpenCode.
+
+Chỉ dùng khi user yêu cầu UI test, visual regression, hoặc test-fix giao diện.
+
+## Workflow
+
+1. Đọc plan active hoặc yêu cầu user để xác định AC UI.
+2. Kiểm tra Playwright đã cài chưa; nếu chưa, hỏi/đề xuất cài.
+3. Chạy multi-viewport: mobile, tablet, desktop.
+4. Lưu screenshot vào `tests/screenshots/<slug>/iter-<n>/`.
+5. Đọc lỗi/screenshot, fix CSS/component, retest.
+6. Sau mỗi 2 vòng, tóm tắt thay đổi và hỏi user nếu hướng visual chưa chắc chắn.
+7. Hard limit 5 vòng trước khi escalate.
+
+## Quy tắc
+
+- Screenshot thật, không đoán bằng đọc code.
+- Không sửa test để né lỗi visual thật.
+- Cleanup state tạm khi hoàn tất.
+
+## Output
+
+```markdown
+## UI Test Result
+
+PASS | FAIL
+
+- Viewports:
+- Screenshots:
+- Attempts:
+- Issues fixed:
+- Blocker nếu fail:
+```
+
+Luôn trả lời bằng tiếng Việt.

package/opencode/plugins/openmoneta-guard.ts

@@ -0,0 +1,389 @@
+import fs from "node:fs"
+import path from "node:path"
+
+type ToolArgs = Record<string, unknown>
+
+const SOURCE_HINTS = [
+  "apps/",
+  "packages/",
+  "src/",
+  "lib/",
+  "components/",
+  "server/",
+  "modules/",
+  "pages/",
+  "/app/",
+]
+
+const SAFE_READ_HINTS = [
+  "docs/",
+  "plans/",
+  ".cursor/",
+  ".opencode/",
+  ".github/",
+  ".vscode/",
+  "AGENTS.md",
+  "README",
+  "CHANGELOG",
+  "LICENSE",
+  "package.json",
+  "tsconfig",
+  "vite.config",
+  "playwright.config",
+  "biome.config",
+  "vitest.config",
+  "astro.config",
+  ".gitignore",
+  "Dockerfile",
+]
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : ""
+}
+
+function projectRoot(ctx: { worktree?: string; directory?: string }): string {
+  const wt = ctx.worktree
+  if (wt && wt !== "/" && wt !== ".") return wt
+  const dir = ctx.directory
+  if (dir && dir !== "/" && dir !== ".") return dir
+  return process.cwd()
+}
+
+function normalize(root: string, filePath: string): string {
+  if (!filePath) return ""
+  return path.isAbsolute(filePath) ? filePath : path.join(root, filePath)
+}
+
+function rel(root: string, filePath: string): string {
+  const abs = normalize(root, filePath)
+  return path.relative(root, abs).replaceAll(path.sep, "/")
+}
+
+function firstPathArg(args: ToolArgs): string {
+  return (
+    asString(args.path) ||
+    asString(args.filePath) ||
+    asString(args.file) ||
+    asString(args.target) ||
+    asString(args.targetFile) ||
+    asString(args.target_file)
+  )
+}
+
+function readTarget(args: ToolArgs): string {
+  return [
+    firstPathArg(args),
+    asString(args.pattern),
+    asString(args.glob),
+    asString(args.query),
+  ]
+    .filter(Boolean)
+    .join(" ")
+}
+
+function bashCommand(args: ToolArgs): string {
+  return asString(args.command) || asString(args.cmd) || asString(args.script)
+}
+
+function isReadTool(tool: string): boolean {
+  return ["read", "glob", "grep", "list"].includes(tool.toLowerCase())
+}
+
+function isBashTool(tool: string): boolean {
+  return ["bash", "shell", "terminal"].includes(tool.toLowerCase())
+}
+
+function isEditTool(tool: string): boolean {
+  return ["write", "edit", "apply_patch", "patch"].includes(tool.toLowerCase())
+}
+
+function shouldCheckRead(tool: string, target: string): boolean {
+  if (!target) return false
+  if (SAFE_READ_HINTS.some((hint) => target.includes(hint))) return false
+  if (["glob", "grep", "list"].includes(tool.toLowerCase())) return true
+  return SOURCE_HINTS.some((hint) => target.includes(hint))
+}
+
+function isSourceSearchCommand(command: string): boolean {
+  if (!command) return false
+  const normalized = command.replaceAll("\\\n", " ")
+  if (!/(^|[;&|()\s])(rg|grep|find|fd|ls|tree|cat|sed|awk|head|tail)\b/.test(normalized)) {
+    return false
+  }
+  if (SOURCE_HINTS.some((hint) => normalized.includes(hint))) return true
+  return !SAFE_READ_HINTS.some((hint) => normalized.includes(hint))
+}
+
+function readsDocsIndexCommand(command: string): boolean {
+  if (!command) return false
+  return command.includes("docs/INDEX.md")
+}
+
+function isSensitivePath(relativePath: string): boolean {
+  const lower = relativePath.toLowerCase()
+  return (
+    lower === ".env" ||
+    lower.startsWith(".env.") ||
+    [
+      "auth",
+      "oauth",
+      "session",
+      "token",
+      "secret",
+      "credential",
+      "security",
+      "permission",
+      "rbac",
+      "role",
+      "admin",
+      "payment",
+      "billing",
+      "invoice",
+      "subscription",
+      "checkout",
+      "db",
+      "database",
+      "schema",
+      "migration",
+      "prisma",
+      "drizzle",
+      "sql",
+      "deploy",
+      "infra",
+    ].some((needle) => lower.includes(needle)) ||
+    lower.startsWith(".github/workflows/")
+  )
+}
+
+function isWhitelistedEdit(relativePath: string): boolean {
+  if (!relativePath) return true
+  if (
+    [
+      "README.md",
+      "README",
+      "CHANGELOG.md",
+      ".gitignore",
+      ".env.example",
+      "AGENTS.md",
+      "LICENSE",
+      "LICENSE.md",
+      "LICENSE.txt",
+    ].includes(relativePath)
+  ) {
+    return true
+  }
+  if (
+    relativePath.startsWith("docs/") ||
+    relativePath.startsWith("plans/") ||
+    relativePath.startsWith(".cursor/") ||
+    relativePath.startsWith(".opencode/") ||
+    relativePath.startsWith(".vscode/")
+  ) {
+    return true
+  }
+  if (relativePath.startsWith(".github/") && !relativePath.startsWith(".github/workflows/")) {
+    return true
+  }
+  if (
+    relativePath.endsWith(".md") &&
+    !["src/", "lib/", "app/", "pages/", "components/"].some((prefix) =>
+      relativePath.startsWith(prefix),
+    )
+  ) {
+    return true
+  }
+  return false
+}
+
+function listPlans(root: string, status: "Draft" | "In Progress"): string[] {
+  const plansDir = path.join(root, "plans")
+  if (!fs.existsSync(plansDir)) return []
+  return fs
+    .readdirSync(plansDir)
+    .filter((file) => file.endsWith(".md") && file !== "INDEX.md")
+    .map((file) => path.join(plansDir, file))
+    .filter((file) => {
+      const content = fs.readFileSync(file, "utf8")
+      return new RegExp(`^\\*{0,2}status\\*{0,2}:?\\s*${status}`, "mi").test(content)
+    })
+}
+
+function planContainsPath(planPath: string, relativePath: string): boolean {
+  const lines = fs.readFileSync(planPath, "utf8").split(/\r?\n/)
+  let inFiles = false
+  for (const line of lines) {
+    if (/^##\s+(Files ảnh hưởng|Files thay đổi|Files changed|Files)\s*$/.test(line)) {
+      inFiles = true
+      continue
+    }
+    if (inFiles && /^##\s+/.test(line)) break
+    if (inFiles && line.includes(relativePath)) return true
+  }
+  return false
+}
+
+function trackChange(root: string, relativePath: string, tool: string) {
+  if (!relativePath) return
+  const cursorDir = path.join(root, ".cursor")
+  fs.mkdirSync(cursorDir, { recursive: true })
+  const trackFile = path.join(cursorDir, ".session-changes.json")
+  const payload = fs.existsSync(trackFile)
+    ? JSON.parse(fs.readFileSync(trackFile, "utf8"))
+    : { started_at: new Date().toISOString(), changes: [] }
+  payload.changes.push({ path: relativePath, ts: new Date().toISOString(), tool })
+  fs.writeFileSync(trackFile, `${JSON.stringify(payload, null, 2)}\n`)
+}
+
+function editedPaths(root: string, args: ToolArgs): string[] {
+  const direct = firstPathArg(args)
+  if (direct) return [rel(root, direct)]
+
+  const patch = asString(args.patch) || asString(args.diff)
+  if (!patch) return []
+
+  const paths: string[] = []
+  for (const line of patch.split(/\r?\n/)) {
+    const match = line.match(/^\*\*\* (?:Add|Update|Delete) File:\s+(.+)$/)
+    if (match?.[1]) paths.push(rel(root, match[1].trim()))
+  }
+  return [...new Set(paths)]
+}
+
+function fail(message: string): never {
+  throw new Error(`[OpenMoneta Dev Kit]\n${message}`)
+}
+
+export const OpenMonetaGuard = async (ctx: { worktree?: string; directory?: string }) => {
+  const globalKey = Symbol.for("openmoneta.devkit.guard.loaded")
+  const globalState = globalThis as Record<symbol, number>
+  globalState[globalKey] = (globalState[globalKey] || 0) + 1
+
+  const root = projectRoot(ctx)
+  const marker = path.join(root, ".cursor", ".docs-index-read")
+  const guardLoadedMarker = path.join(root, ".cursor", ".openmoneta-guard-loaded.json")
+  const docsIndex = path.join(root, "docs", "INDEX.md")
+  const pendingEdits = new Map<string, string[]>()
+
+  fs.mkdirSync(path.dirname(marker), { recursive: true })
+  fs.writeFileSync(
+    guardLoadedMarker,
+    `${JSON.stringify(
+      {
+        loaded_at: new Date().toISOString(),
+        root,
+        version: "1.8.6",
+        load_count: globalState[globalKey],
+      },
+      null,
+      2,
+    )}\n`,
+  )
+
+  // OpenCode does not have Cursor's sessionStart hook, so reset the docs-first
+  // marker when the plugin is loaded for a new OpenCode process/session.
+  if (fs.existsSync(marker)) {
+    fs.rmSync(marker, { force: true })
+  }
+
+  return {
+    "tool.execute.before": async (
+      input: { tool: string; callID?: string },
+      output: { args: ToolArgs },
+    ) => {
+      const tool = input.tool.toLowerCase()
+      const args = output.args || {}
+
+      if (isReadTool(tool) && fs.existsSync(docsIndex)) {
+        const target = readTarget(args)
+        if (target.includes("docs/INDEX.md") || target.endsWith("docs/INDEX.md")) {
+          fs.mkdirSync(path.dirname(marker), { recursive: true })
+          fs.writeFileSync(marker, new Date().toISOString())
+          return
+        }
+        if (shouldCheckRead(tool, target) && !fs.existsSync(marker)) {
+          fail(
+            [
+              "Bạn đang đọc/search source code trước khi đọc `docs/INDEX.md`.",
+              "",
+              "Quy trình đúng:",
+              "1. Read `docs/INDEX.md`.",
+              "2. Dùng Token Routing để chọn module liên quan.",
+              "3. Read module README/source liên quan.",
+            ].join("\n"),
+          )
+        }
+      }
+
+      if (isBashTool(tool) && fs.existsSync(docsIndex)) {
+        const command = bashCommand(args)
+        if (readsDocsIndexCommand(command)) {
+          fs.mkdirSync(path.dirname(marker), { recursive: true })
+          fs.writeFileSync(marker, new Date().toISOString())
+          return
+        }
+        if (isSourceSearchCommand(command) && !fs.existsSync(marker)) {
+          fail(
+            [
+              "Bạn đang chạy shell command đọc/search source code trước khi đọc `docs/INDEX.md`.",
+              "",
+              `Command bị chặn: ${command}`,
+              "",
+              "Quy trình đúng:",
+              "1. Read `docs/INDEX.md` hoặc chạy command đọc `docs/INDEX.md`.",
+              "2. Dùng Token Routing để chọn module liên quan.",
+              "3. Sau đó mới search source liên quan.",
+            ].join("\n"),
+          )
+        }
+      }
+
+      if (isEditTool(tool)) {
+        const paths = editedPaths(root, args)
+        for (const relativePath of paths) {
+          if (isWhitelistedEdit(relativePath)) continue
+
+          const draftPlans = listPlans(root, "Draft")
+          const activePlans = listPlans(root, "In Progress")
+
+          if (activePlans.length === 0) {
+            if (draftPlans.length > 0) {
+              fail(
+                `Có plan Draft nhưng chưa được user approve, nên chưa được sửa code \`${relativePath}\`.\n` +
+                  "Hãy trình plan cho user review, chỉ đổi Status: In Progress sau khi user approve.",
+              )
+            }
+            if (isSensitivePath(relativePath)) {
+              fail(
+                `File \`${relativePath}\` thuộc nhóm nhạy cảm/rủi ro cao nhưng chưa có plan được user approve.\n` +
+                  "Tạo repo plan Status: Draft, trình user review, rồi đổi Status: In Progress sau khi approve.",
+              )
+            }
+            continue
+          }
+
+          if (!activePlans.some((plan) => planContainsPath(plan, relativePath))) {
+            fail(
+              `File \`${relativePath}\` không nằm trong section Files của plan In Progress.\n` +
+                "Update plan scope trước khi sửa file mới.",
+            )
+          }
+        }
+        if (input.callID && paths.length > 0) {
+          pendingEdits.set(input.callID, paths)
+        }
+      }
+    },
+
+    "tool.execute.after": async (input: { tool: string; callID?: string }) => {
+      const tool = input.tool.toLowerCase()
+      if (!isEditTool(tool)) return
+      const paths = input.callID ? pendingEdits.get(input.callID) || [] : []
+      if (input.callID) pendingEdits.delete(input.callID)
+      for (const relativePath of paths) {
+        trackChange(root, relativePath, input.tool)
+      }
+    },
+  }
+}
+
+export default OpenMonetaGuard

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "openmoneta-dev-kit",
+  "version": "1.9.0",
+  "description": "OpenMoneta Dev Kit — Biến Cursor IDE / OpenCode thành team developer hoàn chỉnh với quy trình 6 bước, adaptive planning, hooks enforcement, và token-aware doc routing",
+  "keywords": [
+    "cursor",
+    "opencode",
+    "ai",
+    "developer-tools",
+    "workflow",
+    "vietnamese"
+  ],
+  "homepage": "https://github.com/rapperkey/OpenMoneta-Dev-Kit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rapperkey/OpenMoneta-Dev-Kit.git"
+  },
+  "license": "MIT",
+  "author": "OpenMoneta",
+  "bin": {
+    "openmoneta": "bin/openmoneta.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "skills/",
+    "agents/",
+    "hooks/",
+    "scripts/",
+    "opencode/",
+    "hooks.json"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ]
+}