Skip to content

chore(claude): add the engineering toolkit with tiered model pins#5

Merged
mhenrixon merged 1 commit into
mainfrom
chore/claude-toolkit
Jul 2, 2026
Merged

chore(claude): add the engineering toolkit with tiered model pins#5
mhenrixon merged 1 commit into
mainfrom
chore/claude-toolkit

Conversation

@mhenrixon

Copy link
Copy Markdown
Owner

What

Adds a .claude/ engineering toolkit and a top-level CLAUDE.md so autonomous
and semi-autonomous workflows (/lfg and its specialists) run against docs-kit's
own domain — the DocsUI:: Phlex kit, the per-site config surface, the registry,
the install generator, and the CSS/deploy contracts.

Every command and agent pins a model tier alias in frontmatter rather than a
full model ID, so pins track the latest model per tier and never go stale.

Tier Where Rationale
fable /plan Read-only planning: investigates, designs, emits a self-contained issue or docs/plans/ markdown for cheaper models to execute
opus /lfg, /architect, /security, /review-pr, /github-review-pr Orchestration, security, PR review
sonnet /tdd, /github-review-comments, /github-review-failures Pattern-following implementation with prescriptive prompts
haiku mechanical subagents (documented in rules/agents.md) File finding, pattern scans

Why

  • A pinned full model ID (claude-opus-4-8) goes stale on every model release;
    tier aliases (opus/sonnet/haiku/fable) fix that class of staleness
    permanently by tracking the latest model per tier.
  • Forcing the most expensive model on every turn is wasteful — layer specialists
    and the review runbooks follow prescriptive prompts and run well a tier down.
  • /plan puts the capable model where it pays off: it audits and writes a
    self-contained spec (context, ordered steps, verification gates, out-of-scope)
    that /lfg executes on a cheaper model without any of the planning session's
    context.

What's included

  • Commands (.claude/commands/): plan, lfg, architect, security,
    review-pr, github-review-pr, github-review-failures,
    github-review-comments, tdd.
  • Rules (.claude/rules/): coding-style, git-workflow, testing,
    agents.
  • CLAUDE.md: critical rules, architecture map, slash-command table, and the
    model-tier convention.
  • .claude/README.md: toolkit index + tier convention.
  • .claude/settings.local.json: permission allowlist.

Notes

  • Content is written for docs-kit invariants: compose from DocsUI:: components
    (never raw daisyUI), read DocsKit.configuration with defaults (backwards
    compat), progressive enhancement (works with JS off), one docs-nav Stimulus
    controller, config.themes in sync with the Tailwind @plugin list, and
    required setup wired into the install generator + docs-kit new template.
  • A perf command/rule was intentionally left out — docs-kit has no benchmark
    harness.

Test plan

  • All 9 commands carry a tier alias in frontmatter
  • No stray references to unrelated projects' internals
  • .claude/ is tracked (not gitignored)

Docs/config only — no application code, no specs affected.

## Summary

Add a `.claude/` toolkit and a top-level `CLAUDE.md` so the autonomous and
semi-autonomous workflows (`/lfg` and friends) run against docs-kit's own domain
— the `DocsUI::` Phlex kit, the per-site config surface, the registry, the
install generator, and the CSS/deploy contracts — instead of another project's
internals.

Every command and agent pins a model **tier alias** in frontmatter rather than a
full model ID, so pins track the latest model per tier and never go stale:

- `haiku`  — mechanical/config work
- `sonnet` — layer specialists / pattern-following implementation (default)
- `opus`   — orchestration, security, PR review
- `fable`  — read-only planning that hands execution to cheaper models (`/plan`)

## What's included

- Commands: `/plan` (fable), `/lfg` `/architect` `/security` `/review-pr`
  `/github-review-pr` (opus), `/tdd` `/github-review-comments`
  `/github-review-failures` (sonnet)
- Rules: coding-style, git-workflow, testing, agents
- `CLAUDE.md` — critical rules, architecture map, slash-command table, and the
  model-tier convention
- `.claude/README.md` — toolkit index + the tier convention
- `.claude/settings.local.json` — permission allowlist (bun/bunx/gh/git/bundle/rake)

## Notes

- The perf command/rule was intentionally dropped — docs-kit has no benchmark
  harness.
- All content is rewritten for docs-kit invariants: compose from `DocsUI::`
  components (never raw daisyUI), read `DocsKit.configuration` (with defaults for
  backwards compat), progressive enhancement (works with JS off), one `docs-nav`
  Stimulus controller, `config.themes` in sync with the Tailwind `@plugin` list,
  and required setup wired into the install generator + `docs-kit new` template.

## Verification

- [x] All 9 commands carry a tier alias; agents rule documents cheaper subagent pins
- [x] No stray references to other projects' internals
- [x] `.claude/` is tracked (not gitignored)
@mhenrixon mhenrixon self-assigned this Jul 2, 2026
@mhenrixon mhenrixon added the documentation Improvements or additions to documentation label Jul 2, 2026
@mhenrixon mhenrixon merged commit 1cfffc0 into main Jul 2, 2026
@mhenrixon mhenrixon deleted the chore/claude-toolkit branch July 4, 2026 14:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant