icode-skill

ICode — End-to-End Coding Workflow for AI Coding Hosts

6-step workflow: Plan → Review → Finalize → Code → Deep Check → Audit. Run all at once, or step-by-step and switch models between steps.

ICode is a Claude Code Skill that breaks the journey from requirement to delivery into strict, individually invokable steps. It adds a quality gate, adversarial review, cross-project memory, and crash recovery on top of vanilla Claude Code — without locking you into a single model or a single pass.

Why ICode?

Quick Start

# 1) Clone the open-source installer
git clone https://github.com/ayukyo/icode-skill ~/icode-skill
cd ~/icode-skill

# 2) Install ICODE, shared skills, and MCPs for Claude Code + Codex
./install.sh --client all

# 3) Run a full flow
/icode start Implement a feature module

Or run step by step (switch models between steps anytime):

/icode plan Implement a feature module   # Step 1: Draft plan
/icode review                                       # Step 2: Review plan (soft cap 3 rounds; auto-extends if issues remain)
/icode merge                                        # Step 3: Merge & finalize
/icode code                                         # Step 4: Code implementation
/icode deepcheck                                    # Step 5: Iterative re-review
/icode audit                                        # Step 6: Final audit & fix

Other entry points:

# Local global ticket manager (defaults to 127.0.0.1:8765; auto-falls back if occupied)
/icode ui

# Trimmed full flow (fast mode: single-file/small changes; ~65% of full-flow cost)
/icode fast "Add isqrt function to calc.c"          # plan→review(1 round, no adversarial)→merge→code→deepcheck(Reverse only)→audit

# Requirement unclear? Draft it in conversation first
/icode init Record sensor data re-bag                # Step 0: kick-off draft + dialogue
# After the init analysis and discussion, turn the latest eligible draft into a beginner-facing guide
/icode init --guide                                  # Refreshes deliverables/guide.md; does not create another ticket

# From a bug log: analyze root cause first, then fix
/icode log ~/work/log/service-anomaly "no response after startup"   # Entry: log root-cause analysis → fix requirement

# Project-level knowledge base (standalone step, runs anytime)
/icode doc myproject                                 # Generate/update this project's knowledge base chapters

# DOCX delivery (standalone; preserves `/icode doc` knowledge-base semantics)
/icode docx docs/release-guide.md                    # P0: faithful DOCX beside the Markdown source
/icode docx current bug delivery Word                # P1: latest unique ICODE ticket → .icode_output/docx/

# Backup all work orders before deleting a project (safety net — run BEFORE deleting)
/icode bak                                           # Snapshot current project's entire .icode_output/ to ~/.claude/icode_data/project_backup/
/icode bak --project ~/work/myproj                   # Backup a specified project
# Repeatable: each run creates a new timestamp snapshot (rsync --link-dest hardlink dedup).
# After the project is deleted, history retrieval still finds full work orders from the backup (project-first, backup fallback).

# Opt-in worktree isolation (any of the entry points above)
/icode start --worktree Implement a feature module   # Full flow + isolated branch/dir
/icode fast --worktree  "Add isqrt function to calc.c"         # Fast mode + isolated branch/dir
/icode plan --worktree  Implement a feature module    # Step 1 only + isolated branch/dir
/icode init --worktree  Record sensor data re-bag              # Step 0 + isolated branch/dir
/icode log --worktree   ~/work/log/service-anomaly "no response"  # Log + isolated branch/dir
# Without --worktree, tickets are created in-place by default — no prompt.
# Triggers also accept natural language ("use worktree isolation"), with reverse declarations taking precedence; AI shows a status line on entry. Projects can block via `/icode limit worktree 强制禁止`.
# New worktrees are created on the current remote-tracking baseline (@{u}) with upstream tracking, so git status/pull/merge stay correct.
# Worktree lifecycle (after creation):
/icode worktree --update    # Move the active implementation to a new checkout on the latest remote baseline (tracked upstream)
/icode worktree --close     # After you committed/pushed/merged: verify online evidence + safe cleanup + record baseline
/icode worktree --reopen    # Restore a closed ticket's active checkout on the latest baseline (then /icode patch)
/icode worktree --merge         # Fetch online targets, preflight conflicts, merge safely, then recheck; never commits or pushes

