rule-architect

Files (37)

• marketplace.json · .claude-plugin/
• plugin.json · .claude-plugin/
• test.yml · .github/workflows/
• .gitignore
• LICENSE
• README.md
• SKILL.md
• README.md · archive/
• design-2026-07-15.md · archive/
• test-log-2026-07-15.md · archive/
• rule-architect.md · commands/
• 0001-contract-enforcement.md · docs/adr/
• 0002-runtime-neutral-rule-entry.md · docs/adr/
• 0003-update-migrates-legacy-entry.md · docs/adr/
• 0004-close-the-evidence-loop.md · docs/adr/
• verify_rules.cpython-312.pyc · scripts/__pycache__/
• decisions.py · scripts/
• harvest.py · scripts/
• hookgen.py · scripts/
• manifest.py · scripts/
• quiz.py · scripts/
• rule_guard.py · scripts/
• scan.py · scripts/
• verify_rules.py · scripts/
• UNITTEST_20260827_runtime_neutral_rules.md · test/
• AGENTS.md · tests/fixtures/good/
• AI_RULES.md · tests/fixtures/good/
• CLAUDE.md · tests/fixtures/good/
• Dockerfile · tests/fixtures/good/
• ARCHITECTURE.md · tests/fixtures/good/docs/
• CODING_RULES.md · tests/fixtures/good/docs/
• PITFALLS.md · tests/fixtures/good/docs/
• run.sh · tests/fixtures/good/scripts/
• config.py · tests/fixtures/good/src/
• db.py · tests/fixtures/good/src/
• test_demo.py · tests/fixtures/good/tests/
• test_rules.py · tests/

SKILL.md (first lines)

# rule-architect

Generate a v2 runtime-neutral rule set: one slim `AI_RULES.md` index + on-demand `docs/ai-rules/*.md` rule files. Runtime-specific entry files both resolve to the same neutral index.

## Output Language

Generated rule files follow the project, not this document:

1. Existing `AI_RULES.md` / legacy rule index / `docs/ai-rules/*.md` (or v1 `docs/*.md`) / `README` in the project → match their language.
2. No existing docs → match the language the user is writing in.
3. Still ambiguous → English.

Apply one language consistently across `AI_RULES.md`, portable entry pointers, and every `docs/ai-rules/*.md` in the same run —
a half-English, half-Korean rule set is a defect. Structural tokens stay fixed regardless of language:
`MUST` / `NEVER` / `PREFER`, `why:`, the ❌/✅ markers, UPPERCASE file names, and the
`<!-- generated by rule-architect -->` marker. Report to the user in their language.

Core principle: **rules record only what code cannot tell you.** An agent can run `ls` and read `requirements.txt` by itself; it cannot guess that a model must be registered in two places, or that env must load before config import. Always-loaded context (`AI_RULES.md`) stays minimal; detail lives in `docs/ai-rules/` and loads only when the topic comes up.

## Output Contract

The deliverable is EXACTLY this shape. Not one big file. Not unlinked docs.

### AI_RULES.md (≤60 lines) — runtime-neutral index

In order:

1. Project one-liner (what it is, 1–2 lines).
2. **Core Rules** — ≤10 bullets. Only top non-derivable constraints (see §Non-Derivable Filter).
3. **Run commands** — entrypoints, test, migration, in one fenced block.
4. **Routing table** — `| Trigger (situation/task) | File |` rows linking every generated `docs/ai-rules/*.md`. Every row carries a concrete trigger, e.g. `| editing under Controller/ | docs/ai-rules/CONTROLLER_RULES.md |`, `| adding a new API | docs/ai-rules/tasks/ADD_API.md |`. Topic-only rows without a trigger are forbidden.
5. **File Layout** — where tests/scripts/docs go; `UPPERCASE.md` = AI/team rules, `lowercase.md` = analysis/reference.

### Runtime entry files — one neutral source

Preferred mode on Linux/WSL/POSIX projects whose Git checkout preserves symlinks:

```text
CLAUDE.md -> AI_RULES.md
AGENTS.md  -> AI_RULES.md
```

Both must be relative symlinks in the project root. Never make `AI_RULES.md` itself a symlink.
The neutral index body must not name or privilege a runtime; filenames appear only at the loader boundary.

Portable fallback when the repository must work on Windows without symlink support, Git reports
`core.symlinks=false`, or the user explicitly requests regular files: create BOTH entry files as
short pointers (≤15 lines) to `AI_RULES.md`. They must not contain rule bodies or point at each other:

