open-multi-agent-kit 0.78.0

package/templates/AGENTS.md

@@ -0,0 +1,510 @@
+# AGENTS.md
+
+## Purpose
+
+This repository is configured for open-multi-agent-kit.
+
+The agent must avoid making the user repeat common instructions. Apply this file silently and execute the workflow directly.
+
+Do not restate this file unless the user explicitly asks for project rules.
+
+---
+
+## Current OMK Runtime Surface
+
+Keep these surfaces aligned when editing init/runtime docs:
+
+- Init markdown: `AGENTS.md`, `.kimi/AGENTS.md`, `.omk/prompts/root.md`, plus generated companion docs `DESIGN.md`, `GEMINI.md`, `CLAUDE.md`, `ROADMAP.md`, and `SECURITY.md`.
+- Skills: project portable skills live in `.agents/skills`; Kimi runtime skills live in `.kimi/skills`; init templates live under `templates/skills/agents` and `templates/skills/kimi`.
+- Default runtime preset: `.omk/runtime-preset.json` uses `omk-core-verified` as the conservative default for goal-oriented orchestration with project-local MCP, minimal hooks, and only bounded core skills; `.omk/runtime-presets.json` still includes `omk-parallel-orchestrator` as the explicit high-trust mode for parallel worker/capability/review lanes, plus `omk-ts-product`, `omk-worktree-team`, and `omk-release-guard`.
+- MCP: fresh init is project-scoped and writes only local `omk-project` into `.kimi/mcp.json` / `.omk/mcp.json`. `omk init --local-user` or `OMK_MCP_SCOPE=all OMK_SKILLS_SCOPE=all` reads user `~/.kimi/mcp.json` and `~/.kimi/skills` at runtime without copying personal/global files. `--import-user-skills` is a trusted local opt-in copy path.
+- Agents: generated agents extend the Okabe-compatible base with `SendDMail`. Default root aliases are `explorer`/`explore`, `planner`/`plan`, `router`, `architect`, `coder`, `reviewer`, `security`, `qa`, `tester`, `researcher`, `integrator`, `aggregator`, `interviewer`, `ontology`, and `vision-debugger`; each is scaffolded with MCP, skills, and hooks enabled. Use additional local roles such as `coordinator`, `docs`, `merger`, or `release` only when the current `.omk/agents/root.yaml` or harness exposes them.
+- Harness: chat agent mode writes `.omk/runs/<run-id>/chat-agent-harness.json`. Prompts carry compact MCP/skills/hooks counts; read the harness manifest for the full inventory, worker limits, authority boundaries, virtual DAG, and gate list.
+- Evidence: `scripts/run-tests.mjs` and OMK verification surfaces record sanitized MCP/skill/hook resource metadata. Do not emit resource secrets, headers, or raw env values.
+
+---
+
+## Core Operating Rules
+
+1. Read this file before planning or editing.
+2. Read `.kimi/AGENTS.md` if present.
+3. Read `DESIGN.md` before UI, frontend, visual, landing page, or component work.
+4. Use relevant Agent Skills before implementation.
+5. Use MCP tools actively when configured and useful.
+6. Use subagents for non-trivial work.
+7. Use a todo list for any task with more than one action.
+8. Prefer small, reviewable diffs.
+9. Do not claim success until verification is complete or failures are reported.
+10. Do not expose secrets, tokens, private keys, or private user data.
+
+---
+
+## Do Not Repeat Boilerplate
+
+Do not repeatedly say:
+
+- "I will inspect the repository"
+- "I will create a plan"
+- "I will run tests"
+- "I will use AGENTS.md"
+- "I will follow best practices"
+
+Instead:
+
+1. inspect
+2. plan
+3. use tools
+4. update todos
+5. implement
+6. verify
+7. report only concrete results
+
+The final response should be concise and factual.
+
+---
+
+## Todo Policy
+
+For every task with more than one step, call `SetTodoList` immediately when available.
+
+Use 3-8 todos.
+
+Each todo must be action-oriented and verifiable.
+
+Example:
+
+```txt
+1. Inspect project instructions and relevant configs
+2. Map affected files
+3. Create implementation plan
+4. Implement minimal change
+5. Run quality gates
+6. Review diff and report result
+```
+
+Update todo status as work progresses:
+
+```txt
+pending -> in_progress -> done
+```
+
+Never leave the final todo list inconsistent with the actual result.
+
+---
+
+## Agent / Subagent Policy
+
+Use the `Agent` tool or the available OMK/Codex subagent interface for all non-trivial tasks.
+
+Minimum policy:
+
+* Use the `explorer` subagent for repository discovery.
+* Use the `planner` subagent for architecture, refactor, migration, or risky changes.
+* Use `coder` for scoped implementation tasks.
+* Use `reviewer`, `qa`, or a review workflow before final completion.
+
+Do not use subagents for trivial one-line answers or simple command explanations.
+
+Subagent routing:
+
+```txt
+Task type                       Required subagent
+-------------------------------------------------
+Repo exploration                explorer
+Architecture / refactor plan    planner
+Implementation                  coder
+Bug investigation               explorer -> planner -> coder
+Code review                     reviewer skill or review agent
+Quality-gate analysis           qa or omk-quality-gate
+Docs/release work               docs/release role if exposed, else reviewer
+UI / design work                explorer -> coder + design skill
+Security-sensitive changes      planner + security review
+```
+
+When using subagents, give each subagent a focused prompt with:
+
+```txt
+Goal:
+Scope:
+Files/directories:
+Constraints:
+Expected output:
+```
+
+Do not ask subagents to modify unrelated files. Workers are not alone in the codebase: they must preserve concurrent edits and avoid reverting unrelated changes.
+
+### Parallel Agent Limits
+
+When `OMK_WORKERS` is set (e.g. via `omk chat --workers <n>`):
+
+- Respect the worker count. Do not spawn more parallel agents than `OMK_WORKERS`.
+- When `OMK_WORKERS=1`, run agents sequentially.
+- When `OMK_WORKERS=auto`, use the resource profile default (usually 2-4).
+
+When `--max-steps-per-turn` is set (e.g. via `omk chat --max-steps-per-turn <n>`):
+
+- Treat it as the tool-use budget for the current turn.
+- Prioritize tools: use the most impactful tool first.
+- If the limit is reached, stop tool use and summarize findings to the user.
+
+---
+
+## Skills Policy
+
+Before starting, inspect the loaded skills list.
+
+Use relevant skills when they match the task. Read only the matching `SKILL.md` entrypoints and directly referenced assets.
+
+Project portable skills currently packaged in `.agents/skills` include:
+
+```txt
+claude-for-legal
+agentmemory
+andrej-karpathy-skills
+matt-pocock-skills
+multica
+react-doctor
+omk-backend-api-review
+omk-adaptorch-orchestration-review
+omk-code-review
+omk-context-broker
+omk-control-loop-debugger
+omk-design-system
+omk-docs-release
+omk-evidence-contract
+omk-frontend-implementation
+omk-frontend-ui-review
+omk-git-commit-pr
+omk-industrial-control-loop
+omk-plan-first
+omk-project-rules
+omk-python-typing
+omk-quality-gate
+omk-repo-explorer
+omk-research-verify
+omk-secret-guard
+omk-security-review
+omk-test-debug-loop
+omk-troubleshooting
+omk-typescript-strict
+omk-worktree-team
+```
+
+Packaged Kimi skill templates include OMK runtime/flow skills (`omk-kimi-runtime`, `omk-plan-first`, `omk-task-router`, `omk-global-rules`, `omk-flow-*`), custom orchestration/evidence/control-loop skills (`omk-adaptorch-orchestration-review`, `omk-evidence-contract`, `omk-control-loop-debugger`), design/visual skills (`omk-design-md`, `omk-multimodal-ui-review`, `open-design`, `awesome-design-md`), graph/spec skills (`graph-view`, `speckit-*`), legal workflow support (`claude-for-legal`), external-inspired agent workflow skills (`agentmemory`, `andrej-karpathy-skills`, `matt-pocock-skills`, `multica`, `react-doctor`), and DeepSeek helpers (`deepseek-*`). Local `.kimi/skills` may expose extra user/runtime skills such as `kb-retriever`, `gpt-image-2`, `diagram-design`, or web presentation helpers; use them only when present in the loaded skills list. Skill packs advertised by `omk skill pack` include `omk-priority`, `omk-agentic-ops`, `omk-core`, `omk-spec-driven`, `omk-typescript`, `omk-security`, `omk-review`, and `omk-release`.
+
+Rules:
+
+* Read only relevant `SKILL.md` files.
+* Do not read every skill blindly.
+* Do not mention internal skill selection unless it affects the final result.
+* If a project-specific skill conflicts with a global skill, project-specific rules win.
+* If `DESIGN.md` exists, use `omk-design-md`, `omk-design-system`, or the current design skill for UI/frontend tasks.
+* For legal-domain Claude workflow requests, use `claude-for-legal` as a workflow skill; it is not a substitute for legal advice.
+* For memory, alignment/TDD, React diagnostics, managed-agent teamwork, or surgical-coding requests, use the matching external-inspired workflow skill before implementation.
+
+---
+
+## MCP Policy
+
+Use configured MCP tools actively when they provide better context than local guessing.
+
+Preferred MCP usage:
+
+```txt
+Project memory/task state       omk-project MCP if configured
+Library/API documentation       context7 or official-doc MCP
+Browser/UI debugging            chrome-devtools MCP
+GitHub issues/PRs               github MCP
+Design/token workflow           design-md or stitch-related MCP if configured
+```
+
+Runtime scope rules:
+
+* Default project scope reads project `.kimi/mcp.json` and `.omk/mcp.json`; the generated safe default is `omk-project` only.
+* All scope may read user `~/.kimi/mcp.json` at runtime; do not copy or print global MCP secrets.
+* The managed `omk-project` mirror may appear in both project files; treat it as informational unless health checks fail.
+* Use `omk mcp doctor`, `omk mcp list`, or `omk mcp test <server>` for MCP verification when the task depends on MCP behavior.
+
+Rules:
+
+* Prefer official docs over memory for version-sensitive facts.
+* Do not fabricate MCP results.
+* If an MCP server is unavailable, continue with local tools and clearly report the limitation.
+* Do not send secrets to MCP tools.
+* Do not use remote MCP tools for private code unless the user configured and approved them.
+
+---
+
+## Harness / Evidence Policy
+
+- If a prompt, contract, or run directory references `chat-agent-harness.json`, read it before assuming which MCP servers, skills, hooks, gates, or workers are active.
+- Treat compact prompt inventory counts as a summary only; the harness manifest is the source of truth for full inventory.
+- Keep evidence artifacts under `.omk/runs/<run-id>/`, `.omk/goals/<goal-id>/`, or the command-specific output path.
+- `omk verify --json`, replay/cockpit artifacts, test summaries, and secret scans are stronger completion evidence than narrative claims.
+- Do not paste large skill/MCP inventories into prompts or final reports.
+
+---
+
+## Provider Runtime Policy
+
+Use the selected provider runtime as a long-horizon coding and agentic execution model, with OMK as the root orchestrator identity and every model/provider treated as an adapter lane. Models execute; OMK routes, verifies, measures, and controls.
+
+Rules:
+
+* Use thinking mode for planning, coding, debugging, architecture, review, and multi-step tool work when the selected runtime supports it.
+* Use no-thinking or fast mode for short summaries, commit messages, simple classification, and web-search-heavy research when configured.
+* Do not rely on long context as an excuse to read the whole repository.
+* Build a repo map first, then read targeted files.
+* Preserve important intermediate reasoning/tool context when running multi-step tool workflows.
+* Do not expose or request temperature/top_p tuning from users.
+
+For web-heavy research, prefer a no-thinking research profile when the runtime supports it.
+
+---
+
+## Okabe / D-Mail Policy
+
+This project is a provider-neutral agent runtime for coding workflows. Generated agents should inherit the Okabe-compatible base agent so the `SendDMail` tool is available. Use Okabe smart context management plus D-Mail checkpoints before risky refactors, context compaction, multi-agent handoffs, or rollback-prone work. D-Mail notes should be concise recovery records: current goal, changed files, verification state, blockers, and intended next action.
+
+## Context Policy
+
+Do not dump the entire repository into context.
+
+Use this order:
+
+1. Read AGENTS.md and project-specific instructions.
+2. Inspect top-level files.
+3. Identify package manager and framework.
+4. Use Glob/Grep to locate relevant files.
+5. Read the smallest useful file set.
+6. Expand through imports, routes, schemas, tests, and call sites.
+7. Use Okabe/D-Mail for smart context checkpoints and store stable facts through project-local graph memory (`omk_write_memory`, `omk_memory_mindmap`, `omk_graph_query`); `.omk/memory/` is only a local mirror.
+
+Memory policy:
+
+Project-local graph memory is the default source of truth for project/session recall. Use `omk_read_memory`, `omk_write_memory`, `omk_memory_mindmap`, `omk_graph_query`, `omk_read_run_memory`, and `omk_write_run_memory` when available; `.omk/memory/` remains a readable mirror/cache.
+
+Memory files:
+
+```txt
+.omk/memory/project.md
+.omk/memory/decisions.md
+.omk/memory/commands.md
+.omk/memory/risks.md
+.omk/runs/<run-id>/plan.md
+.omk/runs/<run-id>/final-report.md
+```
+
+Never store secrets in memory.
+
+---
+
+## Project Discovery
+
+Before implementation, inspect relevant files:
+
+```txt
+package.json
+pnpm-lock.yaml
+yarn.lock
+package-lock.json
+tsconfig.json
+eslint.config.*
+next.config.*
+nest-cli.json
+vite.config.*
+pyproject.toml
+requirements.txt
+uv.lock
+ruff.toml
+pytest.ini
+Dockerfile
+docker-compose.*
+.github/workflows/*
+```
+
+Infer:
+
+```txt
+package manager
+framework
+lint command
+typecheck command
+test command
+build command
+source directories
+test directories
+generated files
+protected files
+```
+
+---
+
+## Implementation Policy
+
+Before editing:
+
+1. understand existing conventions
+2. find affected files
+3. create todos
+4. use a subagent when non-trivial
+5. make the smallest correct change
+
+While editing:
+
+* Do not rewrite unrelated code.
+* Do not weaken types to pass builds.
+* Do not delete tests to pass.
+* Do not silence errors without justification.
+* Do not introduce broad refactors inside bugfixes.
+* Do not modify generated files unless required.
+
+For TypeScript:
+
+* Assume strict mode.
+* Avoid `any`; prefer `unknown` with narrowing.
+* Add explicit return types to exported functions.
+* Keep API DTO, domain, and persistence types separate.
+
+For Python:
+
+* Use type hints for public functions.
+* Prefer `pathlib.Path`.
+* Keep IO and business logic separate.
+* Do not silence pyright/ruff without reason.
+
+---
+
+## Quality Gate
+
+Before saying a task is complete, run available checks.
+
+Preferred commands:
+
+```bash
+npm run yaml:check
+npm run lint
+npm run secret:scan
+npm run check
+npm run build:clean
+npm test
+```
+
+Use actual project scripts when different.
+
+If commands are unavailable, report that clearly.
+
+Final report must include:
+
+```txt
+Changed files:
+Commands run:
+Passed:
+Failed:
+Not run:
+Reason not run:
+Remaining risk:
+```
+
+Do not say "tests passed" unless tests were actually run.
+
+---
+
+## Security Rules
+
+Never print, store, commit, or summarize secrets from:
+
+```txt
+.env
+.env.*
+*.pem
+*.key
+id_rsa
+id_ed25519
+credentials.json
+service-account*.json
+```
+
+Block or request approval for:
+
+```txt
+rm -rf
+sudo
+git push --force
+git clean -fdx
+chmod -R 777
+curl | bash
+wget | sh
+docker system prune
+kubectl delete
+aws s3 rm --recursive
+```
+
+For auth, payment, database, deployment, shell, file upload, or permission changes, run a security review before final response.
+
+---
+
+## DESIGN.md / UI Policy
+
+If the task touches UI/frontend/design:
+
+1. Read `DESIGN.md` if present.
+2. Inspect existing components.
+3. Use existing tokens before inventing styles.
+4. Check responsive states.
+5. Check loading, error, and empty states.
+6. Check accessibility.
+7. Use screenshots or media files when available.
+
+Do not invent arbitrary colors or component styles if design tokens exist.
+
+---
+
+## Git Policy
+
+Before major edits:
+
+```bash
+git status --short
+```
+
+Do not overwrite user changes.
+
+Do not run destructive git commands unless explicitly approved.
+
+When generating commit messages, use Conventional Commits:
+
+```txt
+feat(scope): summary
+fix(scope): summary
+refactor(scope): summary
+test(scope): summary
+docs(scope): summary
+chore(scope): summary
+```
+
+PR summaries must be factual and include test results.
+
+---
+
+## Final Response Policy
+
+Final response should be short and concrete.
+
+Include:
+
+```txt
+What changed:
+Files changed:
+Commands run:
+Result:
+Remaining risk:
+```
+
+Do not include long internal reasoning.
+
+Do not repeat AGENTS.md rules.
+
+Do not overclaim.
+
+If something failed, say exactly what failed and what remains.

