CLAUDE.md · git:20261019.df0df06 · 2026-10-19 · sha256 4551d0dc915cc3e4
CLAUDE.md git:20261019.df0df06A
Immutable. This exact content never changes and is served at /api/v1/blob/4551d0dc915cc3e4.
# hiway-kit
> Universal Claude Code toolkit — agents and skills for software development.
> Claude Code is the full-feature baseline; other harnesses get the partial support in README's capability table.
## Who this is for (design north-star)
This is a **published plugin installed into other people's projects**, not a tool for this
repo alone. Every design decision is judged by: **does this work in a consumer's
environment** — where the plugin's files live in the plugin cache (not the project cwd),
where MCP servers may be absent or different, where hooks run on every session? A change
that only works in this repo is a defect. (Concrete gate in the Contributing checklist.)
**Interoperability is a first-class goal**: the kit must compose cleanly with other
plugins (e.g., other workflow/methodology plugins) and with whatever MCP servers the user has (memory MCPs,
search MCPs, private/company servers). Three rules: never *assume* a specific plugin/MCP
is present; never *conflict* with one that is; *leverage* generically when available
(e.g., recall-before-plan / remember-after-done if memory-style tools exist — fail-open
otherwise). Guidance lives in skills, never in agent `tools:` allowlists.
## Installation
```bash
# Anthropic 디렉토리 — Claude Code 내장 마켓플레이스(추가 불필요). 아래 직접 경로와 **둘 중 하나만**
/plugin install hiway-kit@anthropic-plugin-directory
# 직접 마켓플레이스 — main HEAD 즉시 반영
/plugin marketplace add This-HW/hiway-kit
/plugin install hiway-kit@hiway-kit
# Full (+ pre-commit) — setup.sh installs the DIRECT path; uninstall the directory one first
git clone https://github.com/This-HW/hiway-kit && cd hiway-kit && ./setup.sh
```
> 디렉토리 경로는 **로그인 없는 빈 설정에서 실측**한 뒤 적었다(2026-10-05) — 확인 전 명령을 적는 것은 "약속 ≠ 실물" 결함이다.
## Structure
```
plugins/
└── common/ — Core agents (15) + skills (15) + rules (12) + hooks
```
`plugins/common/` contains:
- `.claude-plugin/plugin.json` — plugin manifest
- `agents/` — agent `.md` files
- `skills/` — skill `.md` files
- `hooks/` — Python hook scripts (common only)
- `tools/` — Python tools skills call (not hooks — see Hooks)
- `rules/` — governance rules (common only)
- `assets/icon.png` — plugin icon (Codex manifest `interface.logo`·`composerIcon`; directory listings)
- `.codex-plugin/plugin.json`, `plugin.json`, `.cursor-plugin/plugin.json` — **생성물**. Codex·Antigravity·Cursor 타겟 매니페스트로,
`.claude-plugin/plugin.json` 을 SSOT 삼아 `scripts/build-targets.py` 가 만든다. 손으로 고치지 말 것
(`verify-done.sh` §14가 드리프트를 exit 1로 잡는다). 정책은 레포 루트 `packaging/targets.json`
## Key Skills
| Skill | Command | Description |
| ------------------------ | --------------------------- | ----------------------------------------------- |
| plan-task | `/plan-task` | Structured task planning |
| auto-dev | `/auto-dev` | Automated development pipeline |
| web-research | `/web-research` | Multi-source research (MCP if installed, else built-in) |
| review | `/review` | Code review: ruff + review-code + security-scan |
| multi-perspective-review | `/multi-perspective-review` | 3-Round Deliberation with 10 perspectives |
| debug | `/debug` | 4-Phase debug pipeline |
| test | `/test` | Run tests and auto-fix failures |
| agent-creator | `/agent-creator` | Create a **project/user** agent (`.claude/agents/`) — not kit agents (see Adding a New Agent) |
| brainstorming | `/brainstorming` | Design a Large feature before plan-task |
| using-hiway-kit | (injected, manual-only) | Workflow chain by task size |
| control-loop | `/control-loop` | Multi-session control discipline — investigate/decide/dispatch/verify/merge |
| child-session | (loaded, not invoked) | Discipline a dispatched worker session loads at start |
| native-watch | `/native-watch` | **Repo-only** (`.claude/skills/`) — audit native-feature absorption vs the kit (SSOT: docs/native-absorption.md) |
| self-improve | `/self-improve` | **Repo-only** (`.claude/skills/`) — propose agent/skill/rule improvements from ledger+evals (proposal-only, gated) |
| harness-export | `/harness-export` | Export host-neutral rules to AGENTS.md + GEMINI.md for hosts without hooks (drift-gated) |
| eval-forge | `/eval-forge` | **Repo-only** (`.claude/skills/`) — forge an eval scenario from an observed defect — generated + self-validated |
| skill-forge | `/skill-forge` | Distill a solved hard problem into a reusable skill draft (proposal-only) |
| cross-engine-review | `/cross-engine-review` | Evidence-backed consensus between sessions on **different engines** (Claude ↔ Codex ↔ …) |
## Agent Architecture
### 2-Tier Model
```
Tier 1: plugins/common/ — All projects (15 agents)
Tier 2: project-local/ — Project-specific (user-added)
```
### Agent Frontmatter
Every agent is a `.md` file with YAML frontmatter:
```yaml
---
name: agent-name # kebab-case, matches filename
description: | # Korean + English trigger conditions
MUST USE when: "keywords"
OUTPUT: result format
model: sonnet # opus | sonnet | haiku
effort: medium # low | medium | high | max
maxTurns: 20 # value is owned by each agent's frontmatter
isolation: worktree # optional: file-modifying agents only
tools:
- Read
- Edit
- Bash
- ExitWorktree # required with isolation: worktree
disallowedTools:
- Task # regular agents cannot spawn sub-agents
---
```
### Model Selection
| Model | Use case | Examples |
| ---------- | -------------------------- | ------------------------------------- |
| **Opus** | Strategy, analysis, review | clarify-requirements, review-code |
| **Sonnet** | Code implementation, fixes | implement-code, fix-bugs, write-tests |
| **Haiku** | Quick checks | verify-code, git-workflow |
### isolation: worktree
Apply to agents that **modify files** — prevents filesystem conflicts:
- ✅ implement-code, fix-bugs, write-tests, sync-docs
- ❌ review-code, plan-implementation, define-business-logic, design-user-journey (read-only — they return analysis, the caller writes)
Merge-back protocol (exit conditions, sequential merge, conflict escalation) is
governed by `plugins/common/rules/parallel-worktree.md`.
### Delegation Signal — 폐기됨 (2026-08-27)
에이전트 출력 끝에 붙던 `---DELEGATION_SIGNAL---` 블록은 **폐기됐다.** 파싱하는 결정론적
코드가 어디에도 없었고(유일한 소비 지점이 «신호를 스캔해 다음 에이전트를 호출하라»는
자연어 지시였다), 오케스트레이션은 이미 스킬 주도 플랫 위임으로 넘어가 있었다.
**비결정적 보조 경로는 없는 것보다 나쁘다**는 판정이다.
산문의 `DELEGATE_TO: X` 같은 **에스컬레이션 의도 서술**은 기계 계약이 아니므로 유지한다.
폐기 경위·근거·걷어낸 범위(에이전트 33종·스킬 4종·주입 규칙 2종·게이트 §12·eval 체크 타입)는
`docs/architecture/delegation-signal-retirement.md` 가 소유한다 — **§12 번호는 재사용하지
않고 비워 둔다**(스펙·CHANGELOG 가 섹션 번호로 게이트를 참조한다).
## Development Conventions
### Editing an agent/skill does NOT affect the current session
Agents and skills are loaded from the **installed plugin cache**
(`~/.claude/plugins/cache/<marketplace>/hiway-kit/<version>[-<sha>]/`), not from this
repo's working tree. So editing `plugins/common/agents/*.md` and immediately dispatching
that agent runs the **old** definition — the change is invisible until the version is
bumped, pushed, and the plugin updated.
This bit us in 2.14.0 development: `review-code`'s output contract was buried 496 lines
from the end of its definition, its reports came back empty twice, and the working-tree
fix could not be verified in the same session. Two consequences:
- **Never conclude "the definition change worked" from in-session behavior.** Verify by
reading the file, or by a machine check (`verify-done.sh` § checks against the working
tree; `§12`, the check this incident motivated, is retired — see Delegation Signal above).
- To actually exercise a definition change, bump the version and reinstall
(`/plugin marketplace update` → `/plugin install`), or point a scratch install at the
working tree.
Hooks and `scripts/` are different — hooks run from `${CLAUDE_PLUGIN_ROOT}` (also the
cache), but `scripts/`, `evals/` and `tests/` (hook tests live in `tests/hooks/` since v5.0.0 — they are not shipped) are repo-local and take effect immediately.
### Adding a New Agent
1. Create `plugins/common/agents/{name}.md` — flat only (Claude Code hides subfolder agents;
`check_doc_counts.py` fails on any subdirectory)
2. Add required frontmatter (see template above)
3. Write Korean description with `MUST USE when:` trigger conditions
4. No manifest edit needed — agents are auto-discovered from the directory
(plugin.json has no agent/skill registry)
5. Add it to the roster in `plugins/common/rules/agent-system.md` (CHECKSUMS + mirror), classify it
in `evals/policy.json` `tiers`, and add the scenario + baseline its tier requires
(`scripts/check_eval_coverage.py` is the gate). `/agent-creator` is for consumer agents, not this
### Adding a New Skill
1. Create `plugins/common/skills/{name}/SKILL.md`
2. Optionally add `README.md` in the same directory
3. No manifest edit needed — skills are auto-discovered from the directory
### Naming Conventions
- Agents: `verb-noun.md` (fix-bugs, implement-code, review-code)
- Skills: `noun-action` (web-research, plan-task, auto-dev)
- All agent names must be kebab-case and match the `name:` frontmatter field
### Sub-agent Rules
- Regular agents: `disallowedTools: [Task]` — cannot spawn sub-agents
- Meta agent (`devils-advocate` — the only one since v5.0.0; the multi-perspective-review roles it used to share with 4 others are now skill steps): `disallowedTools: [Bash]`
- Skills (auto-dev, etc.) drive delegation; leaf agents stay flat — a deliberate choice: native
subagents may nest up to three levels by default.
### Orchestration Model — Scale-Appropriate Primitives
오케스트레이션은 전통이 아니라 **스케일별로 올바른 프리미티브**를 쓴다. leaf 에이전트가
Task를 갖지 않는 이유는 "main만 조율" 도그마가 아니라, 우리 스케일에서 에이전트 중첩이
성능 이득 없이 예측불가능성·디버깅 부채만 더하기 때문이다.
킷이 **소비자에게** 제공하는 모델이다(이 레포 자체의 협업 수단은 `coordination.md`).
| 병렬 청크 수(파일 수 아님) | 오케스트레이션 |
| --------- | -------------- |
| 수 개 | 스킬 주도 플랫 위임 (main이 Agent 병렬 dispatch → 결과 수집). 예측가능·검증된 경로 |
| 10~100+ | 네이티브 workflow(`ultracode` 등)를 **사용자가 opt-in** — auto-dev는 청크로 분할해 안내 |
> 워크플로는 사용자 opt-in(키워드·이름 호출·allow 규칙)이 있어야 돈다 — 스킬이 스스로 켜지 않는다
> (판정·근거: `docs/native-absorption.md`). 작업 크기(Small/Medium/Large) 기준은 `plan-task` 의 `elicitation.md §6`.
### Phase Gate Pattern
```
Phase 1 (Planning) → P0 ambiguity = 0 (criteria: rules/agent-system.md Phase Gate)
Phase 2 (Development) → implement based on Phase 1 artifacts
Phase 3 (Validation) → spec compliance, then review + security scan (auto-dev T-*)
```
## Hooks
Located in `plugins/common/hooks/` (except `session-check.py`, which lives in
`plugins/common/setup/`):
- `session-check.py` — `SessionStart` environment/setup check (runs before
`session-start.py`; registered from `setup/`). **Writes nothing into the consumer's
repo** (until v5.0.0 it silently installed `setup/pre-commit` in plugin-only mode —
installation is now `setup.sh` only). Warnings go out as `systemMessage` (a
SessionStart hook's stderr is seen by no one) and only for real defects: python below the 3.9
floor, missing global setup (setup.sh users only), a project `.claude/{agents,skills}` entry whose
**name collides** with a plugin one (project-local agents alone never warn), and a **stale venv**
(`.venv`/`venv` console-script shebangs still pointing at the project's old
path after a directory move/copy — `bin/python` keeps working while every
script dies with `bad interpreter`, or silently runs the old site-packages)
- `session-start.py` — injects rules + active plan status (`docs/plans/*/plan.md`, status≠done) at `SessionStart`
- `protect-sensitive.py` — `PreToolUse` on Edit/Write/MultiEdit/NotebookEdit/Read:
blocks access to **sensitive file paths** (`.env`, keys, `.pem`) by path. env
templates (`.env.example`/`.sample`/`.template`/`.dist`) are exempt; writes to
them get a best-effort high-confidence secret-format content scan. It
does **not** otherwise scan file *content* or intercept `Bash`/`git commit` —
secret scanning is gitleaks at push time — CI, and `verify-done.sh` §24 locally over
unpushed commits. `setup/pre-commit` does **not** run gitleaks.
- `auto-format.py` — auto-formats code after edits (`PostToolUse`): ruff for Python (≤2 runs);
prettier/eslint **only when the project has them in `node_modules/.bin`** — never `npx`
(it looked up the registry on every Markdown edit). Whole hook fits a 25 s budget (< 30 s timeout)
- `stop-validator.py` — on `Stop`, lints edited `.py` (ruff) and runs pytest on
the test files this session edited (never the full suite — that's CI/`/test`'s
job); on failure emits native `{"decision":"block","reason":...}` so Claude
continues and auto-fixes. Timeouts are non-blocking (`CLAUDE_STOP_TEST_TIMEOUT`).
If git reports no modified `.py`, it returns **before reading the transcript**; ruff runs
only on files auto-format could not see (e.g. written via Bash). Everything fits 110 s (< 120 s)
- Stop state reuses `$TMPDIR/claude-{uid}` only when it is an owned, non-symlink
directory with mode `0700`. Unsafe or unavailable stable state uses a private
temporary directory for that process; it never trusts counters from the shared
temporary root. This fallback loses cross-process marker/retry reuse.
- `utils.py` — shared utilities
### 스킬 도구는 `tools/` 에 둔다 (v5.2.0)
OpenAI 디렉토리 포털은 `hooks/` 가 **있기만 해도** 거부해 제출본이 그것을 통째로 뺀다 —
스킬이 부르는 도구(checklist·feedback_ledger·export_harness)는 `tools/` 에 둔다. 3.9 floor·fail-open 은 훅과 같다.
### git 훅은 배포되지만 자동으로 켜지지 않는다
`plugins/common/setup/` 에는 세션 훅이 아닌 **git 훅** 정본도 있다 — `pre-commit`
(ruff·JSON·frontmatter·비공개 이름 검사 — gitleaks 는 없다)과 `git-hooks/reference-transaction`(레퍼런스 변경 가드). `setup.sh`
가 `pre-commit` 을 설치하고, `reference-transaction` 은 **opt-in** 이라 켜지 않은 것이
결함이 아니다.
**"배포됐다"와 "설치돼서 실제로 돈다"는 다른 상태다.** 정본을 고쳐도 각자의
`.git/hooks/` 에 있는 사본은 그대로이므로, 고친 사람만 그 훅이 도는 줄 안다. 이
결함 클래스를 실제로 밟은 뒤 `verify-done.sh` §21(`scripts/check_installed_hooks.py`)이
설치된 사본과 레포 정본을 대조한다 — 미설치(opt-in)와 낡은 설치를 구분해서 보고한다.
Hooks are defined in `plugins/common/hooks/hooks.json` using the **exec form**
(`command` + `args[]`) so `${CLAUDE_PLUGIN_ROOT}` paths need no shell quoting.
**Python floor: 3.9** — hooks run on the *consumer's* `python3`, and macOS still
ships 3.9.x. So hook sources must stay 3.9-loadable: use
`from __future__ import annotations` and keep 3.10-only syntax out of anything
evaluated at import time. This is enforced twice, not by convention: ruff's `FA`
rules (statically, via root `ruff.toml`) and the `python39-compat` CI job (it
actually loads every hook under 3.9). Four hooks were silently dead on 3.9 until
2.12.1 — that is the failure this guards against.
> Subagent lifecycle tracking is delegated to native OpenTelemetry
> (`agent_id` / `parent_agent_id` spans, `/usage` breakdown) — the kit no longer
> ships a custom `agent-lifecycle.py` (removed in 2.6.0).
### 설정값으로 경로를 만들면 반드시 봉쇄한다 (2026-08-27 확정)
@docs/conventions/path-containment.md
## Security
- `gitleaks` scans **every commit** in each push/PR range, merge side branches included
(config `.gitleaks.toml`, per-finding ignores `.gitleaksignore`, pin `.gitleaks-version`);
`verify-done.sh` §24 runs the same scan on unpushed commits before you push
- Never hardcode secrets, API keys, internal IPs, or project names
- `protect-sensitive.py` runs as a `PreToolUse` hook on Edit/Write/MultiEdit/NotebookEdit/Read — path-based (plus a best-effort content scan only for env-template writes), not commit-based (see Hooks section)
## CI/CD
`.github/workflows/validate.yml` runs on push to `main` (and PRs) and **owns its step list** — read it;
most steps call the same scripts as `verify-done.sh`.
### 드리프트 게이트는 통합하지 않는다
생성물·사본이 SSOT 와 일치하는지 묻는 게이트가 여럿이지만 입력·판정·실패 메시지가 전부 달라
**통합하지 않는다** — 게이트는 읽기 쉬워야 red 가 떴을 때 믿고 고친다. 무엇이 드리프트 게이트인지는
`scripts/verify-done.sh` 가 소유한다(여기 열거하지 않는다). 판정·근거·재검토 경위: `docs/conventions/no-gate-integration.md`.
### Lint is one ruleset, everywhere
@docs/conventions/lint-single-ruleset.md
### Rules have a long-form mirror — and it is checksum-guarded
@docs/conventions/rules-mirror.md
### Shell is linted too
@docs/conventions/shell-lint.md
### 경고는 상시 참이 되면 죽는다
@docs/conventions/warning-signal.md
## Release Checklist
**CRITICAL: Every commit that changes plugin behavior MUST bump the version** — via
`scripts/bump-version.sh <ver>`, never by hand. Plugin cache is keyed by version: same version = users never get the fix.
절차(CHANGELOG·타겟 재생성·`AGENTS.md` 재생성·룰 sha·CHECKSUMS·미러·행동 eval·태그·게이트)의 정본은
`docs/conventions/release-process.md` 다. 배포 채널별 상태는 `docs/marketplace-submission.md` 상단 요약표가 소유한다.
## Contributing
PRs welcome. Checklist:
- [ ] **Consumer-first**: works in an installing user's environment, not just this repo —
no reliance on the project cwd containing plugin files, no assumption a specific MCP
server is installed, hooks fail-open when their assumptions don't hold
- [ ] No `mcp__*` tools in any agent `tools:` allowlist (MCP lives in skills — see
`docs/architecture/rules/mcp-usage.md` §4; absent MCP in an agent allowlist hallucinates, CC #13898)
- [ ] Agent frontmatter has `name`, `description`, `model`, `maxTurns`
- [ ] No forbidden fields: `permissionMode`, `context_cache`, `output_schema`, `next_agents`, inline `hooks`
- [ ] Description includes `MUST USE when:` trigger conditions
- [ ] File-modifying agents have `isolation: worktree`
- [ ] Regular agents have `disallowedTools: [Task]`
- [ ] Skill `description` field is in English
- [ ] Version bumped with `scripts/bump-version.sh` + matching `CHANGELOG.md` entry
(the manifest has **no** agent/skill registry — both are auto-discovered from their
directories; the only thing a new component must touch there is the version)
- [ ] `scripts/verify-done.sh` green locally and CI green
@docs/conventions/coordination.md