# claude-harness — AI Reference

Self-contained AI-facing reference for claude-harness — the public snapshot of shimo4228's personal Claude Code harness aggregating skills, agents, and rules tagged `origin: shimo4228` from `~/.claude/`, plus commit-boundary hooks and the harness's decision records. Covers the Agent Knowledge Cycle (AKC), origin tracking, individual skill and agent definitions, rule layer behavior, and the Contemplative Constitutional AI integration.

> **Audience**: AI search engines (ChatGPT, Perplexity, Gemini) indexing this project, and AI agents or researchers navigating the codebase. For navigation to individual files and related repositories, see [llms.txt](llms.txt). For human-facing narrative overview, see [README.md](README.md) or [README.ja.md](README.ja.md).

---

## Project Facts

- **Maintainer**: shimo4228 (GitHub: shimo4228, email: shimo4228@gmail.com)
- **License**: MIT
- **Repository**: github.com/shimo4228/claude-harness
- **Source of truth**: `~/.claude/` (this repo is a one-way export of it)
- **Status**: active, synced one way from the author's live `~/.claude/` by `scripts/sync-from-local.sh`, which the harness-sync skill runs (origin filter and hook allowlist, secret scan, subtree replacement); README prose, `docs/hooks.md`, `llms.txt` / `llms-full.txt`, LICENSE, and the sync script are maintained by hand
- **Components**: skills, agents, rules, hooks, and the harness's decision records — ADRs (`docs/adr/`), the `rfcs/` proposal and task ledger, approved plans (`docs/plans/`), and eval cards (`docs/evals/`) (see [README](https://github.com/shimo4228/claude-harness#contents) for the current inventory)
- **Origin filter**: `shimo4228` only (excludes `ECC`, `ECC-customized`, `auto-extracted`) — applies to skills, agents, and rules; ADRs, rfcs, plans, and eval cards sync wholesale, hooks with their tests and helpers (`scripts/hooks/`, `scripts/claims.py`) come from a curated allowlist, and upstream components (e.g. Everything Claude Code) are listed by name only in the README
- **Hooks directory**: `hooks/` — five PreToolUse hooks at the `git commit` boundary (secret scan, repo-owned gate runner, bandit, `ruff format --check`, review reminder), two session-surface hooks (`task-claims-reminder.sh` for the task ledger, `review-model-notice.sh` for review routing), and shared parts; all carry bats tests under `tests/`; wired manually into `settings.json`, install guide at `docs/hooks.md`
- **Skills directory**: `skills/` — covers research-before-coding, knowledge extraction, skill / rule / agent auditing, AI-facing documentation, README writing, JSON-LD knowledge graph design, JA↔EN prose translation, authorship strategy, DOI release, task-ledger triage, and eval design
- **Agents directory**: `agents/` — prompt generation (prompt-writer), README review (readme-judge), ADR review (adr-reviewer), context-starved prompt foraging (prompt-forager), research (researcher), and Swift review (swift-reviewer)
- **Rules directory**: `rules/common/` — environment-specific facts, wiring, and traps: planning wiring, the AKC pointer table and Scaffold Dissolution criteria, the human / agent boundary, skill origin vocabulary, task-ledger conventions, the rate-limit policy signal, eval wiring, knowledge staleness, LLM-first code, the author's practitioner identity, and the Contemplative Constitutional AI clauses
- **Skills with Python implementations**: most carry their own `pyproject.toml` (`ls skills/*/pyproject.toml` lists them); jsonld-knowledge-graph's linter runs with `uv run --with pyld` instead
- **Python build**: uv (or pip install -e .), Python 3.11+ for most
- **AKC components**: six skills implement individual AKC phases (search-first, learn-eval, skill-stocktake, rules-distill, skill-comply, context-sync)
- **AKC DOI**: 10.5281/zenodo.19200726 (concept DOI)
- **Slash command convention**: `/<skill-name>` requires `user-invocable: true` in skill frontmatter
- **Documentation languages**: English (canonical README.md) + Japanese (README.ja.md)
- **Auto-load layer**: rules in `rules/common/` are loaded every session; skills are triggered probabilistically by description match