package/templates/skills/agents/agentmemory/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: agentmemory
+description: Persistent memory, recall, session replay, and memory-governance workflow adapted from rohitg00/agentmemory for OMK. Use when setting up agent memory, deciding what to remember, importing/replaying sessions, reducing repeated context, or auditing memory safety.
+---
+
+# agentmemory
+
+Source basis: rohitg00/agentmemory at commit 25dddc43798c09f8e1dc5179eb48e434a5c89ab2. This OMK skill is a compact adaptation, not a vendored copy of upstream prompts or code.
+
+## Use when
+
+- A task depends on prior decisions, run history, project facts, or repeated architecture context.
+- You need to design or review MCP/hook-based persistent memory for coding agents.
+- You need replayable evidence for prompts, tool calls, diffs, checks, or completion gates.
+- You are deciding what is safe to store in project memory.
+
+## OMK workflow
+
+1. Inventory memory surfaces: `.omk/memory`, `.omk/runs`, `.kimi/skills`, `.agents/skills`, MCP config, and available graph-memory tools.
+2. Classify candidate memories as project fact, decision, command, risk, user preference, or run-scoped note.
+3. Store only stable, useful, non-secret facts. Include confidence, scope, source, and expiry/refresh trigger when the fact may drift.
+4. Prefer OMK project graph memory when available. Treat external memory servers as optional integrations that must pass local health checks before use.
+5. For replay/evidence tasks, preserve raw prompt, generated diff, verification JSON/logs, screenshots, and known limitations in one artifact bundle.
+6. Before finalizing, verify memory updates did not include credentials, private data, or unvalidated claims.
+
+## Output contract
+
+Return:
+
+- memory sources consulted
+- memories added or skipped
+- verification artifacts
+- replay/proof paths
+- limitations and refresh triggers
+
+## Guardrails
+
+- Never write secrets, tokens, private keys, cookies, or raw `.env` values into memory.
+- Do not let memory override current source files, official docs, or live command results.
+- Do not install or start external memory services unless the user asked for that operational change.

