git:20261005.7f0fd12 to git:20261005.62d3e8e

# hiway-kit

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

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` — **생성물**. Codex·Antigravity 타겟 매니페스트로,

`.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 |

| 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 |

| 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

tools:

- Read

- Edit

- Bash

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---` 블록은 **폐기됐다.** 파싱하는 결정론적

코드가 어디에도 없었고(유일한 소비 지점이 «신호를 스캔해 다음 에이전트를 호출하라»는

자연어 지시였다), 오케스트레이션은 이미 스킬 주도 플랫 위임으로 넘어가 있었다.

**비결정적 보조 경로는 없는 것보다 나쁘다**는 판정이다.

산문의 `DELEGATE_TO: X` 같은 **에스컬레이션 의도 서술**은 기계 계약이 아니므로 유지한다.

폐기 경위·근거·걷어낸 범위(에이전트 33종·스킬 4종·주입 규칙 2종·게이트 §12·eval 체크 타입)는

`docs/architecture/delegation-signal-retirement.md` 가 소유한다 — **§12 번호는 재사용하지

## Development Conventions

### Editing an agent/skill does NOT affect the current session

Agents and skills are loaded from the **installed plugin cache**

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

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

### 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]`

오케스트레이션은 전통이 아니라 **스케일별로 올바른 프리미티브**를 쓴다. leaf 에이전트가

Task를 갖지 않는 이유는 "main만 조율" 도그마가 아니라, 우리 스케일에서 에이전트 중첩이

성능 이득 없이 예측불가능성·디버깅 부채만 더하기 때문이다.

킷이 **소비자에게** 제공하는 모델이다(이 레포 자체의 협업 수단은 `coordination.md`).

| --------- | -------------- |

### Phase Gate Pattern

```

Phase 2 (Development) → implement based on Phase 1 artifacts

```

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

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

### 설정값으로 경로를 만들면 반드시 봉쇄한다 (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

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

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

(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)

@docs/conventions/coordination.md