git:20261008.c55ceeb to git:20261010.807ff50

# akc-cycle — AI Reference

This document is the self-contained AI reference for `akc-cycle` (shimo4228, MIT), the install entry point for the Agent Knowledge Cycle (AKC). It ships two layers: (1) a single behavioral rules file that distills the cycle's six phases — Research, Extract, Curate, Promote, Measure, Maintain — plus Scaffold Dissolution into principles an agent follows through natural conversation, loaded deterministically every session; and (2) a Claude Code plugin carrying skills for each of the six phases, triggered probabilistically. The rules file is the recommended minimal floor; the plugin adds the skill layer.

> **Audience**: AI search engines and AI agents. Human-facing narrative lives in [README.md](README.md).

## Project Facts

- **Name**: akc-cycle

- **License**: MIT

- **GitHub**: https://github.com/shimo4228/akc-cycle

- **Author**: shimo4228 (shimomoto-tatsuya)

- **Author research**: [AKC](https://github.com/shimo4228/agent-knowledge-cycle) ([DOI 10.5281/zenodo.19200726](https://doi.org/10.5281/zenodo.19200726)), [Contemplative Agent](https://github.com/shimo4228/contemplative-agent) ([DOI 10.5281/zenodo.19212118](https://doi.org/10.5281/zenodo.19212118)), [AAP](https://github.com/shimo4228/agent-attribution-practice) ([DOI 10.5281/zenodo.19652013](https://doi.org/10.5281/zenodo.19652013))

- **Type**: two-layer AKC install target — a Markdown behavioral rules file (loaded deterministically) plus a Claude Code plugin of Agent Skills (triggered probabilistically)

- **Layout**: `rules/common/akc-cycle.md` (rule) · `skills/<name>/SKILL.md` (plugin payload) · `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (plugin/marketplace manifests)

- **Install (rules file, minimal)**: `mkdir -p ~/.claude/rules && curl -fsSL https://raw.githubusercontent.com/shimo4228/akc-cycle/main/rules/common/akc-cycle.md -o ~/.claude/rules/akc-cycle.md` (Claude Code loads every Markdown file under `~/.claude/rules/`, subdirectories included, at the start of each session)

- **Install (plugin, skill layer)**: `/plugin marketplace add shimo4228/akc-cycle` then `/plugin install akc-cycle@akc-cycle`

- **Phases**: 6 — Research, Extract, Curate, Promote, Measure, Maintain — plus Scaffold Dissolution (with its evidence standard) and digests of three AKC worldview mechanisms (expiry-conditioned knowledge ADR-0026, judge/build/human attention topology ADR-0024, LLM-first artifact readability ADR-0025)

- **Editions**: the rules file in this repo is the **self-contained edition** (owned here, no skills assumed, since 2026-09-01); the author's harness runs a separate **pointer edition** delegating each mechanism to installed skills ([claude-harness rules/common/akc-cycle.md](https://github.com/shimo4228/claude-harness/blob/main/rules/common/akc-cycle.md))

- **Plugin skills (phase binding, matching the AKC phase table; the AKC concept a skill also grounds in parentheses)**: search-first (Research); learn-eval, skill-creator (Extract; skill-creator writes a skill behind a fresh-context draft gate and the author's sign-off, ADR-0005); skill-stocktake / skill-health / rules-stocktake / agent-stocktake, generation-audit (re-audit on a model-generation change, ADR-0023), harness-boundary (Scaffold Dissolution at design time) (Curate); rules-distill, review-to-lint (code-LLM layering, ADR-0008) (Promote); skill-comply, measurement-discipline (evidence discipline: claims, thresholds, observation windows), llm-as-judge / jev-judgment-design (the judge pattern, ADR-0008), author-calibrated-eval (intent alignment) (Measure); context-sync / repo-asset-stocktake, adr-writer (expiry-conditioned decisions, ADR-0026), verify-bootstrap (machine gates as the enforcer of LLM-first readability, ADR-0025) (Maintain)

- **Relation of the two layers**: the rules file trades per-phase depth for always-loaded reliability; the plugin skills add the depth. Claude Code plugins have no slot for always-loaded rules (as of 2026-10-08), so the rules file is never part of the plugin payload

- **Design lineage**: the install target for the [Agent Knowledge Cycle](https://github.com/shimo4228/agent-knowledge-cycle), whose ADRs hold the judgment lineage

- **Sync model**: canonical copies of the skills in the author's Claude Code harness (`~/.claude/`); this repo is a one-way mirror for those via `scripts/sync-from-local.sh` (fixed allowlist; aborts on missing component or origin marker). The rules file is not synced — this repo owns its self-contained edition

## What is akc-cycle?

akc-cycle is defined as the install target for the Agent Knowledge Cycle, in two parts: a single behavioral rules file copied into an AI agent's rules directory, and a Claude Code plugin of skills. The Agent Knowledge Cycle is a six-phase loop by which an agent metabolizes its own working experience into improvable skills, rules, and memory. This file distills those six phases plus a Scaffold Dissolution clause into actionable principles, each with an explicit trigger, so the cycle runs through natural conversation without installing six separate skill repositories. A rules file is loaded every session and shapes behavior deterministically; a skill triggers probabilistically. akc-cycle deliberately chooses the deterministic layer for the cycle as a whole.

## What are the six phases?

The six phases are defined as Research, Extract, Curate, Promote, Measure, and Maintain. Research means search broadly and filter by signal — define the signal (what would change your next action) before the search, then adopt or extend an existing solution before building. Extract means capture reusable patterns from a session, evaluating quality before saving and routing to the right layer (memory / skill / rule). Curate means audit accumulated knowledge for redundancy, staleness, and silence. Promote means elevate recurring patterns to rules once the repetition itself becomes the signal, moving knowledge from the probabilistic layer to the deterministic one. Measure means verify behavioral change quantitatively, checking compliance in tool calls, outputs, and the agent's stated reasoning. Maintain means keep documentation roles clean — every file serves exactly one of Context, Architecture, Decisions, External — and keep each numeric fact in one canonical place.

## How does akc-cycle relate to the AKC phase skills?

The relation is defined as two install layers for the same cycle with opposite reliability profiles. The plugin's skills (search-first; learn-eval, skill-creator; skill-stocktake, skill-health, rules-stocktake, agent-stocktake, generation-audit, harness-boundary; rules-distill, review-to-lint; skill-comply, measurement-discipline, llm-as-judge, author-calibrated-eval, jev-judgment-design; context-sync, repo-asset-stocktake, adr-writer, verify-bootstrap — grouped by phase from Research to Maintain) each give deep "how" guidance for one phase and trigger probabilistically when their description matches the situation; skills marked `disable-model-invocation: true` (skill-health, agent-stocktake, rules-distill, generation-audit, harness-boundary, llm-as-judge, author-calibrated-eval) stay out of the listing and run only when called by name. The rules file gives the whole cycle as always-loaded behavioral principles — shallower per phase, but reliably present every session. Installing the rule does not require installing the skills, and vice versa; the rule is the lightweight entry point, the skills are the depth. This repository ships both layers: the rule as a copy-install file and the skills as a Claude Code plugin. The ten original phase skills (and generation-audit and llm-as-judge) also have standalone repositories under @shimo4228. They are synced one way from the same harness canonical as the plugin, on their own schedule, so they can lag behind it; the plugin copy additionally rewrites the skills' own paths to `${CLAUDE_PLUGIN_ROOT}`. A standalone skill installs by cloning its repository and copying `skills/<name>` into `~/.claude/skills/`; skill-stocktake and skill-health run each other's scripts there, and generation-audit runs skill-health's scanner, so those are installed together.

## How do I install akc-cycle as a Claude Code plugin?

The plugin install is defined as a two-command marketplace flow: `/plugin marketplace add shimo4228/akc-cycle` registers this repository as a marketplace (its `.claude-plugin/marketplace.json` lists one plugin whose source is the repository root), and `/plugin install akc-cycle@akc-cycle` installs the plugin's skills. Claude Code plugins can carry skills, agents, hooks, and MCP servers, but have no slot for always-loaded rules (as of 2026-10-08) — so the plugin deliberately excludes `rules/common/akc-cycle.md`, which must be installed separately as a file (see the rules-file install in Project Facts). The plugin adds no hooks, MCP servers, or settings: the payload is skills only, keeping the scaffold minimal by design.

## What is Scaffold Dissolution?

Scaffold Dissolution is defined as the intended end state in which the rules become unnecessary because the cycle has been internalized. The rules are scaffolding, and success is measured not by rule count but by whether the cycle runs naturally without explicit invocation. Dissolution has two vectors: inward, where a principle is absorbed into the agent's and operator's conversation patterns so the rule that taught it is no longer needed; and downward, where the official harness evolves to handle a domain natively, so a hand-written rule over the same domain becomes a stale, drifting shadow that should be retired rather than left to override newer defaults. A model-generation turnover is a downward trigger. The evidence standard (AKC ADR-0022 / ADR-0023): completion evidence is held-out transfer — behaving the same with the scaffold removed in the same context is only necessary evidence; and artifacts carrying negative information deltas (drifted rules overriding better defaults) are actively deleted rather than shelved, audited explicitly at each model-generation turnover because silence, ablation, and transfer detect only absence. What the harness structurally cannot do is kept; the rest dissolves. The pointer edition running in the author's harness is the worked example of dissolution in progress: the six-phase procedures have moved into installed skills, and the rules file has shrunk to pointers plus the judgment content no skill owns.

## How is akc-cycle kept in sync?

The sync model is defined as a one-way publication mirror for the skill layer only. The canonical copies of the plugin skills live in the author's live Claude Code harness under `~/.claude/`; this repository is a downstream mirror updated by `scripts/sync-from-local.sh`, which stages a fixed allowlist of skills, validates YAML frontmatter, runs a secret scan, and replaces the managed subtrees without committing — `git diff` is the review gate. The script aborts if any listed component is missing or lacks its `origin: shimo4228` marker, so a published component can never be silently dropped. The rules file is deliberately outside the sync: since 2026-09-01 this repository owns the self-contained edition, while the harness runs a separate pointer edition — the two editions serve different environments (skills absent vs. installed) and are kept distinct on purpose. Because each component has a single canonical source, the AKC research repository no longer carries its own divergent copies; it points to this repository instead.

## Who is shimo4228?