package/templates/skills/agents/andrej-karpathy-skills/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: andrej-karpathy-skills
+description: Minimal, goal-driven, surgical coding workflow adapted from forrestchang/andrej-karpathy-skills for OMK. Use for coding, refactoring, debugging, and review tasks where assumptions, overengineering, or broad edits could cause regressions.
+---
+
+# andrej-karpathy-skills
+
+Source basis: forrestchang/andrej-karpathy-skills at commit 2c606141936f1eeef17fa3043a72095b4765b9c2. This OMK skill is a compact adaptation, not a vendored copy of upstream prompts or code.
+
+## Use when
+
+- Any non-trivial code change needs tight scope and proof.
+- The request is ambiguous enough that silent assumptions could be wrong.
+- A refactor or bugfix risks drive-by edits.
+- You need to turn an imperative request into verifiable success criteria.
+
+## OMK workflow
+
+1. State assumptions and tradeoffs only when they affect the implementation path. Ask if ambiguity blocks safe progress.
+2. Define success as observable checks: tests, typecheck, lint, build, screenshots, replay, or exact output.
+3. Make the smallest change that satisfies the goal. Avoid speculative abstractions and features not requested.
+4. Touch only files directly tied to the request. Preserve existing style and avoid unrelated cleanup.
+5. Remove only dead code introduced by your own change unless the user asked for broader cleanup.
+6. Verify, inspect the diff, and report remaining risks honestly.
+
+## Output contract
+
+Return:
+
+- assumptions that mattered
+- success criteria and checks
+- changed files
+- commands run
+- pass/fail status
+- risks or blocked items
+
+## Guardrails
+
+- Do not broaden scope to improve adjacent code.
+- Do not hide confusion behind a confident implementation.
+- Do not claim completion without evidence.

