{
  "markdown": "# Kkachi\n\nPortable Top-1 greedy loop engine for coding agents.\n\nKkachi keeps selection logic in one Python core and provides thin integrations for:\n\n- Gemini CLI extension\n- OpenCode project/global runtime\n- Generic shell loop for Codex, Claude Code, or any agent runner\n\nLanguage docs:\n\n- [Korean](README.ko.md)\n- [Japanese](README.ja.md)\n- [Chinese (Simplified)](README.zh-cn.md)\n\n## Agent Compatibility and Install Matrix\n\n| Agent | Support Level | Install | Notes |\n| --- | --- | --- | --- |\n| Gemini CLI | Native extension | `bash scripts/install_gemini.sh` | Slash commands + `AfterAgent` hook |\n| OpenCode | Native integration | `bash scripts/install_opencode.sh` | Project/global install supported |\n| Codex | Supported via loop + skill | `bash scripts/install_skills.sh --target codex` | Uses local scripts/prompts and optional Codex skill |\n| Claude Code | Supported via loop + skill | `bash scripts/install_skills.sh --target claude` | Uses local scripts/prompts and optional Claude skill |\n| Any shell-capable coding agent | Portable loop | No special installer required | Run `scripts/setup.sh -> next.sh -> mark.sh` |\n\n## Skills Support\n\nYes. This repo now includes a reusable skill package:\n\n- `skills/kkachi/SKILL.md`\n\nInstall skill pack:\n\n```bash\n# install for both Codex + Claude\nbash scripts/install_skills.sh --target all\n\n# only Codex\nbash scripts/install_skills.sh --target codex\n\n# only Claude Code\nbash scripts/install_skills.sh --target claude\n```\n\nUninstall skill pack:\n\n```bash\nbash scripts/uninstall_skills.sh --target all\n```\n\nManual install (without script):\n\n- Copy `skills/kkachi/` to `~/.codex/skills/kkachi`\n- Copy `skills/kkachi/` to `~/.claude/skills/kkachi`\n\n## One-line Value\n\nShip more by forcing one validated next step at a time.\n\n## Why Teams Adopt Kkachi\n\n- Deterministic and explainable task choice (`rank`, `select`, `explain`)\n- Safe execution contract (exactly one task per iteration)\n- Cross-agent portability (Gemini + OpenCode + generic shell)\n- File-based state you can inspect and version (`.kkachi/`, `.gemini/kkachi/`)\n- Built-in operational modes for different delivery phases\n\n## Best-fit Use Cases\n\n| Use case | Recommended mode | Why it works |\n| --- | --- | --- |\n| Startup feature shipping | `kkachi-ship-fast` | Pushes visible progress and quick wins |\n| CI instability / regression days | `kkachi-stabilize` or `kkachi-incident` | Stronger fail-first and risk controls |\n| Dependency bottlenecks | `kkachi-unblock` | Prioritizes tasks that unlock more work |\n| Unknown requirements / investigation | `kkachi-discover` | Increases information gain with exploration |\n| Refactor / debt cleanup sprint | `kkachi-debt-burn` | Balances debt reduction with change safety |\n\n## Why Kkachi\n\nKkachi enforces one simple contract per iteration:\n\n1. Rank pending tasks.\n2. Pick exactly one Top-1 task.\n3. Execute and verify.\n4. Mark success/fail.\n\nThis prevents multi-task drift and makes progress measurable in files (`tasks.json`, loop state JSON).\n\n## Core Scoring Policy\n\nDefault score formula:\n\n```text\nscore =\n  + 5 * fail_first\n  + 4 * priority\n  + 3 * kkachi-unblock\n  + 2 * quick_win\n  + 2 * impact\n  + 1 * info_gain\n  - 3 * risk\n  - 2 * effort\n  - 4 * failures\n```\n\nDefinitions:\n\n- `fail_first`: `1` only when `--tests-failing` is on and task `kind == \"fix\"`.\n- `quick_win`: `1` when `effort <= 2` and `risk <= 2`.\n- `failures`: prior failed attempts for that task.\n\nTie-break order:\n\n1. Lower `effort`\n2. Lower `risk`\n3. Higher `priority`\n4. Lexicographic `id`\n\nExploration:\n\n- Epsilon-greedy is supported (`--epsilon`).\n- During exploration, selection is random from ranks 2..3 (when available).\n\n## Built-in Modes\n\nModes live under `modes/*.json`.\n\n```bash\npython3 kkachi_greedy.py modes\npython3 kkachi_greedy.py modes --json\n```\n\n| Mode | Goal | Default epsilon |\n| --- | --- | --- |\n| `kkachi-ship-fast` | Maximize visible delivery speed / quick wins | `0.05` |\n| `kkachi-stabilize` | Reliability first, reduce breakage and risk | `0.0` |\n| `kkachi-unblock` | Resolve dependency bottlenecks | `0.05` |\n| `kkachi-discover` | Maximize information gain under uncertainty | `0.2` |\n| `kkachi-debt-burn` | Reduce technical debt with risk control | `0.02` |\n| `kkachi-incident` | Incident / outage / CI emergency mode | `0.0` |\n\n### Mode Deep Dive\n\n| Mode | Primary objective | Dominant positive terms | Strong penalties | When to use | Avoid when |\n| --- | --- | --- | --- | --- | --- |\n| `kkachi-ship-fast` | Maximize visible output per turn | `priority=4`, `quick_win=4`, `impact=4` | `effort=3`, `risk=2` | Early feature sprint, demo week, MVP push | Critical outage where reliability must dominate |\n| `kkachi-stabilize` | Reduce breakage and repeated failures | `fail_bonus=8`, `kkachi-unblock=3` | `risk=6`, `failure_penalty=6` | Flaky CI, regression cleanup, release hardening | You need exploratory discovery speed |\n| `kkachi-unblock` | Unlock downstream work quickly | `kkachi-unblock=8` | Moderate `risk=2`, `effort=2` | Dependency bottlenecks, blocked team queues | Independent tasks with no dependency graph |\n| `kkachi-discover` | Buy information under uncertainty | `info_gain=7`, `impact=2` | Low `effort=1`, `risk=2` | Root-cause analysis, unknown requirements, research spikes | Strict deterministic delivery windows |\n| `kkachi-debt-burn` | Burn debt with controlled blast radius | `quick_win=3`, `priority=3` | `effort=4`, `risk=4`, `failure_penalty=4` | Refactor weeks, quality initiatives, cleanup periods | Aggressive feature expansion targets |\n| `kkachi-incident` | Fast kkachi-incident containment and service restore | `fail_bonus=10`, `priority=5`, `kkachi-unblock=4` | `risk=5`, `failure_penalty=6` | Production outage, broken CI/CD, emergency fixes | Normal roadmap work where exploration is valuable |\n\nPractical notes:\n\n- `kkachi-incident` is most effective with `--tests-failing`, because fix tasks get the largest fail-first bonus.\n- `kkachi-discover` intentionally uses the highest default exploration (`epsilon=0.2`).\n- `kkachi-stabilize` and `kkachi-incident` set `epsilon=0.0` to keep behavior deterministic during high-risk periods.\n- `kkachi-debt-burn` strongly discourages long/high-risk tasks unless payoff is clear.\n\nMode-specific ranking examples:\n\n```bash\npython3 kkachi_greedy.py rank .kkachi/tasks.json --weights-file .kkachi/config.json --mode kkachi --json\npython3 kkachi_greedy.py rank .kkachi/tasks.json --weights-file .kkachi/config.json --mode kkachi-stabilize --json\npython3 kkachi_greedy.py rank .kkachi/tasks.json --weights-file .kkachi/config.json --mode kkachi-unblock --json\npython3 kkachi_greedy.py rank .kkachi/tasks.json --weights-file .kkachi/config.json --mode kkachi-discover --json\npython3 kkachi_greedy.py rank .kkachi/tasks.json --weights-file .kkachi/config.json --mode kkachi-debt-burn --json\npython3 kkachi_greedy.py rank .kkachi/tasks.json --weights-file .kkachi/config.json --mode kkachi-incident --tests-failing --json\n```\n\nMode resolution order:\n\n1. `--mode-file` (explicit custom mode JSON)\n2. `--mode` + `--mode-dir`\n3. No mode (base defaults)\n\nWeight merge order:\n\n1. Base `Weights` defaults\n2. Mode `weights` override\n3. `--weights-file` (or config file) override\n\n## Requirements\n\n- `python3` (tested in CI with 3.11)\n- `jq`\n- `bash`\n\nOptional (integration-specific):\n\n- `gemini` CLI for Gemini extension install\n- OpenCode runtime for `/kkachi-*` commands\n\n## Quick Start (Local Loop)\n\nInitialize:\n\n```bash\nbash scripts/init.sh\nbash scripts/doctor.sh .kkachi/tasks.json .kkachi/config.json\n```\n\nInspect ranking:\n\n```bash\npython3 kkachi_greedy.py rank .kkachi/tasks.json \\\n  --weights-file .kkachi/config.json \\\n  --mode kkachi \\\n  --json\n```\n\nRun one iteration:\n\n```bash\nbash scripts/setup.sh \"Implement feature X with tests\"\nbash scripts/status.sh\nTASK_ID=$(bash scripts/next.sh)\nbash scripts/render_step_prompt.sh\n# Work and verify...\nbash scripts/mark.sh \"$TASK_ID\" success\n```\n\nCheck completion:\n\n```bash\npython3 kkachi_greedy.py pending .kkachi/tasks.json\n```\n\n## Cross-Agent Usage (Codex / Claude Code / OpenCode)\n\nShared loop files:\n\n- `.kkachi/tasks.json`\n- `.kkachi/config.json`\n- `.gemini/kkachi/state.json` (active loop state)\n\nCommon flow:\n\n1. `bash scripts/setup.sh \"<goal prompt>\" ...`\n2. `bash scripts/status.sh`\n3. `TASK_ID=$(bash scripts/next.sh)`\n4. Execute only `TASK_ID`\n5. Verify\n6. `bash scripts/mark.sh \"$TASK_ID\" success|fail`\n7. Repeat\n\nReference: `docs/CROSS_CLI.md`.\n\n## Task JSON Schema\n\nTask file must be a JSON array.\n\nEach task object supports:\n\n| Field | Type | Default | Notes |\n| --- | --- | --- | --- |\n| `id` | string | required | Must be unique |\n| `title` | string | `id` | Display text |\n| `priority` | int | `1` | `>= 0` |\n| `impact` | int | `1` | `>= 0` |\n| `effort` | int | `1` | `>= 0` |\n| `risk` | int | `1` | `>= 0` |\n| `kkachi-unblock` | int | `0` | `>= 0` |\n| `info_gain` | int | `0` | `>= 0` |\n| `kind` | string | `feature` | Use `fix` for fail-first bonus |\n| `status` | string | `pending` | One of `pending`, `done`, `blocked` |\n| `failures` | int | `0` | `>= 0` |\n\nValidation (`doctor`) checks:\n\n- Duplicate task IDs\n- Invalid statuses\n- Negative numeric values\n- Invalid runtime/mode/weights payloads\n\n## Config and Weights\n\nExample config: `examples/config.json`:\n\n- Loop settings:\n  - `tests_failing`\n  - `seed`\n  - `block_after`\n  - `max_iterations`\n  - `completion_promise`\n  - `mode`\n- Weight overrides:\n  - Either top-level weight keys or nested `weights` object\n\n`scripts/setup.sh` behavior:\n\n- Creates missing task/config files from `examples/`.\n- Reads config values.\n- CLI flags override config values.\n- Persists state to `.gemini/kkachi/state.json`.\n\n## CLI Reference (`kkachi_greedy.py`)\n\n### `rank`\n\nRank pending tasks, show Top-1 selection.\n\n```bash\npython3 kkachi_greedy.py rank <tasks.json> [options]\n```\n\nOptions:\n\n- `--tests-failing`\n- `--epsilon <0..1>`\n- `--seed <int>`\n- `--weights-file <path>`\n- `--mode <name>`\n- `--mode-file <path>`\n- `--mode-dir <path>`\n- `--json`\n\n### `select`\n\nPrint selected task ID (or JSON payload).\n\n```bash\npython3 kkachi_greedy.py select <tasks.json> [options]\n```\n\nBehavior:\n\n- Exit code `1` when no pending tasks.\n\n### `pending`\n\nPrint count of `pending` tasks.\n\n```bash\npython3 kkachi_greedy.py pending <tasks.json>\n```\n\n### `apply`\n\nApply one execution result.\n\n```bash\npython3 kkachi_greedy.py apply <tasks.json> <task_id> \\\n  --result success|fail \\\n  [--block-after 3]\n```\n\nBehavior:\n\n- `success`: status -> `done`\n- `fail`: increments `failures`; status -> `blocked` when `failures >= block_after`\n\n### `loop`\n\nSimulated greedy loop (for testing policy behavior).\n\n```bash\npython3 kkachi_greedy.py loop <tasks.json> [options]\n```\n\nLoop-specific options:\n\n- `--max-steps <int>` (default `20`)\n- `--auto-success-rate <0..1>` (default `1.0`)\n- `--write` to persist updates\n\n### `explain`\n\nExplain score breakdown for one task.\n\n```bash\npython3 kkachi_greedy.py explain <tasks.json> <task_id> [options]\n```\n\nOutput includes:\n\n- task payload\n- effective weights\n- selected mode\n- per-term scoring breakdown\n\n### `doctor`\n\nValidate tasks and runtime inputs.\n\n```bash\npython3 kkachi_greedy.py doctor <tasks.json> [options]\npython3 kkachi_greedy.py doctor <tasks.json> --json\n```\n\nBehavior:\n\n- Exit code `0` when valid\n- Exit code `2` on validation/runtime issues\n\n### `modes`\n\nList available modes.\n\n```bash\npython3 kkachi_greedy.py modes [--mode-dir <path>] [--json]\n```\n\n## Runtime Script Reference (`scripts/`)\n\n| Script | Purpose |\n| --- | --- |\n| `init.sh` | Create task/config files from `examples/` and run `doctor` |\n| `setup.sh` | Initialize active loop state from prompt + config + flags |\n| `status.sh` | Print iteration/status summary and current Top-1 |\n| `next.sh` | Select next Top-1 task (`select`) |\n| `render_step_prompt.sh` | Print one-step contract prompt for agent handoff |\n| `mark.sh` | Apply `success|fail` to a selected task |\n| `doctor.sh` | Wrapper around Python `doctor` + dependency checks |\n| `cancel.sh` | Stop loop and remove `.gemini/kkachi/state.json` |\n| `install_gemini.sh` | Install extension and optionally patch `~/.gemini/settings.json` |\n| `uninstall_gemini.sh` | Uninstall extension and clean settings include path |\n| `install_opencode.sh` | Install OpenCode runtime/commands/rules (project or global) |\n| `uninstall_opencode.sh` | Remove OpenCode runtime/commands/rules and config reference |\n| `install_skills.sh` | Install `skills/kkachi` into Codex/Claude skill directories |\n| `uninstall_skills.sh` | Remove installed Codex/Claude skill directories |\n\n## Gemini CLI Extension\n\nExtension metadata:\n\n- `gemini-extension.json`\n- `commands/kkachi/*.toml`\n- `hooks/hooks.json`\n- `hooks/stop-hook.sh`\n\nInstall:\n\n```bash\nbash scripts/install_gemini.sh\n```\n\nManual:\n\n```bash\ngemini extensions install <repo-url> --auto-update\n```\n\nCommands:\n\n- `/kkachi:init`\n- `/kkachi:loop \"<goal prompt>\" [options]`\n- `/kkachi:status`\n- `/kkachi:modes`\n- `/kkachi:cancel`\n- `/kkachi:help`\n\n`/kkachi:loop` options:\n\n- `--tasks-file <path>`\n- `--config-file <path>`\n- `--weights-file <path>`\n- `--mode <name>`\n- `--mode-file <path>`\n- `--mode-dir <path>`\n- `--max-iterations <n>`\n- `--completion-promise <text>`\n- `--tests-failing`\n- `--epsilon <0..1>`\n- `--seed <int>`\n- `--block-after <n>`\n\nHook behavior (`AfterAgent`):\n\n- Continues loop while pending tasks exist and max iterations not reached.\n- Stops when:\n  - no pending tasks\n  - completion promise appears (`<promise>...</promise>`)\n  - prompt mismatch\n  - max iterations reached\n- On continue, denies current continuation and requests fresh context (`clearContext: true`).\n\nUninstall:\n\n```bash\nbash scripts/uninstall_gemini.sh\n```\n\n## OpenCode Integration\n\nInstaller generates runtime from templates in `integrations/opencode/template/`.\n\nProject install:\n\n```bash\nbash scripts/install_opencode.sh\n```\n\nGlobal install:\n\n```bash\nbash scripts/install_opencode.sh --global\n```\n\nInstalled artifacts:\n\n- `.opencode/kkachi/kkachi_greedy.py`\n- `.opencode/kkachi/scripts/*.sh`\n- `.opencode/kkachi/examples/*.json`\n- `.opencode/kkachi/modes/*.json`\n- `.opencode/commands/kkachi-{init,loop,status,modes,cancel}.md`\n- `.opencode/plugins/kkachi-idle.ts`\n- `.opencode/rules/kkachi.md`\n- `opencode.json` merged with `instructions` entry\n\nOpenCode commands:\n\n- `/kkachi-init`\n- `/kkachi-loop`\n- `/kkachi-status`\n- `/kkachi-modes`\n- `/kkachi-cancel`\n\nUninstall:\n\n```bash\nbash scripts/uninstall_opencode.sh\nbash scripts/uninstall_opencode.sh --global\n```\n\n## Agent Prompt Contracts\n\nReusable iteration contracts:\n\n- `prompts/codex.md`\n- `prompts/claude_code.md`\n- `prompts/opencode.md`\n\nAgent instruction snippets:\n\n- `agents/codex/AGENTS.md`\n- `agents/claude_code/CLAUDE.md`\n- `agents/opencode/AGENTS.md`\n\nAll enforce:\n\n- one selected task per iteration\n- verification before marking\n- exactly one mark operation ends the iteration\n\n## Repository Layout\n\n```text\n.\n├─ kkachi_greedy.py                 # core policy engine + CLI\n├─ modes/                           # mode presets\n├─ examples/                        # sample tasks/config\n├─ scripts/                         # runtime/install wrappers\n├─ commands/kkachi/                 # Gemini slash command templates\n├─ hooks/                           # Gemini loop control hook\n├─ integrations/opencode/template/  # OpenCode template assets\n├─ agents/                          # agent-specific instruction snippets\n├─ prompts/                         # copy/paste loop prompts\n├─ docs/                            # installation and cross-cli docs\n├─ tests/test_kkachi_greedy.py      # unit tests\n└─ .github/workflows/ci.yml         # CI pipeline\n```\n\n## Development and CI\n\nLocal checks:\n\n```bash\npython3 -m unittest kkachi-discover -s tests -p \"test_*.py\"\nbash -n hooks/stop-hook.sh scripts/*.sh\npython3 kkachi_greedy.py doctor examples/tasks.json --weights-file examples/config.json\npython3 kkachi_greedy.py modes\npython3 kkachi_greedy.py explain examples/tasks.json CI-01 --weights-file examples/config.json\n```\n\nCI (`.github/workflows/ci.yml`) runs:\n\n- unit tests\n- shell parse checks\n- sample data validation (`doctor`, `modes`, `explain`)\n\n## Troubleshooting\n\n- `Unknown mode '<name>'`: run `python3 kkachi_greedy.py modes`.\n- `invalid status` / duplicate IDs: run `python3 kkachi_greedy.py doctor <tasks.json> --json`.\n- `jq is required`: install `jq` for shell wrappers.\n- Loop not advancing in Gemini: check `.gemini/kkachi/state.json`, completion promise, and max iterations.\n\n## Additional Docs\n\n- Installation variants: `docs/INSTALL.md`\n- Cross-agent workflow: `docs/CROSS_CLI.md`\n- Contribution rules: `CONTRIBUTING.md`\n- 10k star growth playbook: `docs/GROWTH_10K_STARS.md`\n- Technical report draft (arXiv): `paper/main.tex`\n",
  "bytes": 16707,
  "sha": "6d0c25af31609784dd7b38a5a08db19fac83a341c921915847295e05130c0d10",
  "repo_slug": "jaichangpark/kkachi",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_jaichangpark_kkachi_3c27850f/readme"
}