claude-harness

# claude-harness

> Public snapshot of the Claude Code harness (skills, agents, rules,
> commit-boundary and session-surface hooks, the harness's own ADRs, and
> its public task-and-proposal ledger `rfcs/`) used day-to-day by
> shimo4228. Skills, agents, and rules are mechanically aggregated from
> `~/.claude/` for assets tagged `origin: shimo4228`, excluding
> ECC-derived material (`origin: ECC` / `ECC-customized`) and
> auto-extracted artifacts. ADRs and rfcs sync wholesale (both are
> self-authored judgement records); hooks come from a
> curated allowlist, since publishing a hook is a judgement about reuse
> outside this machine rather than about who wrote it.
>
> Bundles skills covering research-before-coding, knowledge extraction,
> skill auditing, AI-facing documentation, human-facing writing review,
> JSON-LD knowledge graph design, academic paper writing / review / deposit, AI-native preprint submission,
> JA→EN translation, Wikidata identifier federation, authorship strategy,
> and DOI release; agents for prompt generation, editorial review, and
> academic paper review; rules covering planning, the AKC cycle,
> authorship strategy, and skill origin tracking.
> The first six skills (search-first, learn-eval, skill-stocktake,
> rules-distill, skill-comply, context-sync) are the building blocks of
> the Agent Knowledge Cycle (AKC) and are also published as standalone
> repos.

## Core documentation

- [Full AI Reference](llms-full.txt): self-contained AI-facing reference — Project Facts, Prior Research References, and 18+ Q&A covering AKC, origin tracking, skills vs rules, agent orchestration, contemplative axioms, and Python-implemented skills. Optimized for AI search engine citation (ChatGPT, Perplexity, Gemini). English-only by design.
- [README](README.md): project overview, positioning, install instructions (English, human-facing, canonical)
- [README (Japanese)](README.ja.md): same content in Japanese

## Skills

Each skill defines a workflow that Claude can invoke via slash command (`/<skill-name>`) or naturally trigger from its description.

