Ayanokoji — Strategic Execution Protocol

A universal strategic execution protocol for AI coding agents. It replaces reactive, error-prone behaviors with pre-calculated, structured planning and verification. Works across Claude Code, Cursor, Windsurf, GitHub Copilot, Cline, Kiro, OpenCode, Hermes, and any LLM agent.

Key Features

• Methodical Intake: The agent silently analyzes tasks and asks at most 9 targeted questions to define the end state, hard constraints, and acceptance criteria before writing any code.
• Persistent Memory Scaffold: Generates four root-level markdown files to maintain state across resets:
  • AGENTS.md — Rulebook (hard-capped at 60 lines) with constraints and operating principles.
  • CONTEXT.md — High-level architecture map and stack definition.
  • TASK.md — Bounded mission brief (files in scope, approach, risks, and criteria). Overwritten per task.
  • PROGRESS.md — Intelligence log of completions (with proof), failures (with exact errors), and blockers.
• Mandatory Verification Gate: Enforces execution of TASK.md's exact acceptance criteria. "Tests passed" is not allowed; concrete command outputs or detailed checks must be logged in PROGRESS.md.
• Fluff & Slop Control: Restricts LLM outputs to direct code, plan updates, and answers, forbidding greetings (hi, hello) or verbose explanations of what the code does.

Workflow

Commands

All commands are available as slash commands, @mentions, or natural language directives.

| Command | Action | |---|---| | /ayanokoji | Activate the strategic execution protocol for this project. | | /ayanokoji-task [desc] | Overwrite and initialize TASK.md with the new task description. | | /ayanokoji-gate | Verify the current task's acceptance criteria and update scaffold logs. | | /ayanokoji-status | Display the current task summary, blockers, failures, and scaffold health. | | /ayanokoji-review | Inspect the active TASK.md for completeness and risks before starting. | | /ayanokoji-audit | Audit all four scaffold files for protocol compliance and syntax errors. | | /ayanokoji-debt | List all deferred decisions, [TO BE DEFINED] blocks, and blockers. | | /ayanokoji-gain | Summarize project stats: completed tasks, retry rate, and verification quality. | | /ayanokoji-help | Display the protocol quick-reference guide. |

Deactivate by saying "stop ayanokoji" or "normal mode".

Setup Guide

Instant Setup (Recommended)

Run in your project directory. Ayanokoji auto-detects your IDE from directory markers and writes only the relevant rule files:

npx ayanokoji.md

Auto-detection rules: .claude/ or CLAUDE.md → Claude Code · .cursor/ → Cursor · .windsurf/ → Windsurf · .clinerules/ → Cline · .kiro/ → Kiro · .github/ → GitHub Copilot. If none are found, all rulesets are written.

Target a Specific Agent

Pass a flag to skip auto-detection and configure exactly one agent:

# npx (one-shot, nothing installed in node_modules)
npx ayanokoji.md --claude       # Claude Code  → CLAUDE.md
npx ayanokoji.md --cursor       # Cursor       → .cursor/rules/ayanokoji.mdc
npx ayanokoji.md --windsurf     # Windsurf     → .windsurf/rules/ayanokoji.md
npx ayanokoji.md --cline        # Cline        → .clinerules/ayanokoji.md
npx ayanokoji.md --kiro         # Kiro         → .kiro/steering/ayanokoji.md
npx ayanokoji.md --copilot      # GitHub Copilot → .github/copilot-instructions.md
npx ayanokoji.md --all          # Every agent at once

You can also stack flags to configure multiple agents in one run:

npx ayanokoji.md --claude --cursor

Using npm install with a flag

When installing via npm install, pass the same flag — npm forwards it to the postinstall script automatically:

npm install ayanokoji.md --claude
npm install ayanokoji.md --cursor
npm install ayanokoji.md --all

After setup completes, the package removes itself from your package.json automatically — it is a one-shot tool, not a runtime dependency. The node_modules/ayanokoji.md folder will be gone on the next npm install.

Environment variable fallback

If flags are inconvenient (CI pipelines, scripts), use AYANOKOJI_FOR:

AYANOKOJI_FOR=claude npx ayanokoji.md
AYANOKOJI_FOR="claude,cursor" npx ayanokoji.md

Setup Output

Every run prints a summary of what was configured:

♟️  Ayanokoji — Strategic Execution Protocol Setup

✅ Configured Master Rulebook (AGENTS.md): AGENTS.md
✅ Configured Claude Code (CLAUDE.md): CLAUDE.md
✅ Installed skill: .openclaw/skills/ayanokoji/SKILL.md
...

♟️  Setup complete.
   Configured for: Claude Code
   Instruct your agent to read AGENTS.md before writing any code.

Manual IDE Setup Guide

1. Cursor

Copy the cursor rule to your project:

mkdir -p .cursor/rules
cp .cursor/rules/ayanokoji.mdc .cursor/rules/ayanokoji.mdc

The rule will automatically steer all composer and chat sessions.

2. Windsurf

Copy the windsurf rule to your project:

mkdir -p .windsurf/rules
cp .windsurf/rules/ayanokoji.md .windsurf/rules/ayanokoji.md

3. Claude Code / Gemini CLI / Antigravity CLI

Install as a plugin:

claude mcp add ayanokoji https://github.com/Sahnik0/ayanokoji.md

Or use the native commands configured in commands/ and gemini-extension.json.

4. GitHub Copilot

• Instruction-tier: Copy .github/copilot-instructions.md to your repository.
• Plugin-tier: Add it through the Copilot Plugin Marketplace.

5. Cline

Copy the rules file to your project:

cp .clinerules/ayanokoji.md .clinerules

6. Kiro

Copy the steering rule:

mkdir -p .kiro/steering
cp .kiro/steering/ayanokoji.md .kiro/steering/ayanokoji.md

7. OpenCode

Add the plugin dependency to your opencode.json:

{
  "plugins": ["ayanokoji.md"]
}

8. Hermes Agent

Install and enable the plugin:

hermes plugins install ayanokoji
hermes plugins enable ayanokoji

Project Structure

ayanokoji.md/
  ├── AGENTS.md                          — Canonical ruleset (copied by agents)
  ├── skills/                            — Full protocol markdown files
  │   ├── ayanokoji/SKILL.md             — Base strategic protocol
  │   └── ayanokoji-[sub]/SKILL.md       — Sub-skill rules (review, status, etc.)
  ├── commands/                          — Slash command descriptors (.toml)
  ├── hooks/                             — Adapter hooks & scripts for shells/CLIs
  ├── pi-extension/                      — Personal AI (pi) extension files
  ├── scripts/                           — Development lint, build, & sync scripts
  ├── tests/                             — Complete functional unit test suite
  ├── benchmarks/                        — Correctness and LOC graders
  ├── __init__.py                        — Hermes plugin runtime entry
  └── plugin.yaml                        — Hermes plugin manifest

"Emotions are inefficiencies. I calculate, therefore I execute."