A sharp little toolkit of agent plugins. Each plugin is independently installable — take only what you need.

/plugin marketplace add Dandi007/katana
/plugin install guide@katana
/plugin install work-folder@katana
/plugin install deep-research@katana
/plugin install memory@katana
/plugin install obsidian-md@katana
/plugin install wiki@katana
/plugin install retrieval@katana
/plugin install fpa@katana

Enable/disable any plugin independently with /plugin.

katana provides an OpenCode parity adapter that enables the same hook implementations to work on OpenCode. Install via npm:

opencode plugin opencode-katana

Or for development, add the local path to your opencode.json:

{
  "plugin": ["/path/to/katana"]
}

The adapter maps OpenCode events to Claude Code hook semantics, spawning the same plugins/*/hooks/* scripts. SessionStart hooks inject context (guide, work-folder, retrieval, wiki), PostToolUse hooks validate FPA documents, and all skills are exposed to OpenCode's skill discovery.

Configuration:

• KATANA_PARITY_ROOT — override katana root path (default: auto-detect from adapter location)
• KATANA_DISABLED_PLUGINS — comma-separated list of plugins to disable (e.g., wiki,retrieval)

Parity verification:

./parity/e2e/run.sh parity/e2e/scenarios/basic.json both

This runs the same scenario on both Claude Code and OpenCode, comparing injection parity (via ccs payload forensics), FPA validation triggers, and skill exposure.

Katana ships a Codex marketplace at .agents/plugins/marketplace.json. Each plugins/<name> package has its own .codex-plugin/plugin.json, so the Codex install shape mirrors the Claude Code plugin shape.

codex plugin marketplace add Dandi007/katana

Then open Codex Plugins, choose the Katana marketplace, and install the individual plugins you want (guide, retrieval, wiki, work-folder, writing, etc.).

For local development, point Codex at a clone:

codex plugin marketplace add /data/code/self/katana
codex plugin add retrieval@katana
codex plugin add wiki@katana

Codex installs the bundled skills/ from each selected plugin. Claude Code SessionStart/PostToolUse hooks are not part of this Codex wrapper; use Codex repo instructions or a future Codex hooks adapter for equivalent lifecycle behavior.

Skills are regression-tested by contract: each skill declares an explicit contract (input prompt + mechanical artifact assertions), executed for real via claude -p in an isolated fixture KB with per-case snapshots. A judge layer backstops semantic expectations (NEEDS-REVIEW, never hard-fail). See tests/README.md.

Codex plugin metadata is checked with:

python3 scripts/validate_codex_plugins.py
python3 /path/to/plugin-creator/scripts/validate_plugin.py plugins/retrieval

Claude Code-specific features degrade gracefully elsewhere:

• guide / work-folder context injection and memory index injection use Claude Code SessionStart hooks. On Codex, paste the work-folder convention (plugins/work-folder/rules/work-folder.md) into your project's AGENTS.md.
• wiki zone-index injection uses a Claude Code SessionStart hook. On other tools, pass the index path via WIKI_INDEX env var or set wiki.index_path in your .katana file.
• deep-research orchestration uses Claude Code's Workflow tool; other tools can follow the SKILL.md flow manually.
• fpa mechanical acceptance uses a Claude Code PostToolUse hook and its adversarial verification uses the Workflow tool. On other tools, run python3 skills/fpa/scripts/validate_fpa.py <file> manually and dispatch skeptic subagents per the SKILL.md prompts.

Katana plugins support three-tier configuration (highest priority first):

1. Environment variables — machine-level overrides
2. .katana file — project-level configuration (committed to repo)
3. Default values — sensible defaults for most projects

Create a .katana file in your project root to customize plugin behavior:

# Katana plugin configuration
# Priority: environment variables > this file > plugin defaults

# work-folder: override the default work folder path
work_folder_path=智元工作/工作记录

# memory: override the project memory directory
memory_project_dir=memory

# deep-research: override the knowledge base root directory
deep_research_kb_dir=.

# deep-research: named platform sources (name:entry pairs) and fan-out width
deep_research_sources=feishu:.agents/skills/lark-cli/SKILL.md,gitlab:.agents/skills/gitlab/SKILL.md,github:gh
deep_research_max_width=10

The file uses simple key=value format. Lines starting with # are comments.

Note: System-level memory directory only supports environment variables (machine dimension, not project-specific).

Version control: Commit .katana to share project config with your team. Use environment variables for machine-specific overrides (paths, credentials) that shouldn't be in the repo.

For a Chinese knowledge base project:

# .katana
work_folder_path=智元工作/工作记录
memory_project_dir=memory
deep_research_kb_dir=.
deep_research_sources=feishu:.agents/skills/lark-cli/SKILL.md,gitlab:.agents/skills/gitlab/SKILL.md,github:gh
deep_research_max_width=10

This tells katana to use 智元工作/工作记录/YYYY/MM/DD/<topic>/ for work folders instead of the default docs/work-records/.... The deep_research_sources / deep_research_max_width entries declare named platform sources for deep-research workers and the per-round fan-out width.

On session start the memory hook (plugins/memory/hooks/session-start) scans the memory card frontmatter with a pure shell + awk scanner (plugins/memory/hooks/scan-memory.awk) and injects the <memory-index>. It is a text script — no compiled binary, no download, no build step — so it ships intact in the npm package and runs anywhere bash + awk exist. If no cards are found it emits nothing (never blocks the session). Output is locked to a golden by plugins/memory/tests/scan-memory.test.sh.

1. Bump version in the plugin's plugin.json and version in the root package.json.
2. Tag v<version> and push; npm-publish.yml publishes the package and creates the GitHub Release.

MIT