A personal Claude Code engineering harness — rules, hooks, agents, and skills that enforce engineering discipline on every project. GitHub-native, ticket-optional, plug-and-play extras.
Drop it into any repo with one command and every Claude Code session in that project starts with clean-code rules loaded, security and git-safety hooks armed, specialized agents available, and a set of workflow skills (/feature, /review, /audit, …) one slash away. Built for a personal multi-stack workflow but generic enough for any project.
| Layer | Count | What it does |
|---|---|---|
| Rules | 13 common + TypeScript + Python | Coding style, naming, paradigms, design principles, testing, security, git workflow, code review, agent behavior, context hygiene, worktrees, dangerous-action guardrails. Language layers override common where they conflict. |
| Hooks | 13 | Guards and automations fired on tool events — block dangerous bash, block credential writes, block pushes to protected branches, run tests before push, scan for secrets before commit, validate branch/commit format, lint on write, monitor context, remind about PR review, resume/track workflow, auth check. |
| Agents | 5 | planner, coder, tester, reviewer, security — each with model routing (deep-reasoning models for planning/review, faster models for mechanical work). |
| Skills | 7 core | /feature, /bugfix, /review, /audit, /pr, /tdd, /diagnose. |
| Plugins | 2 optional | gitlab (MR creation via glab), notion-prd (write PRDs in Notion). Opt-in with --with. |
Everything is plain files — Markdown rules, Bash hooks, JSON settings. No runtime, no daemon, no lock-in. Read any of it.
# 1. Clone
git clone https://github.com/datj9/dat-devkit.git
cd dat-devkit
# 2. Install into a project (pick your language)
./install.sh typescript ~/path/to/project
# or
./install.sh python ~/path/to/project
# 3. Open Claude Code in that project — hooks fire automatically, skills are availableThat writes a .claude/ directory into your project containing the rules, hooks, agents, skills, bin scripts, and settings. Re-run any time to update — the managed directories (rules, hooks, agents, bin) are replaced cleanly while your devkit-plan.json and any local skills are preserved.
./install.sh <language...> [/path/to/project] [--target claude|codex|gemini|hermes] [--with <plugin>]... [--dry-run]
| Language | Adds |
|---|---|
typescript |
TS coding-style, type-safety, testing, security, GraphQL workflow rules + a GraphQL post-write hook |
python |
Python coding-style, type-safety, testing, security rules |
./install.sh typescript python ~/path/to/project # both, into rules/typescript/ and rules/python/Language rules install into per-language subdirectories so they never overwrite each other.
| Target | Output | Notes |
|---|---|---|
claude (default) |
.claude/ with full harness |
Rules, hooks, agents, skills, bin, settings |
codex |
.codex/AGENTS.md |
All rules concatenated into one instruction file (hooks/skills/agents are Claude-only and skipped) |
gemini |
.gemini/GEMINI.md |
Same concatenated-rules bundle for the Gemini CLI |
hermes |
.hermes/ + AGENTS.md at repo root + git hooks symlinked into .git/hooks/ |
Hermes Agent harness — same rules + agents + workflows, plus real git hooks (branch validation, staged-secret scan, conventional commits, protected-branch enforcement, force-push block, fast-test gate on push). See harness/hermes/README.md for the full mapping from the Claude-Code target to Hermes. |
./install.sh typescript --target codex ~/path/to/project
./install.sh typescript --target hermes ~/path/to/project./install.sh typescript --with gitlab ~/path/to/project
./install.sh python --with notion-prd ~/path/to/project
./install.sh typescript python --with gitlab --with notion-prd ~/path/to/projectEach plugin's requires field is printed as a post-install note so you know what external tool to set up. See Plugin system below.
./install.sh typescript ~/path/to/project --dry-runPreviews every action without writing a byte. Good for sanity-checking before a first install.
Project configuration lives in .claude/devkit-plan.json. It is created on first install and kept on subsequent installs so your edits survive updates. Two things live here: git-workflow conventions (read by the branch/commit validators and the /pr skill) and statusline token budgets.
{
"session_tokens": 44000000,
"weekly_tokens": 880000000,
"git_workflow": {
"ticket_required": false,
"branch_types": [
"feat", "fix", "docs", "style", "refactor", "perf",
"test", "build", "ci", "chore", "revert", "hotfix"
],
"commit_types": [
"feat", "fix", "docs", "style", "refactor", "perf",
"test", "build", "ci", "chore", "revert"
],
"ticket_pattern": "[A-Z]+-[0-9]+",
"ticket_examples": ["GH-42", "ABC-123"],
"branch_examples": ["feat/add-oauth", "fix/null-crash", "feat/GH-42"],
"commit_examples": [
"feat(auth): add JWT refresh token endpoint",
"fix: handle null pointer in parser",
"chore: bump deps"
]
}
}ticket_required—falseby default. Branches and commits do not need a ticket id (feat/add-oauthis valid). Flip totrueto require one matchingticket_pattern(e.g.feat/GH-42).ticket_pattern— ERE regex for the ticket-id portion, used only whenticket_requiredistrue.branch_types/commit_types— the conventional-commit prefixes the validators accept.session_tokens/weekly_tokens— budgets the statusline uses to show usage. Presets for common Claude plans (max_5x,max_20x,team) are listed under_plansin the file — copy the pair you want into the top-level fields.
Type the slash command in Claude Code, or just describe the task and the skill auto-triggers.
| Skill | Use it for |
|---|---|
/feature |
Full feature flow: plan → code → test → review. Orchestrates the agents end to end. |
/bugfix |
Reproduce → fix → test → review for a single defect. |
/review |
Structured code review of the current diff; auto-escalates to a security pass when auth/PII is touched. |
/audit |
Security audit of the codebase + dependency vulnerability scan. |
/pr |
Guided branch → commit → PR creation following your devkit-plan.json conventions (GitHub gh by default). |
/tdd |
Test-first workflow: red → green → refactor, enforcing coverage. |
/diagnose |
Systematic root-cause investigation for a failing test, flaky behavior, or confusing error. |
/feature add a rate limiter to the login endpoint
/bugfix login returns 500 when email is missing
/review
/audit
/pr
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
Hooks are Bash scripts under .claude/hooks/ fired by Claude Code on tool events. They run automatically — no opt-in. Most are guards that block an unsafe action; a few are automations.
| Hook | Event | What it does |
|---|---|---|
block-dangerous-bash |
PreToolUse (Bash) | Blocks sudo, rm -rf outside an allowlist, git reset --hard, git clean -fd, curl … | sh, and similar destructive commands. |
block-credential-writes |
PreToolUse (Write/Edit) | Refuses writes to .env, *.pem, *.key, credentials.json, ~/.ssh/*, and other secret files (templates like .env.example are allowed). |
block-protected-push |
PreToolUse (Bash) | Blocks direct pushes and force-pushes to protected branches (master, main, plus any you add). Use a PR instead. |
pre-push-tests |
PreToolUse (Bash) | Runs the project's tests before a git push. Escape hatch: DEVKIT_PREPUSH_SKIP=1 git push …. |
pre-commit-security |
PreToolUse (Bash) | Scans staged changes for hardcoded secrets before a commit. |
validate-branch-name |
PreToolUse (Bash) | Enforces the branch_types / ticket format from devkit-plan.json. |
validate-commit-msg |
PreToolUse (Bash) | Enforces conventional-commit format and optional ticket id. |
post-write-lint |
PostToolUse (Write/Edit) | Runs the language linter (ESLint / Ruff) on the file just written. |
context-monitor |
PostToolUse | Tracks context-window usage and warns before you run out of headroom. |
pr-review-reminder |
Stop | Reminds you to run /review before opening a PR. |
workflow-resume / workflow-status |
SessionStart / PostToolUse | Persists and restores in-flight workflow state across sessions. |
auth-check |
SessionStart | Verifies the GitHub CLI (and any plugin CLIs) are authenticated. |
Shared helpers live in _lib.sh. The TypeScript layer adds post-write-graphql.sh (GraphQL codegen on schema change).
Plugins are optional, self-contained integrations with a specific tool, kept outside the core harness so the default install stays lean. Each is a directory under plugins/:
plugins/<name>/
├── plugin.json # manifest
├── skills/<skill>/SKILL.md # (optional) skills it adds
├── rules/*.md # (optional) rules it adds
└── hooks/*.sh # (optional) hooks it adds
{
"name": "gitlab",
"description": "GitLab merge request creation via the glab CLI or a GitLab MCP server.",
"requires": ["glab CLI"],
"adds": {
"skills": ["gitlab-pr"],
"rules": [],
"hooks": []
}
}name— matches the directory name.description— one sentence on what it integrates.requires— external prerequisites (a CLI, an MCP server, a token). Printed at install time; the plugin is inert without them.adds— whichskills/rules/hooksget copied into the project's.claude/.
| Plugin | Adds | Requires |
|---|---|---|
gitlab |
/gitlab-pr skill (GitLab MR creation) |
glab CLI or a GitLab MCP server |
notion-prd |
/prd-authoring skill (write PRDs in Notion) |
Notion MCP server + integration token |
- Create
plugins/<name>/plugin.jsonwith the schema above. - Add the skill / rule / hook files it references.
- List them under
adds, prerequisites underrequires. - Install with
./install.sh <lang> --with <name> /scratch/projectand confirm the files land in.claude/.
See plugins/README.md for the full guide.
This harness was built for Dat's stack — Vite/React frontends, NestJS services, Next.js/Strapi sites, serverless TypeScript, and Python tooling — but nothing in the core is specific to those. The rules are general engineering discipline, the hooks are stack-agnostic guards, and the language layers (typescript, python) carry the only framework-flavored content. To adapt it:
- Edit
.claude/devkit-plan.jsonto match your branch/commit conventions and token budgets. - Add or remove language layers under
harness/<language>/. - Keep company- or tool-specific behavior in a plugin, not the core, so the default install stays portable.
GitLab, Notion, and any other vendor integration is a plugin — never a default. The base install assumes only Git and (optionally) the GitHub gh CLI.
dat-devkit/
├── install.sh # installer: languages × targets × plugins
├── README.md
├── LICENSE # MIT
├── package.json
├── .claude-plugin/
│ └── plugin.json # Claude Code plugin manifest
├── harness/
│ ├── common/ # language-agnostic core
│ │ ├── CLAUDE.md # project instructions loaded every session
│ │ ├── settings.json # hook wiring
│ │ ├── settings.local.json # statusline (engineer-local override)
│ │ ├── devkit-plan.json # git workflow + token budgets (kept on update)
│ │ ├── rules/*.md # 13 common rules
│ │ ├── hooks/*.sh # 13 hooks + _lib.sh
│ │ ├── agents/*.md # planner, coder, tester, reviewer, security
│ │ ├── skills/ # feature, bugfix, review, audit, pr, tdd, diagnose
│ │ └── bin/ # statusline, doctor, state, usage scripts
│ ├── typescript/
│ │ ├── rules/*.md # TS coding-style, type-safety, testing, security, graphql
│ │ └── hooks/ # post-write-graphql.sh + hooks-extend.json
│ ├── python/
│ │ └── rules/*.md # Python coding-style, type-safety, testing, security
│ └── hermes/ # Hermes Agent target
│ ├── AGENTS.md # repo-root entry installed by --target hermes
│ ├── agents/*.md # role briefs for delegate_task
│ ├── workflows/*.md # feature, bugfix, review, audit, pr, tdd, diagnose
│ ├── git-hooks/ # pre-commit, commit-msg, pre-push (real git hooks)
│ └── README.md # Claude→Hermes mapping
└── plugins/
├── README.md
├── gitlab/ # /gitlab-pr skill (opt-in)
└── notion-prd/ # /prd-authoring skill (opt-in)
MIT © 2026 Dat Nguyen. See LICENSE.