ai-in-the-human-loop

AI in the human loop

A template and live experiment for running a HUMAN.md feedback loop in coding projects that use AI agents.

HUMAN.md collects friction that an agent observes on the human side of the loop — unclear requests, missing decisions, undeclared scope, absent review criteria — and turns each observation into a concrete prompt or review pattern the human can use next time.

This repository is two things at once:

1. A template you can install to start the loop in another repository. The skill, the /triage and /feedback commands, the schema, and the SessionStart and Stop hooks are written to be domain-neutral and install once at user scope; a repository that opts in carries its own HUMAN.md (the rules layer) and HUMAN_FRICTIONS.md (the log layer).
2. A live experiment. This repository runs its own loop, and the Operation Log section at the bottom of HUMAN_FRICTIONS.md records what worked and what did not.

How HUMAN.md differs from Claude Code memory

Claude Code already has a per-project memory system that records facts the agent should remember across sessions. HUMAN.md is not a replacement for it. They have different jobs.

Observation	Where it goes
Something the agent itself should do differently (vocabulary, output format, procedure)	Claude Code memory
Something a human should write, review, or decide differently	HUMAN.md

Examples:

• "Avoid the verb tateru on abstract nouns" → memory. The agent's wording is the thing being corrected.
• "Declare in the request which subsystems are in scope" → HUMAN.md. The human's request is the thing being corrected.

If an observation could belong to either side, write it in the place that matches the corrective action, not the place that matches who made the mistake.

The loop

Observe   → an agent notices friction during work; the Stop hook nudges it at
            the end of each turn to record anything it observed
Record    → the human-feedback skill logs the observation to HUMAN_FRICTIONS.md,
            and when it clears the threshold writes/updates a rule in HUMAN.md
Surface   → the SessionStart hook puts the open HUMAN.md rules in front of the
            human at the start of each session
Triage    → /triage moves entries from open to adopted, obsolete, or merged

Two Claude Code hooks drive the loop's edges. The SessionStart hook (scripts/session-start.sh) surfaces open entries when a session begins. The Stop hook (scripts/stop-reminder.sh) fires at the end of every turn and emits one short, conditional reminder so the agent reconsiders, against the skill's own bar, whether the turn produced friction worth recording. The reminder prompts a single follow-up turn; the script reads the Stop input's stop_hook_active flag and stays silent on that follow-up, so it nudges exactly once and never loops. The reminder is emitted with suppressOutput so its raw text is not shown to you, and it instructs the agent to end the follow-up turn with no output when there was no friction, so a quiet turn stays quiet. Both hooks stay silent in repositories without a HUMAN.md.

Observe runs in one of two modes per repository. By default it is automatic — the per-turn nudge above. If you would rather collect on demand, set "env": { "HUMAN_LOOP_MODE": "explicit" } in the repository's .claude/settings.json; the Stop hook then stays silent and you record friction deliberately with the /feedback command. /feedback works in either mode, and /triage still walks the open rules in HUMAN.md.

The schema for an entry is defined in skills/human-feedback/HUMAN.schema.md.

Getting started in another repository

Installing the loop has two parts: set up the machinery once (the human-feedback skill, the /triage and /feedback commands, and the SessionStart + Stop hooks), then drop HUMAN.md and HUMAN_FRICTIONS.md into each repository where you want the loop.

For the machinery, pick one of the two methods below. They deliver the same skill, commands, and hooks — use one or the other on a given machine, because installing both makes the hooks fire twice.

Method A — Claude Code plugin (auto-updating)

If you use Claude Code, install the loop as a plugin from this repo's marketplace. Claude Code keeps the plugin up to date automatically.

/plugin marketplace add kawasima/ai-in-the-human-loop
/plugin install ai-in-the-human-loop@kawasima