Idea To Code

= Idea to Code

Idea to Code is a disciplined, human-in-the-loop Claude Code operating model.

image::./idea-to-code.png[]

== Key features

• Refines an idea (feature, bug fix, ...) into a specification and implementation plan
• Interactively executes the implementation plan using test-driven development (TDD), with human oversight
• Constrains GenAI interactions with explicit development and debugging instructions
• Implements a feedback loop for continually improving how Claude Code operates
• Run Claude Code in a secure sandbox using https://github.com/humansintheloop-dev/isolarium/[Isolarium]

== Why humans in the loop development?

If you want quality software then must be developed by human developers - GenAI is a tool, not a developer.

The human developer is responsible for the delivered software

A GenAI coding agent must write code iteratively using TDD. The developer must carefully review any GenAI-generated code and provide prompt feedback.

== About Idea to Code

Idea to Code consists of the following:

• The i2code CLI tool — a UV-installable Python CLI that implements the entire idea-to-code workflow and plan file management.
• A Claude Code plugin that provides skills, commands and hooks.
• Template CLAUDE.md and .settings.local.json.

Let's look at the key features starting with the idea to code workflow.

=== The idea to code workflow

The idea to code workflow consists of the following steps:

. Exploring an idea - an interactive, Claude Code-driven Q&A session to flesh out an idea . Creating a specification - GenAI creates a specification from the Q&A session . Creating an implementation plan - a sequence tasks that are prompts for Claude Code . Executing the implementation plan - running the coding agent to execute the plan

To use this workflow simply run i2code go:

[source,bash]

i2code go ~/ideas/some-feature

where ~/ideas/some-feature is a directory that will contain the idea, spec, and implementation plan.

The workflow creates the following files in that directory:

• some-feature-idea.md - the initial idea
• some-feature-discussion.md - the Q&A discussion
• some-feature-spec.md - the specification
• some-feature-plan.md - the plan consisting of tasks, which are marked as completed ([ ] -> [x]) as the plan is executed

Note: the file name is prefixed with the directory name.

For example, see https://github.com/humansintheloop-dev/humansintheloop-dev-examples-loctree/tree/master/docs/features/loc-outliner[humansintheloop-dev-examples-loctree/docs/features/loc-outliner], which is described in more detail below.

=== The i2code CLI tool

The i2code CLI tool is a UV-installable Python CLI that provides the entire idea-to-code workflow as subcommands. It bundles the workflow shell scripts and prompt templates as package data, with thin Click wrappers that forward arguments and propagate exit codes.

The CLI is organized into the following command groups (see link:./docs/i2code-cli/i2code-cli.adoc[full CLI reference] for details):

[cols="1,3"] |=== | Command | Purpose

| link:./docs/i2code-cli/go.adoc[i2code go <dir>] | Run the full idea-to-code orchestrator

| link:./docs/i2code-cli/idea.adoc[i2code idea brainstorm <dir>] | Brainstorm and explore an idea

| link:./docs/i2code-cli/spec.adoc[i2code spec create\|revise <dir>] | Create or revise a specification

| link:./docs/i2code-cli/plan.adoc[i2code plan create\|revise <dir>] | Create or revise an implementation plan

| link:./docs/i2code-cli/design.adoc[i2code design create <dir>] | Create a design document from a specification

| link:./docs/i2code-cli/implement.adoc[i2code implement <dir>] | Execute an implementation plan

| link:./docs/i2code-cli/improve.adoc[i2code improve ...] | Analyze sessions, review issues, update configuration

| link:./docs/i2code-cli/setup.adoc[i2code setup ...] | Initial project setup and configuration updates

| link:./docs/i2code-cli/implement.adoc[i2code scaffold <dir>] | Generate project scaffolding for an idea directory

| link:./docs/i2code-cli/tracking.adoc[i2code tracking setup] | Manage HITL tracking directories for session and issue recording |===

The plan group also includes subcommands for plan file management (get-next-task, mark-task-complete, etc.) used by the plan-file-management skill to enable Claude to read and edit plan files.

Example commands:

[source,bash]

i2code go docs/features/my-feature i2code idea brainstorm docs/features/my-feature i2code spec create docs/features/my-feature i2code plan create docs/features/my-feature

=== Running Claude Code in a secure sandbox

The i2code implement command provides the option of running Claude Code in a secure sandbox using https://github.com/humansintheloop-dev/isolarium/[Isolarium].

