claude-harness

# 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/`. 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 manually-synced artifact)
- **Components**: skills, agents, rules, commit-boundary hooks, and the harness's own ADRs (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 sync wholesale and hooks come from a curated allowlist
- **Hooks directory**: `hooks/` — five PreToolUse hooks at the `git commit` boundary (secret scan, repo-owned gate runner, bandit, `ruff format --check`, review reminder) plus shared parts; wired manually into `settings.json`, install guide at `docs/hooks.md`
- **Skills directory**: `skills/` — covers research-before-coding, knowledge extraction, skill auditing, AI-facing documentation, JSON-LD knowledge graph design, human-facing writing review, authorship strategy, and DOI release
- **Agents directory**: `agents/` — prompt generation (prompt-writer), README review (readme-judge), and ADR review (adr-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, knowledge staleness, LLM-first code, the author's practitioner identity, and the Contemplative Constitutional AI clauses
- **Skills with Python implementations**: llms-txt-writer, skill-comply, rules-distill, skill-stocktake, skill-health
- **Python build**: uv (or pip install -e .), Python 3.10+
- **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.19200727
- **Slash command convention**: `/<skill-name>` requires `user-invocable: true` in skill frontmatter
- **Default invocation model**: Opus 4.7 (1M context) per global CLAUDE.md
- **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 DOI [10.5281/zenodo.19200727](https://doi.org/10.5281/zenodo.19200727) | 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 | Aggarwal, P., et al. (2024). *GEO: Generative Engine Optimization*. arXiv:2403.10844 | 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, commit-boundary hooks, and the harness's own Architecture Decision Records (ADRs), mechanically aggregated from `~/.claude/` (skill, agent, and rule files are filtered by the `origin: shimo4228` tag; the ADR directory is synced whole, as ADRs 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 auditing, AI-facing documentation (including JSON-LD knowledge graph design), human-facing writing review, authorship strategy for DOI-registered research repos, and DOI release management. 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 manual sync, not a primary working tree. Bug fixes and new patterns flow from `~/.claude/` outward into the repo when shimo4228 publishes a snapshot. 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. If sync frequency grows, a Bash collection script under `scripts/` will automate the export from `~/.claude/`.

## 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).

## 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. Two shared parts ship with them: `_git-target-common.sh`, which works out which repository a command targets, and `scripts/hooks/verify_allow.py`, a direnv-style approval ledger. 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 five hooks carry bats tests, plus the shared extractor, 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. The publication decision is recorded in ADR-0038.

## 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), `ECC-customized` (ECC derivative with maintainer modifications), `auto-extracted` (generated by the learn-eval skill), or `{org/repo}` (imported from a specific external repository). Files use YAML frontmatter when available and HTML comments otherwise. This repository contains only files tagged `origin: shimo4228`; ECC and auto-extracted material are excluded by design.

## 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 (deprecated 2026-04-07 per the global CLAUDE.md); skill definitions live exclusively in `skills/<name>/SKILL.md` or `skills/<name>.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. The save destination depends on quality and scope: short observations go to `MEMORY.md`, repeatable workflows become new skills under `~/.claude/skills/learned/` with `origin: auto-extracted`, and cross-cutting principles get queued for promotion to rules via the rules-distill skill. 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 enumerates skills with Glob and reads every skill into one context for a single-context holistic evaluation — no scan scripts and no subagent batching, which makes cross-skill overlap detection accurate. 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). 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 scans across skills and conversation memory to find guidance that appears in three or more places, then extracts the cross-cutting principle as a single concise rule with a clear trigger condition. After promotion, the original occurrences in skills can be removed or simplified to point at the new rule. This compresses repeated advice into a deterministic auto-loaded rule that fires every session, rather than a probabilistic skill that fires only when the description matches.

## 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 strictness levels (gentle, neutral, adversarial), 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 numeric claims (file counts, test counts, version numbers) against the live codebase, and creates missing documentation files where roles are vacant. 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. Run after major refactoring or when context files exceed roughly 200 lines.

## 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 the five Python-implemented skills (llms-txt-writer, skill-comply, rules-distill, skill-stocktake, skill-health), run `uv sync` or `pip install -e .` inside each skill directory. Python 3.10+ is required. 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`, `ECC-customized`, `community`, `auto-extracted`, and `skill-create`.