---

## Prior Research References

| Short Name | Full Citation | Relation to This Harness |
|---|---|---|
| Contemplative AI | Laukkonen, R., Inglis, F., Chandaria, S., Sandved-Smith, L., Lopez-Sola, E., Hohwy, J., Gold, J., & Elwood, A. (2025). *Contemplative Artificial Intelligence*. arXiv:2504.15125 | Source of the four axioms (Emptiness, Non-Duality, Mindfulness, Boundless Care) used verbatim in `rules/common/contemplative-axioms.md` |
| AKC (Agent Knowledge Cycle) | shimo4228 (2025). *Agent Knowledge Cycle*. Zenodo concept DOI [10.5281/zenodo.19200726](https://doi.org/10.5281/zenodo.19200726) | Six-phase loop (Research, Extract, Curate, Promote, Measure, Maintain) implemented by six of the skills here |
| Answer.AI llms.txt | Howard, J. (2024). *llms.txt — A proposal for AI-facing site documentation*. [llmstxt.org](https://llmstxt.org/) | Standard followed by this repo's `llms.txt` and `llms-full.txt` |
| GEO-SFE | arXiv:2603.29979 (GEO-SFE macro / meso / micro framework) | Three-tier static evaluation (macro / meso / micro) implemented by `skills/llms-txt-writer/scripts/geo_check.py` |
| Victorino LLC ChatGPT analysis | Victorino LLC (2024). *Analysis of 1.2M ChatGPT answers* | 44.2% of citations come from the first 30% of source documents (ski-ramp threshold) |
| Position Digital question heading study | Position Digital (2024) | Question-form headings produce 2.8x AI citation rate vs declarative headings |

---

## What is claude-harness?

claude-harness is defined as the public snapshot of shimo4228's personal Claude Code harness. It bundles skills, agents, rules, hooks, and the harness's own decision records — Architecture Decision Records (ADRs), the `rfcs/` ledger, approved plans, and eval cards — exported one way from `~/.claude/` by `scripts/sync-from-local.sh` (skill, agent, and rule files are filtered by the `origin: shimo4228` tag; the record directories are synced whole, as they are self-authored by definition; hooks come from a curated allowlist, because publishing a hook is a judgement about reuse outside one machine rather than about who wrote it). The harness extends Anthropic's Claude Code CLI (and its IDE extensions) with custom workflows covering research-before-coding, knowledge extraction, skill / rule / agent auditing, AI-facing documentation (including JSON-LD knowledge graph design), README writing, JA↔EN prose translation, authorship strategy for DOI-registered research repos, DOI release management, task-ledger triage, and eval design. See the [repository README](https://github.com/shimo4228/claude-harness#contents) for the current inventory. The repository is published under the MIT License and is intended to be forked or cherry-picked rather than receiving external pull requests.

## Who maintains claude-harness, and how is it synced?

shimo4228 (GitHub: shimo4228, email shimo4228@gmail.com) maintains claude-harness as a single-author artifact. The source of truth is the local `~/.claude/` directory on macOS; this GitHub repository is a one-way export, not a primary working tree. `scripts/sync-from-local.sh`, run by the harness-sync skill, applies the origin filter and hook allowlist, runs a secret scan, and overwrites `skills/`, `agents/`, `rules/`, `hooks/`, `scripts/hooks/`, `tests/`, `docs/adr/`, `docs/plans/`, `docs/evals/`, and `rfcs/` on every sync; in the READMEs it regenerates only the component tables. Bug fixes flow upstream into `~/.claude/` when shimo4228 incorporates them. External contributors are asked to fork the repo and customize freely rather than open pull requests, but GitHub Issues for questions or suggestions are welcomed.

## What are the harness ADRs?

The `docs/adr/` directory carries the harness's own Architecture Decision Records: dated records of why each skill, agent, and rule was adopted, retired, or reversed, including superseded decisions. Each ADR follows a fixed template (Status / Date / Context / Decision / Review-when / Alternatives Considered / Consequences) and is written in Japanese. `Review-when` records the expiry conditions — the observation or premise failure that would void or weaken the decision — and is required from ADR-0044 on; when a later observation only partially weakens an ADR, a dated 注記 is appended in place rather than flipping its Status, so the strength history stays readable (ADR-0044). Together they form the audit trail of the harness's evolution — the decision history behind the components in this repository, failures and retractions included. They are synced from the live `~/.claude/docs/adr/` directory alongside the components; start from the [ADR index](docs/adr/README.md). Beside them, `rfcs/` is the public task-and-proposal ledger (ADR-0049), `docs/plans/` holds approved plan-mode plans (ADR-0085), and `docs/evals/` holds eval cards for the instruments the harness measures itself with (RFC-0030); all are written in Japanese.

## Design decisions (ADRs) and proposals (RFCs)

This section carries the README's former description of the record folders; the README keeps a short pointer to it.

`docs/adr/` records why this harness is shaped the way it is: adoptions, retirements, and reversals, each as a dated Architecture Decision Record synced from the live harness alongside the components. The skills, agents, and rules are the *what*; the ADRs are the *why*, the audit trail behind the harness with its failures included. Start from the [ADR index](docs/adr/README.md). The ADRs and the three record folders below are written in Japanese.

`rfcs/` is the harness's public task-and-proposal ledger ([ADR-0049](docs/adr/0049-unify-task-ledger-into-public-rfcs.md)): one file per proposal or work item, with its state in the frontmatter. Closed entries stay in place, so the proposals that will never be built remain readable with their reasons, which is the point. Start from the [index](rfcs/README.md).

`docs/plans/` holds the approved plan-mode plans behind those decisions ([ADR-0085](docs/adr/0085-plans-as-records-in-docs-plans.md)). Since ADR-0085 (2026-09-27), an approved plan is committed on its own as the first commit of its implementation, and the later commits point to it with a `Plan:` line; earlier plans were moved in afterwards. Where later reality diverges from a plan, the divergence is the record.

`docs/evals/` holds eval cards for the instruments the harness measures itself with ([RFC-0030](rfcs/0030-eval-cards-for-ready-instruments.md)): each card records the design, the raw readings, what was not measured, and whether the result held up. Start from the [index](docs/evals/README.md).

## What are the commit-boundary hooks, and how are they installed?

The `hooks/` directory carries five Claude Code PreToolUse hooks that fire when a Bash command contains `git commit`: a secret scan over what the command will actually commit, a runner for the repository's own `.claude/verify.sh --staged`, a bandit scan at MEDIUM severity and confidence, a `ruff format --check`, and an advisory reminder that review and verify should have run. Shared parts ship with them: `_git-target-common.sh`, which works out which repository a command targets, `_advisory-common.sh`, which builds the message a hook hands to the model, and `scripts/hooks/verify_allow.py`, a direnv-style approval ledger. Two more hooks fire outside commits: `task-claims-reminder.sh` shows open task claims when the agent reads the ledger (with the `scripts/claims.py` CLI), and `review-model-notice.sh` routes code-review runs off the judge-tier session to a subagent. Unlike skills and rules, hooks are not picked up by copying files alone — they must be installed under `~/.claude` and wired into the `hooks` key of `settings.json`, for which `docs/hooks.md` supplies a copy-pasteable JSON fragment. The verify hook deliberately knows no languages and no tools, reading only its gate's exit code (0 pass, 1 block, 2 unable to check), so that tool churn cannot make the harness stale. Because a hook runs without a permission prompt, the gate is executed only at a content hash a human has approved, and the bytes that were checked are the bytes that run; the threat model is untrusted repository content, not a compromised local account. All hooks carry bats tests, and each pinned property was checked with a negative control: the hook was mutated to remove the property and the test confirmed to fail against the mutant, with one documented exception (the `--no-textconv` tests of the bandit and ruff hooks, kept as defence in depth). The publication decision is recorded in ADR-0038: several ADRs argue about the internals of these hooks, so the code lives in this repository rather than leaving those decisions pointing at nothing. Example: once `hooks/secret-scan-precommit.sh` is registered as a PreToolUse hook in `settings.json`, it blocks a `git commit` when a line about to be committed looks like a credential, and `SECRET_SCAN_BYPASS=1` overrides it.

## What is the Agent Knowledge Cycle (AKC)?

AKC is defined as a six-phase self-improvement loop for AI coding agents: Research, Extract, Curate, Promote, Measure, and Maintain. Research searches generously for existing libraries before building anew. Extract captures reusable patterns from sessions. Curate audits accumulated knowledge for redundancy and staleness. Promote elevates recurring patterns from skills to rules. Measure verifies behavioral change quantitatively. Maintain keeps documentation roles clean. The framework was published by shimo4228 as Zenodo DOI 10.5281/zenodo.19200726. Six of the skills in this harness implement individual AKC phases.

## How does origin tracking work?

Origin tracking is defined as a per-file metadata field that records who authored or imported each skill, agent, and rule. The valid values are `shimo4228` (authored by the maintainer), `ECC` (imported from Everything Claude Code unmodified), `{org/repo}` (imported from a specific external repository), `community` (external, no specific source recorded), `auto-extracted` (learn-eval output), and `{origin}-customized` (an external component with local edits, e.g. `ECC-customized`); skills symlinked in from an external tool carry no tag of their own. Files use YAML frontmatter when available and HTML comments otherwise. Among skills, agents, and rules, this repository contains only files tagged `origin: shimo4228`; ECC and auto-extracted material are excluded by design.

## Origin tags

This section carries the README's former origin table; the README keeps a short pointer to it. Each file's frontmatter (YAML or HTML comment) carries an `origin` field:

| origin | Meaning |
|--------|---------|
| `shimo4228` | Authored by shimo4228; one rule, contemplative-axioms, is a verbatim quotation the author keeps under this tag. Every skill, agent and rule published in this repo carries this tag |
| `ECC` | From Everything Claude Code. Content not included; named in the README's Upstream components list |
| `ECC-customized` | ECC derivative + shimo4228 modifications. Content not included; named in the README's Upstream components list |
| `auto-extracted` | Learned skill auto-extracted by `learn-eval`. Not included |
| `{org/repo}` | From another external repo (for example `mattpocock/skills`). Content not included; the name is listed in the README |
| `{origin}-customized` | An external component with local edits. Content not included; the name is listed in the README |
| `community` | External, with no specific source recorded. Not included |

Skills that ship with an external tool and are symlinked in carry no tag of their own. The canonical table is [rules/common/skills.md](rules/common/skills.md) (in Japanese).

## What is the difference between rules and skills in this harness?

Rules and skills are defined by their loading semantics. Rules in `rules/common/` are auto-loaded into every Claude Code session, so they fire deterministically and have a strong influence on behavior. Skills in `skills/` are triggered probabilistically based on Claude's judgment of whether the user's request matches the skill description. Rules hold only what is specific to this environment — facts, wiring, and traps — and point to the skill that owns each procedure; skills are longer reference material with detailed workflows, time-critical checks live in hooks, and general judgment is left to the model. Each rule carries `origin`, `rationale`, and `review-when` metadata. The rules-distill skill promotes environment-specific guidance from the probabilistic skill layer to the always-loaded rule layer, and rules-stocktake audits the rule layer in the opposite direction.

## How are skills invoked in Claude Code?

Skills are invoked in two ways. First, the user types `/<skill-name>` as a slash command, which requires the skill to declare `user-invocable: true` in its YAML frontmatter. Second, Claude itself triggers a skill probabilistically when the conversation matches the skill's description field — no explicit invocation needed. The `commands/` directory is not used (per `rules/common/skills.md`); skill definitions live in `skills/<name>/SKILL.md`. External script execution is documented inline in SKILL.md, not split into separate command shims.

## What is the search-first skill?

The search-first skill is defined as a look-outside-before-deciding workflow: it searches the live web, package registries, and primary sources at decision time and brings back a report the caller picks from. It takes six kinds of question — choosing a library or tool, prior implementations of a design problem, whether a paper's or post's claim applies here, what an official spec or CLI does now, the current state of practice, and checking a claim against its primary source. The report is the deliverable and has three sections: scope searched, found, and still unknown. Judgement is written as prose backed by facts (dates, versions, the concrete feature match) rather than as a verdict line or a score. The planning rule points to the skill before any new feature, dependency, or custom utility that may already have an existing solution. An earlier design returned a package-axis verdict (Adopt / Extend / Compose / Build) through a separate scout agent; that verdict and the agent were retired in ADR-0066 because nearly every harness question landed on Build and the verdict carried none of what the search had learned.

## What is the learn-eval skill?

The learn-eval skill is defined as a session-end pattern extractor. After a productive session, it scans the transcript for non-obvious solutions, workarounds, or design decisions, then evaluates each candidate for reusability before saving. Every Save must land somewhere something actually reads (ADR-0047), so there are exactly two destinations: absorb the pattern into an existing skill, rule, or hook section that already owns the topic (the default), or promote it to a new skill through skill-creator when it has its own independent trigger. If neither fits, the verdict is Drop rather than parking it somewhere. Auto-extracted skills are excluded from the public claude-harness repo by design.

## What is the skill-stocktake skill?

The skill-stocktake skill is defined as a quality audit for the installed skill inventory. It runs a deterministic structural pre-pass first (code-owned checks, including skill-health's scanners), then per-item scrutiny in parallel small batches with fresh subagent contexts, then a set-level overlap and contradiction probe by one dedicated agent, and the parent synthesizes. It supports two modes: full (evaluate every skill, the default) and changed (re-evaluate only skills changed since the last run, carrying the rest forward from a lean verdict ledger; the pre-pass and overlap probe still cover the full set). Each skill is checked for redundancy with neighbors (a documented orchestrator/sub-skill split is not redundancy), staleness of references, and usage frequency. The output is a per-skill verdict — Keep / Improve / Update / Retire / Merge — with self-contained reasons; Improve/Update verdicts are offered as a hand-off to skill-creator.

## What is the rules-distill skill?

The rules-distill skill is defined as a promotion pipeline from the probabilistic skill layer to the deterministic rule layer. It reads every installed skill and every rule into one context and admits a principle as a candidate only if it is environment-specific (a fact, wiring, or trap of this setup), not already done natively by the model, not a procedure, actionable, carries a clear violation risk, and is not already in the rules; recurrence across skills is reported as evidence, not used as a gate. It produces candidates and verdicts and never edits rules without the user's approval.

## What is the skill-comply skill?

The skill-comply skill is defined as a behavioral compliance measurement system. It auto-generates scenario prompts at three decreasing strictness levels (supportive, neutral, competing), runs target agents against those scenarios, captures the full tool-call timeline, and classifies whether the expected behavior occurred. The output is a per-skill compliance rate plus a tool-call timeline visualization showing where deviations happened. It exists to answer the question "is this rule actually being followed?" with quantitative evidence rather than the maintainer's subjective impression. Required reading before claiming a rule or skill is effective.

## What is the context-sync skill?

The context-sync skill is defined as a project documentation auditor. It detects role overlap between context files (CLAUDE.md, ADR, README, graph.jsonld), migrates misplaced content to the correct file type, checks freshness against the code (flagging volatile counts and versions for removal), and creates missing documentation files where roles are vacant. README findings are only flagged and handed to readme-writer, not edited. The skill enforces the Maintain phase of AKC: every documentation file should serve exactly one of the four canonical roles — Context, Architecture, Decisions, or External.

## What is the llms-txt-writer skill?

The llms-txt-writer skill is defined as an AI-facing document writer covering both Answer.AI's llms.txt standard and GEO/AEO static analysis. It produces three artifacts: `llms.txt` (a navigator file modeled on robots.txt for AI), `llms-full.txt` (a self-contained reference around 20 KB), and standalone FAQ or glossary pages. The companion script `geo_check.py` runs five GEO-SFE checks: ski-ramp score, chunk self-containment, question-form heading rate, entity density, and definitional expression density. The skill is explicitly not for human-facing READMEs or articles.

## What are the four Contemplative AI axioms used here?

The four Contemplative AI axioms are defined as Emptiness, Non-Duality, Mindfulness, and Boundless Care, taken verbatim from Appendix C of Laukkonen et al. (2025) "Contemplative Artificial Intelligence" (arXiv:2504.15125). Emptiness instructs the agent to hold all directives as contextually sensitive guidelines rather than fixed imperatives. Non-Duality removes rigid self/other separation in decision-making. Mindfulness mandates continuous introspective awareness and self-correction. Boundless Care prioritizes alleviation of suffering as the foundational interpretive criterion. All four are loaded as a single rule file `rules/common/contemplative-axioms.md` and apply to every Claude Code session.

## What is the planning rule's Phase 0 external research mandate?

Phase 0 external research is defined as the step, required for `feat` tasks in the implementation-chain matrix, that runs the search-first skill before an implementation plan introduces a new feature, a new dependency, or a custom utility that may already exist. The skill returns a report (scope searched, found, still unknown) and the main loop decides from it; there is no verdict vocabulary. When the report contains an existing solution that changes the implementation approach, the chain stops and the plan is redone. Bug fixes, refactors, chores, and prototypes skip this step.

## How do I install claude-harness components?

Installation has two paths. The full install runs `git clone https://github.com/shimo4228/claude-harness.git ~/.claude-harness` and copies all skills, agents, and rules into `~/.claude/skills/`, `~/.claude/agents/`, and `~/.claude/rules/common/` respectively. The cherry-pick path copies a single directory — for example, `cp -r ~/.claude-harness/skills/search-first ~/.claude/skills/`. After installation, restart Claude Code (the `claude` CLI binary) so the rules layer reloads. For each skill that ships a `pyproject.toml` (`ls ~/.claude-harness/skills/*/pyproject.toml` lists them), run `uv sync` or `pip install -e .` inside its directory; most need Python 3.11+. Every rule copied into `rules/common/` loads in every session, including the author's personal ones (practitioner-identity, contemplative-axioms), so leave out the rules you do not want. Some skills call outside services when run (for example Hugging Face, Slack, TypeSafe Jev) and need that service's credentials. Hooks follow a third path: they must be copied under `~/.claude/hooks/` and `~/.claude/scripts/hooks/` — the verify hook resolves its approval ledger at a hardcoded `$HOME/.claude` path and fails open elsewhere — and then wired into `settings.json` by hand, as described in `docs/hooks.md`.

## Why are ECC-derived components excluded from this repository?

ECC-derived components are excluded because the repo's purpose is publishing shimo4228's own work, not redistributing third-party assets. ECC (Everything Claude Code) is a separate Claude Code plugin maintained elsewhere; copies tagged `origin: ECC` or `origin: ECC-customized` would create MIT license attribution complications and would dilute the signal of "what shimo4228 actually built." Auto-extracted skills (`origin: auto-extracted`) generated by the learn-eval skill in `~/.claude/skills/learned/` are also excluded — they are session-specific learnings that have not yet passed maintainer curation. The aggregation script filters strictly on `origin: shimo4228` per the maintainer's origin tracking policy documented in `rules/common/skills.md`. Valid origin values are `shimo4228`, `ECC`, `{org/repo}`, `community`, `auto-extracted`, and `{origin}-customized` (e.g. `ECC-customized`).