idea-to-deploy

Harness Engineering methodology for reliable agentic software delivery, with a model-neutral contract, state, and verification core.

One canonical core is currently packaged and validated for Claude Code and OpenAI Codex through host adapters. Other agent hosts are an architectural extension point, not a supported claim. Choose a host · Architecture · End-to-End Example · Skill Contracts.

Русская версия (README.ru.md) · Changelog · Contributing · CI

Idea to Deploy is the product name; Harness Engineering is the methodology category. The repository contains one shared methodology core plus separate Claude Code and Codex packages. It does not run as a standalone CLI.

Demo

See the End-to-End Example below for a detailed walkthrough. The recording predates the Codex adapter and shows the Claude Code transport; the lifecycle and verification contracts are shared.

---

The Problem

AI coding agents are powerful, but without a harness they work like builders without blueprints:

• Writes code randomly, skips tests, doesn't document
• Each time produces different structure and quality
• Can break what already works
• No methodology — just chaotic generation

The Solution

idea-to-deploy is a methodology, not just a set of tools. Its 41 skills + 10 specialized agents, 31 hooks, project contracts, and persistent state give a supported coding host an evidence-gated delivery pipeline:

Idea → Questions → Plan → Architecture → Code → Tests → Review → Deploy

Every step is verified. Every feature is tested. Every decision is documented. Every session is preserved.

Architecture and portability

                     Idea to Deploy
        canonical Harness Engineering methodology core
    skills · .itd contracts · .itd-memory · hooks · tests
                           |
                host adapter contract
                  /                     \
       Claude Code adapter          Codex adapter
       CLAUDE.md / hooks       AGENTS.md / dispatcher

Host adapters translate packaging, guidance files, tool names, hook events, and subagent transport. They may not fork completion criteria, risk policy, persistent project state, or skill semantics. See the host adapter contract.

Acceptance is proof-carrying by default: low-risk work uses harness-executed machine evidence, medium adds a targeted fresh-session checker, and high/unknown adds a full checker from a fresh session and different model or provider. /goal and review caches accept only an exact-candidate adjudication receipt; see Verification Loop v1.

Opt-in operating loops add binary readiness diagnostics, routing to existing skills, report-only host-native schedules, temporary capability-bound trust, observed append-only telemetry, deterministic failure handling, and provenance-backed outcome stories. They do not add a daemon or unattended permanent authority. The closed recipe registry contains exactly six report-first loops: state freshness, test regression, dependency health, security posture, review drift, and documentation drift.

Host	Status	Guidance entry	Evidence boundary
Claude Code	Supported	CLAUDE.md	Native plugin, skills, agents, and hooks
OpenAI Codex	Supported	AGENTS.md	Native package plus tested hook/tool normalization
Other agent hosts	Not validated	Adapter-defined	Requires an adapter, declared degradations, and parity evidence

What “model-neutral” means here: the load-bearing contracts, state, gates, and evidence rules do not depend on the identity of a particular model. It does not mean that every model or agent host works out of the box, that all hosts expose identical capabilities, or that current model recommendations are provider-equivalent.

Quick Start

Claude Code

Requirements: Claude Code CLI ≥ 2.0 (or its VS Code / JetBrains extension) with plugin support, an eligible Claude subscription, and git on PATH.

Install the Claude Code adapter:

/plugin install hihol-labs/idea-to-deploy

The skills and agents are then registered under:

~/.claude/plugins/idea-to-deploy/
  ├── skills/          # 41 skill directories
  ├── agents/          # 10 subagent definitions
  └── hooks/           # enforcement hooks - /adopt and /project offer to install them

Sanity check inside Claude Code:

/project

If the router prompt appears and offers routes A / B / C, the plugin is live.

Update:

/plugin update hihol-labs/idea-to-deploy

Uninstall:

/plugin uninstall hihol-labs/idea-to-deploy

OpenAI Codex

Enable this repository through the normal Codex plugin UI and review its bundled command hooks with /hooks before trusting them. The Codex adapter uses .codex-plugin/plugin.json, AGENTS.md, and automatic hooks/hooks.json discovery.

For a repository-local checkout instead of an installed package, follow the Codex adapter setup. It documents the local .codex/hooks.json fallback and the known transport differences.

On both hosts, git is required by lifecycle, review, and continuity workflows. See the CHANGELOG for release notes.

Updating - one installation for every project