The --isolation-type option specifies the sandbox type:

$ i2code implement --isolation-type nono/container/vm my-idea

Claude will then run in an isolated environment of the specified type.

=== Guiding Claude Code

Claude code needs guidelines. This project defines the idea-to-code Claude Code plugin along with template CLAUDE.md and .settings.local.json files. The plugin defines various skills, commands and hooks. Key skills include:

• plan-file-management - tells Claude when and how to use i2code plan commands to read and edit plan files
• tdd - implements a TDD red-green-refactor workflow
• commit-guidelines - structures the Git commit message
• ...

Key commands are:

• commit-changes - commits staged and unstaged changes
• claude-issue-report - described below

There are also session tracking hooks, which are described below.

=== Improving how Claude Code operates through context engineering

Claude Code regularly makes mistakes and, unlike a human, will repeatedly make the same mistake again. It's essential, therefore, to continue update the plugin to improve how Claude Code operates.

To support continuous improvement, the idea-to-code Claude Code plugin provides the following capabilities:

• claude-issue-report - a slash command that reports an issue in .hitl/issues
• hooks - record the Claude sessions (.hitl/sessions) and associate filed issues with the session

In addition, there are the following i2code subcommands:

• i2code tracking setup - migrates and links HITL tracking directories (see link:./docs/i2code-cli/tracking.adoc[tracking])
• i2code improve analyze-sessions <tracking-dir> - analyzes project tracking sessions
• i2code improve summary-reports <hitl-dir> - generates summary reports from sessions
• i2code improve review-issues <hitl-dir> - analyzes filed issues and updates the Claude Code plugin
• i2code improve update-claude-files <project-dir> - updates the template files with changes made to a project's CLAUDE.md and .settings.local.json

=== Setting up a project

The i2code setup commands configure Claude Code files in a project directory:

• i2code setup claude-files --config-dir <path> - copies initial Claude config files into a project
• i2code setup update-project <project-dir> --config-dir <path> - updates a project's CLAUDE.md and .settings.local.json from the template files

=== Examples

Here's some examples

• https://github.com/eventuate-platform/eventuate-tram-spring-micrometer-tracing/tree/master[eventuate-tram-spring-micrometer-tracing/tree/master] - provides distributed tracing support for Eventuate Tram using Micrometer Tracing. Here's the https://github.com/eventuate-platform/eventuate-tram-spring-micrometer-tracing/blob/master/docs/features/use-micrometer-tracing/use-micrometer-tracing-idea.txt[idea file].

• https://github.com/humansintheloop-dev/humansintheloop-dev-examples-loctree[`loctree`], a GoLang terminal user interface (TUI) application that provides an interactive, hierarchical view of lines of code (LOC) counts for a given directory structure. See link:./docs/idea-to-code-workflow.adoc[idea to code workflow for Loctree]

• This project itself — packaging workflow scripts as i2code subcommands. See link:./docs/features/i2code-idea-to-code-subcommand-v2/i2code-idea-to-code-subcommand-v2-idea.txt[idea], link:./docs/features/i2code-idea-to-code-subcommand-v2/i2code-idea-to-code-subcommand-v2-spec.md[spec], and link:./docs/features/i2code-idea-to-code-subcommand-v2/i2code-idea-to-code-subcommand-v2-plan.md[plan]

== Installation

=== Prerequisites

• Claude Code - see https://microservices.io/post/architecture/2025/07/09/vibe-coding-good-almost-other-part-2.html[Vibe coding: the good, the almost, and the @#$%** - Part 2] for getting started.
• https://docs.astral.sh/uv/[uv] - Python package and project manager

=== Installing

Clone the repository and run the install script:

[source,bash]

gh repo clone humansintheloop-dev/humansintheloop-dev-workflow-and-tools cd humansintheloop-dev-workflow-and-tools ./install-plugin.sh

This registers the local clone as a plugin marketplace and installs the idea-to-code plugin. Restart Claude Code to load the plugin.

Then install the i2code CLI tool:

[source,bash]

uv tool install -e .

=== Uninstalling

[source,bash]

./uninstall-plugin.sh

== Acknowledgement

The original inspiration and some prompts came from this https://harper.blog/2025/02/16/my-llm-codegen-workflow-atm/[excellent post].

I've subsequently been inspired by https://github.com/nTCoding/claude-skillz/[Nick Tune's work] - most notable the TDD skill and the /claude-issue-report command.