- [search-first](skills/search-first/SKILL.md): look outside before deciding — searches the live web, registries, and primary sources at decision time and returns a report the caller picks from (scope searched / found / still unknown; judgement as prose backed by facts, no verdict line — ADR-0066)
- [learn-eval](skills/learn-eval/SKILL.md): extracts reusable patterns from sessions, evaluates quality, and decides save destination (memory / skill / rule)
- [skill-stocktake](skills/skill-stocktake/SKILL.md): skill quality audit — inline Glob inventory + single-context holistic evaluation (full / changed modes), Keep/Improve/Update/Retire/Merge verdicts
- [skill-health](skills/skill-health/SKILL.md): structural skill-library debt scan — flags "missing artifacts" (SKILL.md references to scripts, agents, or sibling skills that don't resolve on disk); deterministic, delegates quality / risk / validation to skill-stocktake / security-scan / skill-comply
- [skill-creator](skills/skill-creator/SKILL.md): write or rewrite a skill / agent definition — intent packet, library-wide boundary check, a fresh-context draft gate with a named verdict (Publishable / Fix / Drop, no scoring), author read-through; replaces the upstream anthropics skill-creator in place (ADR-0046)
- [rules-distill](skills/rules-distill/SKILL.md): scans skills to extract cross-cutting principles and promotes them to deterministic rules
- [rules-stocktake](skills/rules-stocktake/SKILL.md): rules quality audit — residency-cost model (every line is a per-session token tax), staleness / substrate-absorption checks, Keep/Improve/Update/Merge/Demote/Dissolve/Retire verdicts; the inverse of rules-distill
- [agent-stocktake](skills/agent-stocktake/SKILL.md): agent-definition quality audit — hybrid cost model (description = per-session residency in the agent listing, body = invocation-time load), suppression-instruction detection with Improve-by-inversion, substrate-absorption checks; third sibling of skill-stocktake and rules-stocktake
- [generation-audit](skills/generation-audit/SKILL.md): model-generation-change audit orchestrator — captures the live runtime layer (system prompt + tool descriptions), classifies mismatches with self-authored assets as conflict / redundancy / drift, judges each with the intent / evidence / freshness / expiry frame, and hands the evidence to the three stocktake skills for verdicts (the concrete procedure for Scaffold Dissolution's model-generation trigger)
- [skill-comply](skills/skill-comply/SKILL.md): measures actual compliance of skills, rules, and agents — generates scenarios at 3 prompt strictness levels and classifies behavioral sequences
- [context-sync](skills/context-sync/SKILL.md): audits and fixes project documentation — detects role overlap between context files (CLAUDE.md, ADR, README, graph.jsonld), checks freshness against code, creates missing docs
- [codex-review](skills/codex-review/SKILL.md): cross-model second opinion from the OpenAI Codex CLI (a different model family), read-only — code review of the current diff folded into the review chain, plus a plan-stage premise challenge of a design packet (refute / missing / alternative, never a design)
- [llms-txt-writer](skills/llms-txt-writer/SKILL.md): writes AI-facing documentation (llms.txt, llms-full.txt, FAQ pages, glossaries) with Answer.AI llms.txt standard compliance and GEO/AEO static analysis (GEO-SFE 5 checks)
- [jsonld-knowledge-graph](skills/jsonld-knowledge-graph/SKILL.md): designs and ships a companion JSON-LD knowledge graph (graph.jsonld) next to llms.txt for projects with stable concept-level structure — encodes domain entities and relationships as schema.org triples for LLM citation
- [measurement-discipline](skills/measurement-discipline/SKILL.md): discipline for measurement-backed claims, thresholds, and guards — one pass is not evidence, gate on observations not the calendar, calibrate guard firing rates (0% and 100% both design bugs), no numeric caps as quality filters, no distribution claims from survivors only
- [repair-discipline](skills/repair-discipline/SKILL.md): discipline for starting a repair — verify against git log and real code before picking up a stale task, sweep all consumers in the same change on schema/storage edits, know a bypass short-circuits every gate, low CPU is not stuck, foreground retries only
- [review-to-lint](skills/review-to-lint/SKILL.md): extracts mechanically decidable checks from an existing reviewer's checklist into a deterministic evidence script, thinning the reviewer to semantic-only judgment
- [collect-context](skills/collect-context/SKILL.md): gathers in-session and external context into source material files for article writing
- [authorship-strategy](skills/authorship-strategy/SKILL.md): 4-layer framework (Authenticity / Attribution diffusion / Idea-vs-scaffold / Tactics) for DOI-registered idea-rescue research repos
- [release-doi](skills/release-doi/SKILL.md): cuts a versioned release of a DOI-registered research repo — Zenodo concept DOI semantics, CHANGELOG / tag / asset packaging
- [adr-writer](skills/adr-writer/SKILL.md): records design decisions as numbered ADRs — directory detection, sequence numbering, index update; the main loop writes the 7-section body from a settled decision packet, then a mechanical evidence script and the adr-reviewer agent check it (ADR-0072)
- [readme-writer](skills/readme-writer/SKILL.md): writes human-facing READMEs — deterministic structural lint plus holistic LLM review without scores
- [hf-sync](skills/hf-sync/SKILL.md): mirrors graph.jsonld-bearing research repos to Hugging Face Datasets — flattens the graph and uploads alongside graph.jsonl
- [spawn-session](skills/spawn-session/SKILL.md): launches a new detached Claude Code Remote Control session inside Herdr, visible in the mobile app session list
- [harness-sync](skills/harness-sync/SKILL.md): one-way export of origin-filtered components from the live harness (~/.claude) into this publication repo — collection, secret scan, subtree replacement
- [wiki-harvest](skills/wiki-harvest/SKILL.md): read-only harvest from an Obsidian LLM wiki (wiki/concept/) into a research repo — extracts only next-action-changing candidates into a ranked, source-cited ledger under the repo's `.notes/`
- [wiki-query](skills/wiki-query/SKILL.md): read-only query over an Obsidian LLM wiki (wiki/concept/) with `[[ ]]` source-cited synthesis
- [repo-asset-stocktake](skills/repo-asset-stocktake/SKILL.md): audits a project repository's non-code assets (tool configs, CI workflows, runbooks) for diminished value — every asset serves a consumer; flags assets whose consumer has vanished, with Keep/Update/Retire/Merge verdicts
- [task-stocktake](skills/task-stocktake/SKILL.md): audits and consolidates a repository's pending-task tracking into its single task ledger — bootstraps the ledger, sweeps stray task lines from handoff and audit files, verifies entries against git log and actual code
- [task-triage](skills/task-triage/SKILL.md): one cycle of the task-triage loop — judge every open ledger task (premise in code, start condition against its 照合先, worth), dispatch the ready ones to fresh build sessions in worktrees, verify their output independently; the human keeps the merge word (ADR-0043)
- [implementation-chain](skills/implementation-chain/SKILL.md): decides the task type (feat / fix / refactor / chore / prototype / writing) and front-loads its agent chain into the plan — Chain Matrix, reviewer routing, early-stop conditions
- [harness-boundary](skills/harness-boundary/SKILL.md): design-time lens for any proposed mechanism (rule / skill / hook / agent / workflow) — which of 6 layers it belongs to, whether the model could own it instead, whether it survives a runtime swap; keep only what outlives the harness
- [public-comment](skills/public-comment/SKILL.md): drafts replies for public technical threads (GitHub discussions, issues, PRs, Hugging Face discussions) — AI-slop tell removal, thread grounding, and a human gate with a Japanese translation before posting
- [llm-as-judge](skills/llm-as-judge/SKILL.md): design pattern for LLM-as-judge evaluators — binary checks as evidence, one named holistic verdict, no score aggregation
- [git-workflow](skills/git-workflow/SKILL.md): permission-friction discipline for running git in this environment — git-to-git chaining is auto-allowed (segments match independently), but cd must never be mixed with git (use git -C; that combination always prompts), commit messages must avoid command substitution, and push needs the sandbox disabled
- [headline-craft](skills/headline-craft/SKILL.md): craft skill for the one line that makes readers open — title / tagline / subtitle / SNS-post candidate generation with concrete techniques, evaluated per traffic channel (search vs feed)
- [growth-astra](skills/growth-astra/SKILL.md): writes and revises the north star of a GitHub follower campaign (`.growth/NORTH_STAR.md`); the escalation target of growth-fable
- [growth-fable](skills/growth-fable/SKILL.md): plans experiments toward that north star, dispatches them to worker sessions, records outcomes in `.growth/EXPERIMENTS.md`

## Agents

Specialized agents in `agents/`, each with its own tool allowlist.

- [prompt-writer](agents/prompt-writer.md): generates concise, focused prompts using a lightweight model (Haiku)
- [readme-judge](agents/readme-judge.md): the single README judge for readme-writer — answers a fixed checklist from the README alone, freezes that verdict, then checks factual claims against the repo (file:line) and returns Publishable / Fix / Rewrite

## Rules

Environment-specific facts, wiring, and traps auto-loaded every session from `rules/common/`. Rules load deterministically; skills fire probabilistically. Procedures live in skills, time-critical checks in hooks, general judgment in the model.

- [agents](rules/common/agents.md): pointer to the agent catalog (the frontmatter of `agents/*.md` is canonical), the rule that review runs in a different agent process from the implementer, and the entry points to the Herdr delegation skills
- [akc-cycle](rules/common/akc-cycle.md): pointer edition of the Agent Knowledge Cycle — maps each mechanism (six phases, judge / build / human loop, LLM-first readability, expiry-conditioned knowledge) to the skill or rule that owns it, states the Scaffold Dissolution criteria, and says how ADRs are treated (dated records, supersede with dated annotations, a two-condition filing bar)
- [debugging](rules/common/debugging.md): rate-limit signal — repeated rate limits during bulk writes to an external platform are a policy signal, not a transient error: stop the burst and report to the human instead of backing off through it
- [planning](rules/common/planning.md): planning wiring — search-first before anything that may already exist, build-tier dispatch as the default for implementing from a judge-tier session, implementation-chain for chain type and reviewer conditions, and the repo's `.claude/verify.sh` as the canonical Verify
- [skills](rules/common/skills.md): origin vocabulary for skills / agents / rules (the canonical table), the `replaces:` lineage field, the imperative wiring to skill-creator before writing or overhauling a skill, and the writing rule — positive form by default, prohibitions only under three stated conditions
- [contemplative-axioms](rules/common/contemplative-axioms.md): Contemplative Constitutional AI clauses from Laukkonen et al. (2025) Appendix C, verbatim — Emptiness, Non-Duality, Mindfulness, Boundless Care
- [task-tracking](rules/common/task-tracking.md): one canonical pending-task ledger per repo in one of two shapes — a single table (`.notes/TASKS.md`) or a public store of one-file-per-task RFCs (`rfcs/`) queried through `claims.py ready`; claim / release for concurrent sessions; review findings are filed only when they break the loop itself, with a producer → sink citation
- [knowledge-staleness](rules/common/knowledge-staleness.md): external LLM-domain knowledge is treated as going stale on a one-week scale — no asserting tooling, specs, or going rates from memory; check at search time, date the evidence as-of, and attach an expiry condition to every recommendation
- [llm-first-code](rules/common/llm-first-code.md): code is optimized for its actual reader — the next LLM session, not humans; preserve verifiability (types, tests, golden files) over readability, enforce quality through machine gates, spend human-readability budget only on READMEs and output text
- [boundary](rules/common/boundary.md): the single home of the harness's boundaries — which operations are handed to the human (publication, billing, external sends, ledger filing, unattended changes to permissions / hooks / rules / ADRs), which risks the agent takes without asking, and when to stop and report (ADR-0069)
- [practitioner-identity](rules/common/practitioner-identity.md): the author's self-definition, verbatim — a practitioner searching for good ideas and means in the AI era, not a researcher; DOIs are a means, and the work is not reframed into existing categories

## Hooks

- [Hook guide](docs/hooks.md): install and operating guide for the published hooks — the five commit-boundary gates plus two session-surface hooks (ledger-etiquette reminder with the `scripts/claims.py` ledger CLI, judge-tier review routing) — per-hook firing conditions, block conditions, bypass environment variables, the copy-pasteable `settings.json` fragments, the content-hash approval model behind the verify gate, what each bats suite pins (and which pinned claims were verified by negative control), and what is deliberately not published
- [secret-scan-precommit.sh](hooks/secret-scan-precommit.sh): PreToolUse hook that scans what a `git commit` command will actually commit (not merely what is staged when the hook fires) for credentials, preferring detect-secrets over a regex fallback
- [verify-precommit.sh](hooks/verify-precommit.sh): PreToolUse hook that runs the repo's own `.claude/verify.sh --staged` and reads only its exit code — the harness knows no languages and no tools, so it cannot go stale as tooling turns over
- [bandit-precommit.sh](hooks/bandit-precommit.sh): PreToolUse hook running bandit at MEDIUM severity + MEDIUM confidence over the staged (index) content of `.py` files; stands down if the repo owns a `.claude/verify.sh`
- [ruff-format-precommit.sh](hooks/ruff-format-precommit.sh): PreToolUse hook running `ruff format --check` over staged `.py` content — checks only, never rewrites, because per-edit auto-formatting raced with in-progress edits
- [review-chain-notice.sh](hooks/review-chain-notice.sh): advisory PreToolUse hook that asks whether review and verify ran before commit / revert / merge
- [_git-target-common.sh](hooks/_git-target-common.sh): shared extractor for which repositories a command will commit to — drops backslash escapes and quoted spans before segment parsing so a commit message cannot redirect the scan, and returns every matching repo rather than one, since a single answer leaves one half of a compound commit unexamined
- [verify_allow.py](scripts/hooks/verify_allow.py): direnv-style approval ledger — only a human-approved content hash of a repo's gate is executed, and the checked bytes are the executed bytes

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

- [ADR index](docs/adr/README.md): dated Architecture Decision Records for the harness itself — why each skill, agent, and rule was adopted, retired, or reversed, including superseded decisions. The audit trail that makes the harness's evolution (and its value layer) inspectable rather than merely declared. Written in Japanese; each follows a fixed template (Status / Date / Context / Decision / Review-when / Alternatives Considered / Consequences — `Review-when` holds the expiry conditions and is required from ADR-0044 on; an ADR is a dated hypothesis, not a permanent constraint)
- [RFC ledger](rfcs/README.md): the harness's public task-and-proposal ledger (ADR-0049) — one entry per proposal or work item in Rust-RFC-template form, state in the frontmatter in standard vocabulary (draft / accepted / in_progress / blocked / done / resolved / rejected / withdrawn / obsoleted — ADR-0050), a prose `## Status` section in the IETF "Status of This Memo" lineage, and a `## Next action` tracking section; terminal entries are left in place so rejected proposals stay readable with their reasons. The operator-scale counterpart of the AI-native SDLC playbook's "intent home"; read with `scripts/claims.py ready`

## Related repositories

- [agent-knowledge-cycle](https://github.com/shimo4228/agent-knowledge-cycle): AKC concept and DOI release on Zenodo (10.5281/zenodo.19200726) — the framework that the first six skills here implement
- [contemplative-agent-rules](https://github.com/shimo4228/contemplative-agent-rules): rule-only implementation of the four Contemplative AI axioms with adapters for Cursor, Copilot, and the Iterated Prisoner's Dilemma benchmark
- [contemplative-agent](https://github.com/shimo4228/contemplative-agent): autonomous agent built on the AKC + Contemplative AI foundations — reference application of these patterns in a long-running runtime
- standalone skill repos: independent published versions of each AKC skill (search-first, learn-eval, skill-stocktake, rules-distill, skill-comply, context-sync) and design-pattern skills (when-code-when-llm, signal-first-research, code-and-llm-collaboration, llm-agent-security-principles), plus rules-stocktake and generation-audit