The methodology lives in the installation, not in a project: rules, hooks, skills and the .itd tools (itd_hygiene.py, itd_progress.py, check_contract_drift.py, itd_init_validate.py) run from the installed copy through skills/_shared/itd_tool.sh. An adopted project holds only its own contracts (.itd/*.json, *.md), its state (.itd-memory/) and a short pointer block in CLAUDE.md / AGENTS.md. Updating the installation therefore updates every project on the machine:

• Claude Code: update the plugin, then bring the checkout to the same release and synchronize from it - a stale checkout would copy old files over the new installation:

  git -C ~/idea-to-deploy-src pull --ff-only
  

  bash ~/idea-to-deploy-src/scripts/sync-to-active.sh
  

  The sync installs hooks, skills, templates and the managed global CLAUDE.md block.

• Codex: refresh the plugin through the Codex plugin UI.

One fallback remains for compatibility: when no installed copy of a tool is found at all, itd_tool.sh runs a legacy project copy .itd/<tool>.py left by an older /adopt and warns about it on stderr. Keep the installation current to avoid running such a stale copy.

Projects adopted by older versions may still carry a copied rules block or copied .itd/*.py tools. List them read-only (nothing is changed; with Codex run the same file from the plugin root):

python3 ~/.claude/skills/_shared/itd_projects_doctor.py ~/projects

Usage

In either supported host, describe what you want:

I want to build a food delivery service

The active host adapter will:

1. Ask which route you prefer (full cycle / planning only / have docs)
2. Ask clarifying questions about your project
3. Generate architecture and documentation
4. Show you the plan and wait for your approval
5. Build the project step by step
6. Test and review after each step
7. Deploy

When you're done for the day, just say:

save session

Your session context — decisions, progress, blockers, next steps — will be saved and automatically restored in your next session.

How It Works

You: "I want to build a delivery app"
         |
         v
    /project (smart router)
         |
    Asks: A, B, or C?
         |
    +----+--------+--------+
    v              v              v
  A) Full        B) Plan       C) Guide
  Cycle          Only          Only
    |              |              |
    v              v              v
 /kickstart    /blueprint     /guide
    |
    +-- Asks clarifying questions
    +-- Generates 7 documents
    +-- Runs /review (auto-validation)
    +-- PAUSE: shows plan, waits for approval
    +-- Scaffolds project
    +-- Implements step by step:
    |     +-- /test after each feature
    |     +-- Code vs Architecture check
    |     +-- Fix issues before next step
    +-- Deploys

End-to-End Example

A minimal walkthrough of Route A (full cycle):

You:   I want to build a Telegram bot that tracks my gym workouts
Agent:  [/project] A, B, or C?
You:   A
Agent:  [/kickstart] asks 6 clarifying questions
        (users? auth? DB? hosting? budget? deadline?)
You:   personal use, no auth, SQLite, local, $0, this weekend
Agent:  generates STRATEGIC_PLAN, PROJECT_ARCHITECTURE,
        IMPLEMENTATION_PLAN, PRD, README, CLAUDE_CODE_GUIDE, CLAUDE.md
        runs /review → PASSED_WITH_WARNINGS (2 nits)
        shows plan, asks: "Approve and start coding?"
You:   yes
Agent:  Step 1/9 — scaffold project, commit
        Step 2/9 — DB models + /test
        ...
        Step 9/9 — deploy script + README update
        Done. 42 tests passing. Here is your bot.

The legacy-compatible CLAUDE.md and CLAUDE_CODE_GUIDE.md names in this example are current generator outputs, not a claim that the methodology core is Claude-only. Host-neutral output naming remains follow-up work.

Reference fixtures: reproducible golden-path scenarios used by the test runner live in tests/fixtures/. Run them with tests/run-fixtures.sh to see how each skill behaves on a known input.

Current progress / verification entry points: the living progress log is CHANGELOG.md (per-release, includes rationale); ROADMAP_v*.md files are historical. To verify the whole system locally run bash tests/run-all.sh (mirrors both CI workflows; --quick for the static core); the release procedure and its known pitfalls live in docs/RELEASE_RUNBOOK.md.

Skills

Entry Points (6 skills)

Skill	Description
/project	Smart router for creating something — asks one question and routes to /kickstart, /blueprint, or /guide
/task	Smart router for working on existing code — routes to the right daily-work skill (/bugfix, /refactor, /doc, /test, /perf, /review, ...) based on the task type
/adopt	Onboard a legacy project through the active host adapter — CLAUDE.md + .claude/settings.json on Claude Code, or AGENTS.md + Codex hooks on Codex — then bootstrap canonical .itd/ contracts and .itd-memory/ state. No reverse-engineering of plan docs.
/discover	New in v1.17.0. Product discovery phase — market analysis (TAM/SAM/SOM), competitor research, user personas, feature prioritization (MoSCoW + RICE). Outputs DISCOVERY.md ready for /blueprint.
/strategy	New in v1.19.0. Strategic replanning for existing projects — 5-dimension gap analysis, option generation with devil's advocate, ADR for pivot decisions, LAUNCH_PLAN.md updates.
/advisor	New in v1.19.0. Advisory/consulting mode — analysis-only (no code changes), multi-perspective evaluation via business-analyst + devils-advocate subagents.

Project Creation (3 skills)

Skill	Route	What it does
/kickstart	A) Full cycle	Idea to deployed product: docs, code, tests, deploy
/blueprint	B) Planning only	6 documentation files, no code
/guide	C) Have docs already	You already have architecture and plan docs (from route B, another developer, or another tool) — generates step-by-step prompts to build it

Quality Assurance (6 skills)

Skill	Description
/review	Validates documentation/code with the deterministic rubric and uses the same mandatory route-bound producer whenever the Verification Loop risk route requires an independent checker (medium/high/unknown; low remains the explicit machine-only route). No caller can downgrade the selected route (BLOCKED / PASSED_WITH_WARNINGS / PASSED).
/security-audit	Read-only OWASP-style security audit (auth, secrets, injection, CORS/CSP, deps) with same status enum as /review
/security-guidance-setup	New in v1.29.0. Security companion — sets up & integrates the official security-guidance plugin by Anthropic (free, ships default-on). A shift-left, always-on reviewer of Claude-generated code: regex pattern warnings on every Edit/Write, an LLM diff review on Stop (findings fed back before you see the turn), and an agentic commit/push reviewer tracing cross-file vulns (IDOR, auth bypass, SSRF). Detects install, prints the verified CLI command, maps it onto the lifecycle. Complements /security-audit (on-demand audit), does not replace it; does not vendor upstream code; gates unaffected.
/cross-review	Mandatory independent pre-PR review over the exact staged candidate. Uses one fresh opposite-GPT Sol -> Terra / Terra -> Sol route through itd_free_reviewer_producer.py, with no automatic provider fallback or quorum. There is no caller bypass, and acceptance remains owned by evidence-first Verification Loop adjudication. Anthropic, Copilot, Antigravity and paid adapters are optional operations infrastructure.
/grill-me	New in v1.21.0. Interactive read-only stress-test for plans, designs, architecture, and risky decisions — asks one question at a time (with a recommended answer) to surface assumptions, risks, and dependencies. Runs before /review, does not replace it.
/browser-check	New in v1.21.0. Local browser smoke-test for frontend/full-stack/visual flows via a bundled Playwright harness (Browser Use / in-app browser fallback) — checks first render + critical path (navigation, forms, states). Broken render/flow → BLOCKED before deploy.

Daily Work (6 skills)

Skill	Description
/test	Generate unit, integration, and edge case tests
/bugfix	Systematically find and fix bugs (was /debug before v1.4.0 — renamed to avoid collision with Claude Code's built-in /debug slash command)
/perf	Performance analysis and optimization
/refactor	Improve code structure without changing behavior
/explain	Explain how code works with ASCII diagrams
/doc	Generate documentation matching project style

Quality Assurance — Supply Chain (1 skill, new in v1.4.0)

Skill	Description
/deps-audit	Read-only dependency audit — parses lockfiles, queries OSV.dev + GitHub Advisory for known CVEs, SPDX license compatibility, abandoned-package detection (> 2y without release). Same status enum as /review.

Operations (5 skills)

Skill	Description
/migrate	Apply database migrations safely — backup, apply, verify, document rollback. Refuses production without explicit confirmation.
/migrate-prod	New in v1.19.0. Migrate running production services between hosts — inventory, setup target, data migration, dual-run, DNS cut-over, rollback plan, decommission.
/deploy	New in v1.19.0. Deploy to production — sync files (tar-over-ssh), regenerate gateway config, build Docker image, restart containers, apply pending migrations, verify healthcheck. Refuses without explicit user confirmation; always calls /session-save after.
/harden	New in v1.4.0. Production-readiness hardening rubric — health checks, graceful shutdown, structured logging, rate limiting, Prometheus/Grafana, backup strategy, k6 load tests, SRE runbook. Generates missing artifacts on user approval.
/infra	New in v1.4.0. Infrastructure-as-code generator — Terraform modules (DigitalOcean, AWS, Hetzner), Kubernetes manifests + Helm chart, secrets wiring (Vault, AWS Secrets Manager, Doppler, Sealed Secrets). Remote tfstate with locking enforced for prod.

Workflow (6 skills)

Skill	Description
/session-save	Save session context to canonical project-local memory — what was done, key decisions, blockers, next steps. Ensures continuity across supported host sessions.
/autopilot	Auto-pipeline that runs discover → blueprint → kickstart → review → test with minimal human intervention (GSD-inspired). Takes a project idea and produces a full project with all docs, code, tests, and review.
/handoff	New in v1.21.0. Write a compact HANDOFF.md context packet to transfer work to the next session/agent when there is no return path — compaction, delegation, AFK run, or recovery. Distinct from /session-save (milestone save).
/goal	New in v1.44.0. Long-goal mode — decompose a multi-session goal into ordered verifiable units in .itd-memory/GOAL.json (user approval required), drive them one at a time through the standard /task pipeline (WIP=1, evidence-gated verified), and resume across sessions from the first non-verified unit. Its bounded envelope now enforces observed token/time/attempt stops, routes checker cost by sealed risk tier, emits ≤4 KB checkpoints, and can grade clean A/B evidence with a deterministic anti-Goodhart 5/5 evaluator. Brownfield-first; never bypasses /review, /test, or the DoD.
/retro	New in v1.46.0. Self-proposing improvement cycle for the methodology itself, split FACTS / PROPOSALS / MERGE: itd_retro_scan.py deterministically aggregates telemetry (VCR, regressions, active goals, SKILL_BYPASS ledger, cost), the model turns facts into ranked proposals where every one cites evidence (anti-Goodhart: external signals only), and the human merges via the ordinary release pipeline. Never edits the methodology itself; not a gate.
/graph	New (unreleased). Graph Lite — turn ONE task into an explicit agent graph (jobs, arrows, shared state, a checker separate from the writer, a human terminal), get the owner to approve the exact graph digest, run it through the host workflow runtime (or node by node when the host has none) and keep every node output as a file under .itd-memory/graph-runs/<run-id>/. Default-off (disable-model-invocation), read-only nodes, a measured exception to ADR-012 (ADR-013); the shipped template module-neighbour-check hunts four defect classes (owner, money, dedup, time) across a whole money/access module.

Research (2 skills)

Skill	Description
/market-scan	New in v1.21.0. Fresh public market & community signal scan (~30-day window via the last30days engine) for discovery, validation, ICP, competitor, and launch decisions. Normalizes findings into MARKET_BRIEF.md (dated append). Distinct from /discover (full discovery phase).
/mcp-docs	New in v1.21.0. Read-only lookup of fresh library/framework documentation via MCP providers (Context7) — resolves a library ID, asks a narrow question, records source + decision. Use before adding dependencies or integrating against SDKs.

Integration (4 skills)

Skill	Description
/github-workflow	New in v1.21.0. GitHub Issues / PR / CI / release workflow — inspects PR & check status (connector or gh), debugs failing Actions before code changes, prepares branches/changelogs/release notes, keeps .rubric-status aligned. Explicit-invocation; no push/merge/close/release without explicit intent.
/tool-sync	New in v1.21.0. Mirror idea-to-deploy artifacts to external tools — GitHub, Linear, Notion, Google Drive, Obsidian. Connector-native reads before writes (reconcile, never clobber), export-only fallback to .itd-integrations/. Explicit-invocation.
/obsidian-export	New in v1.21.0. Export planning docs, handoff, memory, state, decisions, and gates into an Obsidian-compatible local knowledge graph under .itd-integrations/obsidian/. Derived & regenerable — canonical docs stay the source of truth.
/seo-setup	New in v1.28.0. SEO companion — sets up & integrates the upstream Claude SEO plugin (MIT), which ships 25 sub-skills + 18 sub-agents for technical SEO, content quality (E-E-A-T), Schema.org, sitemaps, Core Web Vitals, local SEO, backlinks, AI/GEO, hreflang, and the Google SEO APIs. Detects install, runs/prints the verified CLI commands, and maps it onto the lifecycle (discover→keyword/competitor, blueprint→schema/hreflang, kickstart→on-page, harden→technical/CWV/GEO, deploy→drift baseline + Google APIs). Named -setup to avoid colliding with upstream's own seo skill. Does not vendor upstream code; gates are unaffected.

Efficiency (2 skills)

Skill	Description
/caveman	New in v1.26.0. Token-efficiency communication mode — terse caveman-style replies (lite/full/ultra/wenyan-*) that cut output tokens ~75% while keeping full technical accuracy. Port of the public Caveman plugin (MIT). idea-to-deploy gates still win over brevity: never compresses gate status, blockers, verification evidence, security warnings, or destructive confirmations. Style control only — does not replace /review, /test, or any work route.
/context-mode-setup	New in v1.27.0. Context-window optimization companion — sets up & integrates the upstream Context Mode plugin (ELv2), which sandboxes large tool output into a local FTS5 store so the agent searches it (ctx-search) instead of dumping it into context (vendor claim ~98% per-call reduction). Detects install, runs/prints the verified CLI commands, and maps its ctx-* skills onto the lifecycle (long /kickstart builds, long /task//bugfix sessions). Named -setup to avoid colliding with upstream's own context-mode skill. Does not vendor upstream ELv2 code; gates are unaffected.

Subagents

Heavy skills run in isolated contexts with specialized agents for better quality:

Agent	Used by	Specialization
architect	/blueprint	Database schemas, API design, tech stack selection
code-reviewer	/review	Cross-document validation, consistency checks, scoring
test-generator	/test	Comprehensive test coverage, edge cases, mocking
perf-analyzer	/perf	Bottleneck detection, N+1 queries, algorithm optimization
doc-writer	/doc	README, API docs, inline comments, style matching
business-analyst	/discover	Market analysis, competitor research, user personas, feature prioritization
devils-advocate	/advisor, /strategy, /blueprint	Adversarial reviewer — challenges architectural and strategic decisions, proposes counter-arguments before implementation
researcher	/market-scan, /mcp-docs, /discover	Bounded market/technical/docs research that changes product, architecture, dependency, or integration decisions
security-reviewer	/security-audit, /harden	Read-only security audit — exploitability/impact ranking, remediation plan, never prints secrets
ux-reviewer	/browser-check, /review	Browser-based UX/visual/accessibility review of user-facing changes — prefers Playwright evidence over static guesses

Skill Contracts

Note for users: in normal use, you do not invoke skills manually. Describe your task in natural language ("I want to build X", "fix this bug", "add tests for this function") and the active host adapter routes it through skill discovery and trigger-phrase matching. Skills also invoke each other in chains — see the Call Graph section below. The contracts table exists for debugging, contributions, and explicit control; it is not a "list of commands you must memorize".

Each skill has a documented contract — what it reads, what it writes, what side effects it has, and whether it's safe to run twice.

Skill	Inputs	Outputs (files written)	Side effects	Idempotent
/project	User idea (text)	None directly — routes to another skill	None	✅
/task	Task description (text) for an existing project	None directly — routes to /bugfix, /refactor, /doc, /test, /perf, /review, /security-audit, /deps-audit, /migrate, /harden, /infra, or /explain	None (router only)	✅
/discover	Product idea or problem statement	DISCOVERY.md (market analysis, personas, prioritization)	None (analysis only, no code)	✅
/kickstart	User idea + clarifications	7 docs + scaffolded project + commits	Git commits, file scaffolding, possible deploy	⚠️ Resumes from CLAUDE.md status
/blueprint	User idea + clarifications	6 docs + CLAUDE.md + .gitignore	None (planning only, no code)	⚠️ Asks before overwrite
/guide	Existing PROJECT_ARCHITECTURE.md + IMPLEMENTATION_PLAN.md	CLAUDE_CODE_GUIDE.md	None	✅
/review	All project docs + code (read-only)	Validation report (stdout) + optional fix patches	Optional doc fixes if user agrees	✅
/test	File/function/module path	New test files matching project conventions	New test files only	✅
/bugfix	Error message / stack trace / symptom	Code patch fixing root cause + optional regression test	Source file edits	⚠️ Should not be re-run after fix
/refactor	File/function/area	Refactored code preserving behavior	Source file edits	✅ Behavior preserved
/perf	File/function/area + perf complaint

Reading the table:

• Idempotent ✅ — safe to run twice on the same input. Output is unchanged.
• Idempotent ⚠️ — has stateful behavior (resume from status, asks before overwrite, expects pre-condition). Re-running may not be safe without inspection.

Call Graph

Skills can invoke each other. This is the maximum depth and the chains:

/project (router, depth 1)
  ├─ /kickstart (depth 2)
  │    ├─ /review (depth 3, automatic Quality Gate 1)
  │    ├─ /test (depth 3, after each implementation step)
  │    ├─ /security-audit (depth 3, before deploy)
  │    ├─ /deps-audit (depth 3, before deploy)     # new in v1.4.0
  │    ├─ /harden (depth 3, before prod deploy)    # new in v1.4.0
  │    └─ /infra (depth 3, optional IaC generation) # new in v1.4.0
  ├─ /blueprint (depth 2)
  │    └─ architect agent (subagent fork, depth 3)
  └─ /guide (depth 2)

/review (standalone or chained)
  └─ code-reviewer agent (subagent fork)

/perf (standalone)
  └─ perf-analyzer agent (subagent fork)

/test (standalone or chained)
  └─ test-generator agent (subagent fork)

/doc (standalone)
  └─ doc-writer agent (subagent fork)

/security-audit (standalone)
  └─ may suggest fixes but never applies them — separation of audit and remediation

/deps-audit (standalone)
  └─ read-only; honors .deps-audit-ignore for accepted-risk entries

/harden (standalone)
  └─ generates artifacts only with explicit user approval per item

/infra (standalone)
  └─ writes files only; never calls cloud APIs directly

/migrate (standalone)
  └─ refuses on production without explicit user confirmation

/session-save (standalone, no subagent)
  └─ writes session memory file + updates MEMORY.md index

/bugfix, /refactor, /explain — leaf skills, no nested invocations.

Recursion guard: No skill invokes itself directly or through a chain. Maximum observed depth is 3 (/project → /kickstart → /review or any of the other depth-3 skills). If you observe a deeper chain or loop, file an issue — that's a bug.

Hook taxonomy and Claude Code setup

Claude Code adapter note: global hooks are an optional, separate step. /plugin install registers skills and agents but deliberately does not write ~/.claude/settings.json. Codex uses its bundled adapter registration instead; do not copy these Claude paths into Codex.

Per-project install (offered by /adopt and /project). Both skills end with an explicit step: they show the read-only plan of skills/_shared/itd_project_hooks.py plan --root <project> (what would be added to <project>/.claude/settings.json), ask for confirmation, and only on a yes run itd_project_hooks.py apply --root <project> --yes. The merge is idempotent (a re-run adds nothing), keeps your own hooks, keys and permissions, skips each hook already registered user-level from an idea-to-deploy hooks dir, and never writes ~/.claude/settings.json. On a no the file is not touched; the same command installs the hooks later.

The methodology is only effective if the active host invokes the skills. Trigger matching is necessary but not sufficient: under pressure or on an ambiguous prompt an agent may default to ad-hoc tool calls. The hooks/ folder contains 31 hooks — 12 hard gates that can stop an action and 19 soft hooks for reminders, context, observability, and self-correction. The enforcement strength is the 12 hard gates, not 31. Put plainly: of the 31, 12 are hard and 19 are soft.

Hook taxonomy — 12 hard gates vs 19 soft (machine-checked)

#	Hard gate (can block/deny)	Event	What it stops
1	check-review-before-commit.sh	PreToolUse · Bash	a >2-file git commit without a diff-bound /review (v1.59.0)
2	check-dod-before-commit.sh	PreToolUse · Bash	a commit on a sensitive/payments path without the required /security-audit etc.
3	check-commit-completeness.sh	PreToolUse · Bash	committing a SKILL.md without its supporting artifacts
4	check-skill-completeness.sh	PreToolUse · Write/Edit	writing a SKILL.md without references/, fixtures, or trigger phrases
5	check-tool-skill.sh	PreToolUse · Bash/Edit/Write	a raw mutating tool call after 3 ignored skill decisions (with a skill-active grace window)
6	pii-egress-guard.sh	PreToolUse · any tool	an external mutation without an exact session-bound preview and host-native confirmation (ask), or egress of live secrets/PII
7	cost-tracker.sh	PreToolUse · Agent/Task/Bash/PowerShell	the next expensive agent/test/build attempt before its estimate crosses the configured session ceiling; cheap inspection and checkpoint calls stay available
8	narration-final.sh	SubagentStop	a subagent ending on narration instead of its result/verdict (≤2 block-pings)
9	verdict-contract.sh	SubagentStop	a review subagent ending with a prose verdict and no valid JSON verdict block (≤2 block-pings)
10	completion-gate.sh	PreToolUse · Bash	a git commit with source code claiming done while a completion layer is unproven — L2 tests failing or never run (deny, exit 2)
11	state-guard.sh	PreToolUse · Write/Edit + Bash/PowerShell	a write to a .itd-memory state ledger (/) — via Write/Edit tools OR a Bash command targeting the ledger (redirect///…, v1.78.0) — while a FRESH is owned by ANOTHER session — parallel-session last-writer-wins, the NeuroExpert 2026-04-11 incident class (deny, exit 2; ≤2 denies per session, then warn-allow; its PostToolUse validation/heartbeat legs stay soft)

Soft (19): careful, check-skills, completion-signals, completion-stop, context-aware, context-budget, crash-recovery, cross-review-precommit, execution-trace, freeze, graph-route, handoff-readiness, model-policy, pre-flight-check, record-agent-skill, risk-score, session-open-diagnostic, stuck-detection, wip-gate — they raise the invocation rate and quality, but never hard-stop (each self-declares "never blocks" / exit 0).

Hard-gate coverage — the metric that keeps the 12 honest: the fraction of hard gates backed by a behavioural test that actually drives the gate to deny/block (a real exit-2/block exercise, not a doc grep). tests/verify_gate_taxonomy.py asserts the 12/19/31 split and this README table stay in sync with hooks/; tests/verify_harness_map_fixtures.py enforces coverage. Target: 12/12.

Claude Code global hook install

Recommended — one command:

git clone https://github.com/hihol-labs/idea-to-deploy ~/idea-to-deploy-src
cd ~/idea-to-deploy-src && bash scripts/sync-to-active.sh

The script copies all hooks into ~/.claude/hooks/, patches ~/.claude/settings.json to register them, and syncs the latest skill/agent definitions. It is idempotent — re-running only updates changed files.

The Codex adapter discovers the bundled hooks/hooks.json instead. Review it with /hooks; repository-local fallback setup is documented in docs/CODEX_ADAPTER.md.

mkdir -p ~/.claude/hooks
cp hooks/check-skills.sh hooks/check-tool-skill.sh hooks/pre-flight-check.sh \
   hooks/check-skill-completeness.sh hooks/check-commit-completeness.sh \
   hooks/check-review-before-commit.sh hooks/session-open-diagnostic.sh \
   ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

Then add the hooks block to your ~/.claude/settings.json — full settings.json snippet and pipe-tests in hooks/README.md.

After installation:

• pre-flight-check.sh (v1.5.0, UserPromptSubmit) — runs before every user prompt. Loads git log, git status, and the project memory index (MEMORY.md) into the active host context, and warns if a parallel session has touched the project in the last 10 minutes (via .active-session.lock). Soft context injection — never blocks. Prevents the v1.13.2 incident class where two parallel sessions independently fixed the same drift.
• check-skills.sh (UserPromptSubmit) — scans every prompt for ~80 Russian/English triggers and injects a [SKILL HINT] reminder when a skill matches. Soft reminder — never blocks.
• check-tool-skill.sh (PreToolUse on Bash/Edit/Write/NotebookEdit) — injects a [SKILL CHECK] reminder before raw tool calls, rate-limited to one reminder per 60 seconds. Escalating hard gate (#5 above): it reminds for the first 2 ignored skill decisions, then on the 3rd consecutive ignore (no Skill call and no SKILL_BYPASS) it denies the tool call (exit 2). A skill-active grace window and the read-only-Bash allowlist keep routine recon from tripping it.
• check-skill-completeness.sh (v1.5.1, PreToolUse on Write/Edit/MultiEdit) — before any modification to skills/*/SKILL.md inside a methodology repo, parses the pending tool input and verifies that references/, trigger phrases in the prompt hook, and regression fixture all exist. Hard block (exit 2 + hookSpecificOutput.permissionDecision: "deny") — the Write never runs, the file never lands on disk.
• check-commit-completeness.sh (v1.5.1, PreToolUse on Bash) — before any git commit inside a methodology repo, parses the staged diff and denies the commit if a skill file is staged without its supporting artifacts. Hard block (exit 2 + hookSpecificOutput.permissionDecision: "deny") — the commit never runs.

All 31 hooks are registered by the canonical adapters. handoff-readiness.sh is soft/rate-limited and can be disabled with ITD_HANDOFF_READINESS=0; methodology-only enforcement hooks no-op on unrelated projects. execution-trace.sh records paired intent/outcome rows, while cost-tracker.sh keeps estimated and host-observed token counters explicitly separate. Registration and reload behavior remain host-specific.

Why this matters: in a 2026-04-07 production-incident retrospective, Claude Code (Opus 4.6) spent ~2 hours doing direct SSH/sed/curl work to fix an auth outage. /bugfix would have been the right tool. It was never invoked — nothing forced it. These hooks are the answer. See hooks/README.md for the full case study.

Quality Gates

The methodology includes two automatic quality checkpoints. As of v1.2.0 they use binary rubrics (deterministic checklists), not subjective scores.

Gate 1: Plan Review

After documentation generation, before coding:

• Automatic /review validation against the rubric in skills/review/references/review-checklist.md
• The rubric is split into Critical / Important / Nice-to-have checks
• Gate passes only when all Critical checks pass; Important/Nice-to-have produce warnings, not failures
• Mandatory user approval — you see the plan + warnings and confirm before any code is written

Gate 2: Step-by-Step Code Review

After each implementation step:

• Code compiles and runs without errors
• Tests pass
• Code matches architecture document
• No hardcoded secrets or naming inconsistencies
• 3 consecutive failures → STOP and ask user for guidance (no infinite retry)

What Gets Generated

The shared generators still emit the legacy-compatible CLAUDE.md and CLAUDE_CODE_GUIDE.md filenames listed below. Claude Code consumes them natively; Codex adoption uses AGENTS.md as its guidance entry while the canonical continuity and completion state lives in .itd-memory/ and .itd/. This naming residue is disclosed rather than presented as full output-layer neutrality.

Route A (Full Cycle) produces:

7 Documents:

• STRATEGIC_PLAN.md — strategy, competitors, budget, KPIs, risks
• PROJECT_ARCHITECTURE.md — DB schema, API endpoints, auth flow, infrastructure
• IMPLEMENTATION_PLAN.md — 8-12 steps with specific files and verification
• PRD.md — user stories, requirements (P0/P1/P2), kill criteria
• README.md — quick start guide
• CLAUDE_CODE_GUIDE.md — copy-paste prompts for each step
• CLAUDE.md — project memory and status tracking

Plus: working deployed project with tests, Docker, and CI/CD.

Route B (Planning Only) produces:

6 Documents:

• STRATEGIC_PLAN.md — strategy, competitors, budget, KPIs, risks
• PROJECT_ARCHITECTURE.md — DB schema, API endpoints, auth flow, infrastructure
• IMPLEMENTATION_PLAN.md — 8-12 steps with specific files and verification
• PRD.md — user stories, requirements (P0/P1/P2), kill criteria
• README.md — quick start guide
• CLAUDE_CODE_GUIDE.md — copy-paste prompts for each step

Plus: CLAUDE.md (project memory) and .gitignore. No code is written. You can review the plan, share it with a client or team, and later switch to route A to start implementation.

Route C (Have Docs Already) produces:

1 Document:

• CLAUDE_CODE_GUIDE.md — step-by-step prompts based on your existing documentation

Takes your existing architecture, plan, and requirements — and converts them into ready-to-use prompts. You run each prompt in the active supported host, inspect the result, and move to the next step. Full manual control over every stage.

Seamless Route Switching

Routes are not dead ends — you can switch between them at any time without losing work.

Switch	What you say	What happens
B → A	"Start implementation"	Detects existing docs, validates, skips to coding
C → A	"Start implementation"	Detects guide + docs, supplements if needed, starts coding
C → B	"Create full documentation"	Reads existing guide, generates missing docs
A (interrupted) → A	"Continue the project"	Finds last completed step, resumes from there

How it works: Each skill automatically scans for existing project files on startup. If documentation, code, or a guide already exists — the skill reuses it instead of starting from scratch. One phrase from you — and the system picks up where it left off.

Nothing is lost. Switch routes, take breaks, come back later — the methodology remembers your progress.

Recommended Models

Portability boundary: the table below is the current Claude Code adapter mapping (Haiku/Sonnet/Opus and /model), not a provider-neutral benchmark. Codex uses its native model/effort controls while preserving the shared risk-tier and evidence floors. No equivalence is claimed for other providers.

As of v1.3.0, the recommended model is also encoded in each skill's body in a ## Recommended model section. The table below is the same data in summary form. /blueprint and /kickstart auto-fall-back to Lite mode on Sonnet and refuse on Haiku.

Model-routing policy (v1.31.0): the per-phase rationale behind these picks — expensive tiers on reasoning-heavy phases, cheap tiers on mechanical ones, to control OpEx — lives in docs/MODEL-ROUTING-POLICY.md. It is a transparent policy applied via /model + per-agent model: frontmatter, not an auto-router (see ADR-001).

Skill	Minimum	Recommended	Notes
/project	Haiku	Sonnet	Router only — minimal reasoning
/task	Haiku	Sonnet	Router for daily-work skills — minimal reasoning
/discover	Sonnet (Lite)	Opus (Full)	Deep market analysis, competitor research, multi-dimensional prioritization
/blueprint	Sonnet (Lite)	Opus (Full)	Lite mode auto-active on Sonnet
/kickstart	Sonnet (Lite)	Opus (Full)	Lite mode auto-active on Sonnet, refuses Haiku
/guide	Sonnet	Opus	Long prompt sequences benefit from Opus
/review	Sonnet	Opus	Cross-document validation
/security-audit	Sonnet	Opus	Cross-file pattern recognition
/test	Sonnet	Sonnet	Pattern-matching to existing convention
/bugfix	Sonnet	Sonnet	Opus only for cross-language analysis
/refactor	Sonnet	Sonnet	Mechanical via Fowler catalog
/perf	Sonnet	Opus	Cross-layer reasoning helps
/doc	Sonnet	Sonnet	Style matching is straightforward
/explain	Haiku	Haiku	Read-only walkthrough; Haiku is fast enough
/migrate	Sonnet	Sonnet	Mechanical (read SQL → run → verify)
/deps-audit	Sonnet	Sonnet	Parsing + API lookups; Opus doesn't improve accuracy
/harden	Sonnet	Opus	Cross-layer reasoning (code + infra + observability)

Who Is This For

Audience	Value
Freelancers	Take more orders, deliver faster. One project per weekend instead of two weeks
Startups	MVP in 2 days instead of a month. No team needed. Professional architecture
Beginners	No need to know how to structure a project — the system does it for you
Agencies	Standardize your process. Same quality, predictable timelines for every client

Project Types

Works with any project that can be built with code:

• SaaS platforms
• Telegram / Discord bots
• REST APIs and integrations
• Landing pages and web apps
• CLI utilities
• Mini Apps
• E-commerce
• Parsers and scrapers

What This Methodology Does NOT Do

Setting expectations honestly. As of v1.4.0 this list is two items — the remaining limitations are fundamental, not gaps.

• Does not replace a senior architect on novel systems in regulated industries. The methodology encodes strong defaults for typical web stacks, but LLMs cannot exercise the judgment that comes from having shipped production systems under SOC 2, HIPAA, PCI DSS, GDPR, or HITRUST audit. For healthcare, fintech, aerospace, or other high-risk domains, treat idea-to-deploy as a starting skeleton — a human expert still owns the compliance posture and the hard architectural tradeoffs.
• Does not run autonomously forever — by design. After 3 consecutive step failures in Phase 4, the methodology stops and asks for human input. This is a safety feature, not a limitation. Removing it would let the LLM spin in circles on impossible tasks and burn user budget. Human-in-the-loop is the point.

If either of these is a blocker for your use case, layer your own process on top of the methodology.

Previously on this list — now covered

Items that used to be in this section and are now handled by the methodology:

Was a limitation	Now covered by
Does not guarantee a production-ready deploy	/harden — hardening rubric + artifact generation (health checks, graceful shutdown, structured logs, metrics, backups, load tests, runbook)
Does not audit third-party dependencies	/deps-audit — OSV.dev + GHSA CVE lookups, license compatibility, abandoned-package detection
Does not manage infrastructure	/infra — Terraform modules, Helm charts, secrets wiring for DO/AWS/Hetzner/K8s
GIGO — vague clarifications produce vague plans	/kickstart v1.4.0 — clarification validation with targeted follow-ups and structured confirmation before doc generation
Not a substitute for code review by a human on critical paths	/review v1.4.0 — expanded code rubric with SOLID checks, cyclomatic complexity, Fowler smells, Google Engineering Practices (still not a full replacement for peer review on truly critical paths, but it's now close)

See CHANGELOG v1.4.0 for the detailed breakdown.

Troubleshooting / FAQ

A skill is not being invoked when I expect it to. An agent host may default to ad-hoc tool calls on ambiguous prompts. Verify that the adapter and its hooks are enabled; the discovery hooks inject [SKILL HINT] and [SKILL CHECK] reminders. You can also name a skill explicitly: /bugfix, /test, etc.

How do I update the Claude Code adapter? /plugin update hihol-labs/idea-to-deploy. Check the CHANGELOG for what changed.

How do I uninstall the Claude Code adapter? /plugin uninstall hihol-labs/idea-to-deploy. Hooks in ~/.claude/settings.json (if you installed them) must be removed manually.

For Codex enable/update/removal behavior, use the normal Codex plugin UI; see Codex adapter.

Conflicts with other plugins. Skills are namespaced by plugin, so two plugins can coexist even if both define /test. The router will ask which one to use. Hooks are global — if another plugin also registers UserPromptSubmit hooks, they run in the order defined in settings.json.

/review flags my plan as BLOCKED but I disagree. See the Troubleshooting section in the /review skill itself (skills/review/SKILL.md) — it documents how to override Critical checks with explicit user consent.

I'm using the Claude Code adapter on Haiku and /kickstart refuses to run. By design — see the Recommended Models table. /kickstart and /blueprint require at least Sonnet; Haiku is fine for /project, /explain, and read-only skills.

The methodology "forgot" my project. Check the active host guidance file (CLAUDE.md or AGENTS.md) and the canonical .itd-memory/STATE.json / GOAL.json state. Host-private transcript memory is optional and never overrides project-local state. Re-run /adopt if the adapter guidance/config is missing.

How does the methodology preserve context between sessions? Three mechanisms work together:

1. Project-local ledger — .itd-memory/STATE.json, optional GOAL.json, events, session checkpoints, and MEMORY.md are the canonical continuity source on both supported hosts.
2. /session-save and handoff workflows — record decisions, blockers, evidence, and the next action at milestones or session close.
3. Host guidance — CLAUDE.md or AGENTS.md tells a fresh session how to reconstruct the same local state.

Important: an abruptly closed session can lose the last uncheckpointed fragment. Say “save session” before closing when possible.

Where are my installed skills located? The Claude Code adapter normally installs under ~/.claude/plugins/idea-to-deploy/skills/; Codex exposes the same canonical skills/ tree through its package. Each skill has a SKILL.md contract.

How does idea-to-deploy relate to "Dive into Claude Code" (arxiv 2604.14228)? The April 2026 paper by Liu et al. (arxiv 2604.14228) and its companion repo VILA-Lab/Dive-into-Claude-Code formalize 16 architectural principles behind Claude Code itself. We published docs/DESIGN_SPACE.md mapping the methodology against those principles: of the 15 applicable ones, 13 are covered in full or partial form, and 2 (context budgeting and on-disk checkpoints beyond git) are acknowledged gaps. The map is honest by design — both gap items are candidate scope for a future v1.21 release once multi-point user signal arrives.

How does idea-to-deploy relate to "Harness Engineering" (walkinglabs)? The Harness Engineering course formalizes the discipline: the goal is not to make the model smarter but to build a closed working system with explicit rules and boundaries — the central thesis of this methodology. docs/HARNESS_ENGINEERING_MAP.md records a version- and evidence-scoped 5/5 conformance result. Host guidance maps to CLAUDE.md on Claude Code and AGENTS.md on Codex; the load-bearing portable layer is .itd/ + .itd-memory/, not either filename.

Something else is broken. Open an issue: github.com/hihol-labs/idea-to-deploy/issues. Include the active host/adapter version, model or effort setting, prompt, and unexpected behavior.

Contributing

Contributions are welcome. The project is small enough that process is lightweight:

1. Report issues / suggest skills — open a GitHub issue with a concrete scenario and expected behavior.
2. Propose a new skill — skills live under skills/<name>/SKILL.md and follow the shape documented in the existing 41. Each needs: frontmatter (name, description, triggers, allowed-tools, recommended model), Instructions, Examples, Troubleshooting.
3. Fix a bug or polish a skill — open a PR against main. Run tests/run-fixtures.sh locally to sanity-check against fixtures before submitting.
4. Improve documentation — both README.md and README.ru.md must stay in sync. Updates to one require updates to the other.

All PRs are reviewed against the same binary rubric that /review uses on generated projects. No subjective scoring.

Requirements

• One validated host: Claude Code with plugin support, or OpenAI Codex with plugin/hook support
• The account/subscription required by the selected host
• git on PATH

Changelog

See CHANGELOG.md for a full release history. This project follows Semantic Versioning and Keep a Changelog.

License

MIT

Author

HiH-DimaN — GitHub