package/templates/skills/agents/claude-for-legal/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: claude-for-legal
+description: Legal workflow drafting, triage, review, research planning, legal operations, law-student or clinic support, and legal AI governance adapted from Anthropic claude-for-legal. Use for commercial, privacy, product, corporate, employment, regulatory, AI governance, IP, litigation, legal-clinic, and law-student tasks. Draft-only; attorney review and current source verification required.
+---
+
+# Claude for Legal
+
+Use this skill when the user asks for legal workflow help: contract review, legal triage, policy/regulatory analysis, legal research planning, compliance checklists, litigation support, legal ops trackers, law-student practice, or clinic-style intake/drafting.
+
+Source basis: Anthropic `claude-for-legal` at `anthropics/claude-for-legal` commit `9cecd91b0f26f732d18315afc3c9bb5ff99e0fbb`, Apache-2.0. This OMK skill is a compact adaptation, not a vendored copy of upstream prompts.
+
+## Non-negotiables
+
+- Treat outputs as AI-assisted drafts for qualified attorney review, not legal advice or legal conclusions.
+- Do not file, send, sign, threaten, accept, reject, waive rights, or communicate externally without an explicit user gate and attorney-review note.
+- Identify jurisdiction, governing law, audience, role of the user, deadline, and source set. If unknown and material, ask; if proceeding, state assumptions.
+- For current law, citations, statutes, regulations, court rules, agency guidance, or case law, verify with authoritative/current sources before relying. If not verified, label citations and conclusions as needing verification.
+- Never invent citations, docket facts, quotes, party facts, deadlines, or regulatory text.
+- Preserve privilege/confidentiality boundaries; avoid putting sensitive facts into external tools unless user has configured and approved them.
+- If user is not a lawyer, structure output as an attorney-facing brief with plain-English risk explanations and clear questions for counsel.
+
+## Core workflow
+
+1. **Classify lane**: choose practice area and workflow. Load `references/workflow-catalog.md` when mapping is not obvious.
+2. **Intake**: collect only missing material facts: role, jurisdiction, document/source corpus, transaction/matter context, risk appetite, deadline, intended audience, and requested output.
+3. **Source preflight**: record what sources were actually checked. Prefer official/primary sources; use legal research connectors/MCPs only if configured. Otherwise browse authoritative sources or mark `[verify]`.
+4. **Analyze conservatively**: separate facts, assumptions, legal issues, risk level, source-backed points, open questions, and attorney decisions.
+5. **Gate consequential action**: give draft language/checklist/memo, then list what must be reviewed before use.
+
+## Default output skeleton
+
+```md
+# AI-assisted legal workflow draft — attorney review required
+
+- Role/audience:
+- Jurisdiction/governing law:
+- Scope:
+- Sources checked:
+- Verification gaps:
+- Assumptions:
+
+## Executive summary
+## Key issues / risk flags
+## Analysis
+## Draft / checklist / table
+## Open questions for counsel
+## Pre-use review gate
+```
+
+## Risk language
+
+Use cautious labels: `Blocking`, `High`, `Medium`, `Low`, `Information needed`. Explain each label in business/plain-English terms. Avoid saying a position is “legal,” “compliant,” “privileged,” or “safe” unless verified and still framed for attorney judgment.
+
+## Citation rules
+
+- Attach source/provenance to every legal authority or factual extraction from documents.
+- Distinguish primary authority, secondary source, model reasoning, and user-provided facts.
+- If a citation comes from model knowledge or an unverified web result, tag it `[verify]` and place it in verification gaps.
+- Quote only short excerpts needed for analysis; prefer paraphrase and pinpoint citations.
+
+## Practice profile pattern
+
+When a matter will continue across turns, create or update a concise practice/matter profile in the working docs, not in global memory unless explicitly asked. Include: client/company context, role, jurisdiction footprint, escalation contacts, risk posture, house style, source locations, and current open questions. Do not store secrets.