The Workflow

  /icode log (optional)        /icode init (optional)
  log root-cause analysis ─┐    requirement draft ─┐
                           └──────────┬────────────┘
                                      ▼
  ┌────────┐   ┌────────┐   ┌────────┐   ┌────────┐   ┌────────┐   ┌────────┐
  │ Plan   │ → │ Review │ → │ Merge  │ → │ Code   │ → │ Deep   │ → │ Audit  │
  │ Step 1 │   │ Step 2 │   │ Step 3 │   │ Step 4 │   │ Check  │   │ Step 6 │
  └────────┘   └────────┘   └────────┘   └────────┘   │ Step 5 │   └────────┘
                                                       └────────┘
       /icode start = steps 1→6 chained  |  /icode fast = trimmed chain (~65% cost)

Every main ticket step produces a real artifact in .icode_output/.icode_output_N/ (plan → review → final plan → code → deep-check report → audit report), tracked by .ico_metadata.json for cross-session recovery and resumable runs. Detached deliverables and crosscheck rounds use their documented sibling directories and do not pretend to be tickets.

Features

• Closed-loop delivery: (optional) Requirement Draft → Plan → Review → Finalize → Code → Deep Check → Audit; each step callable independently, runs in the main session without model switching
• Dual modes: /icode start full flow (multi-round review + adversarial verification) / /icode fast trimmed (1 round, no adversarial, ~65% cost)
• Anti-laziness quality gates: triple-phase deepcheck (Reverse/Fixed/Free), plan assertion verification, ADR decision records, adversarial verification (independent skeptics — insufficient evidence is never confirmed, honest downgrade over fake consensus)
• Cross-project history retrieval: init/log/plan/start auto-search similar past tickets and inject by command; references stay in-session, never pollute project artifacts. Verdict-based injection prevents disproved/superseded tickets from misleading new work
• Project-level knowledge base (/icode doc): global per-project/per-branch knowledge base (module docs generated once and reused across projects), auto-retrieved and injected by phase-zero search
• DOCX delivery (/icode docx): separate P0 Markdown conversion and P1 project/module/current-ticket delivery report. The installer creates a pinned, user-private DOCX runtime; every output includes hashes, source map, structural QA and an explicit visual-QA state. Visual rendering uses only an ICODE-owned OS/CPU/glibc-compatible bundle, never host LibreOffice.
• Project work-order backup (/icode bak): snapshot the project's entire .icode_output/ (tickets + debug twins + isolated crosscheck rounds + limit.local + ppt) to global ~/.claude/icode_data/project_backup/, repeatable with hardlink dedup. Run it before deleting a project — once deleted, history retrieval still reads full work orders from the backup (project-first, backup fallback), and /icode list marks them [path_gone→backup]. For closed worktree tickets whose project_path is gone but whose archive_path is valid, /icode list marks them [path_gone→archive] (or [path_gone→archive+backup] when both archive and backup exist)
• Anti-duplicate injection: history retrieval and project-doc retrieval share an injection cache, avoiding repeated injection within one dev chain
• Decision anchors: steps pass concise decision summaries (.decision_anchors.json) downstream — saves tokens, keeps reasoning continuity
• Resumable runs: .ico_metadata.json status + round counters support crash recovery at steps 2/4/5
• Two optional entries: /icode log log root-cause analysis (baseline check first, then adversarial analysis; domain-agnostic) → fix requirement, plus a cross-audience brief at completion — log_problem_brief.md, with a <ticket> prefix (DEMO-26_log_problem_brief.md) when the source is a TB ticket (no icode terminology); /icode init multi-turn requirement draft → 00_init.md
• Project constraint red lines (/icode limit): define this project's forbidden zones / constraints; the plan step treats them as a hard baseline (plan → implementation → audit convergence)

Installation

One public installer

Clone the source into a neutral directory, then use the root installer. It installs ICODE, every shared skill declared by skill-packs/manifest.json, host command adapters, and the MCP servers. The installer keeps default: claude (--client claude); use --client all for Claude Code and Codex together. Use --client codebuddy for CodeBuddy. With all, CodeBuddy is added only when ~/.codebuddy/ is detected, preserving the historical two-host behavior.

git clone https://github.com/ayukyo/icode-skill ~/icode-skill
cd ~/icode-skill
./install.sh --client all