```markdown
# Project AI Rules

Read [AI_RULES.md](AI_RULES.md) first, then load only the relevant `docs/ai-rules/` file it links.
```

Do not mix modes. A symlink plus a regular pointer is drift-prone and fails verification.
`AI_RULES.md` is the single source of truth in both modes.

Projects with an intentional custom loader name may keep that loader name, but not a custom neutral
index name. For example, a personal Claude entry may use `CLAUDE.local.md -> AI_RULES.md` alongside
`AGENTS.md -> AI_RULES.md`. A custom `docs_local/` directory does not justify `AI_RULES.local.md`;
the neutral source remains `AI_RULES.md`.

### docs/ai-rules/*.md (each ≤150 lines) — on-demand rule docs

v2 is the output layout version (not a manifest schema): it keeps ordinary project
documentation in `docs/` and generated agent rules under `docs/ai-rules/`. A pre-existing intentional custom rule directory remains supported via
`--docs-dir`; `docs/` alone is the v1 legacy location, not the default for new runs.

Always generate:

| File | Content |
|---|---|
| `ARCHITECTURE.md` | directory map, stack list, data flow, subsystem roles |
| `CODING_RULES.md` | style, naming, comment language, required patterns — each with a real code example |
| `PITFALLS.md` | symptom→cause→fix entries. `Symptom:` quotes the error message/behavior verbatim (greppable), `Cause:` one line, `Fix:` links a rule or playbook step. Covers dual naming, ongoing migrations, runtime drift, version-pinning policies |

Conditional — generate only when the scan detects the observable signal:

| Signal detected (observable predicate) | File |
|---|---|
| A dedicated controller/handler layer directory exists | `CONTROLLER_RULES.md` (controller/handler conventions) |
| A dedicated api/routes/router/endpoints layer contains source files, or a flat Python module declares `/api/` or `/vN/` routes | `API_RULES.md` (routing, auth, request/contract conventions) |
| ≥3 enum/status-code value sets scattered across files (aggregation pays off) | `ENUM_CODES.md` |
| Response serialization/envelope conventions exist in an API/controller layer | `RESPONSE_KEYS.md` (response payload only) |
| ORM mapping, SQL access in a DB/model layer, or a migrations/ directory (plain domain models alone do not count) | `DB_RULES.md` |
| deploy scripts/workflows, systemd units, or Dockerfiles | `DEPLOY.md` |
| git log shows the same file set modified together ≥3 times (recurring task) | `tasks/ADD_<TASK>.md` |

Conditional file names are defaults — rename to fit the project as long as the name stays UPPERCASE and appears in the Routing table. Do not rename `RESPONSE_KEYS.md` to `API_RULES.md`: API routing and response payloads are separate signals; cross-link shared constraints instead of duplicating them. Borderline signal → skip the doc; a rule can live in `CODING_RULES.md` until it earns its own file.

### docs/ai-rules/tasks/*.md (each ≤80 lines) — task playbooks

Numbered step-by-step procedure for ONE recurring task. Every step cites backticked
`evidence: file:line`. Cross-file couplings ("model registered in BOTH `models/__init__.py` AND
`migrations/env.py`") live as playbook steps, not standalone rules. Name pattern:
`docs/ai-rules/tasks/ADD_<TASK>.md` (UPPERCASE).

Cross-link invariant: every file `AI_RULES.md` links exists, and every generated `docs/ai-rules/**/UPPERCASE.md` appears in the Routing table.

Generation marker: the last line of a generated `AI_RULES.md` is `<!-- generated by rule-architect -->`. Its presence is how §Update Mode is detected on a later run.

### `.rule-architect/` — audit state, not routed rules

Every completed generation records `.rule-architect/decisions.json` and
`.rule-architect/manifest.json`; the quiz adds `.rule-architect/quiz/<run-id>.json`. Hook files are
optional and exist only after explicit hook promotion. These files are audit/enforcement state, not
runtime rule docs, so they do not appear in the Routing table. A temporary full scan manifest may be
removed after `decisions.json` has copied its decisions, evidence, caps, source fingerprint, root, and Git HEAD.

## Bundled Scripts

All are stdlib-only Python and live in `scripts/`. Resolve them relative to this
`SKILL.md`; do not assume the current working directory or a runtime-specific home.

| Script | Role |
|---|---|
| `scan.py <root>` | measures observable signals with `met` / `not_met` / `unknown` decisions; `--output` persists the evidence |
| `harvest.py <root>` | mines local Claude and Codex transcripts for the user's own corrections — the rules a cold scan cannot see |

From moveju112/rule-architect, MIT.