dat-devkit

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.

What you get

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.

Quick start

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

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

./install.sh <language...> [/path/to/project] [--target claude|codex|gemini|hermes] [--with <plugin>]... [--dry-run]

Languages (multiple allowed for polyglot repos)

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.

Targets

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

Plugins (`--with`, repeatable)

./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/project

Each plugin's requires field is printed as a post-install note so you know what external tool to set up. See Plugin system below.

Dry run

./install.sh typescript ~/path/to/project --dry-run

Previews every action without writing a byte. Good for sanity-checking before a first install.

Configuration

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 — false by default. Branches and commits do not need a ticket id (feat/add-oauth is valid). Flip to true to require one matching ticket_pattern (e.g. feat/GH-42).
ticket_pattern — ERE regex for the ticket-id portion, used only when ticket_required is true.
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 _plans in the file — copy the pair you want into the top-level fields.

Skills

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

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

Plugin system

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

`plugin.json` schema

{
"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 — which skills / rules / hooks get copied into the project's .claude/.

Available plugins

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

Writing your own

Create plugins/<name>/plugin.json with the schema above.
Add the skill / rule / hook files it references.
List them under adds, prerequisites under requires.
Install with ./install.sh <lang> --with <name> /scratch/project and confirm the files land in .claude/.

See plugins/README.md for the full guide.

Adapting to your projects

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.json to 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.

Repository structure

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)

License

dat-devkit

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.

What you get

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.

Quick start

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

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

./install.sh <language...> [/path/to/project] [--target claude|codex|gemini|hermes] [--with <plugin>]... [--dry-run]

Languages (multiple allowed for polyglot repos)

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.

Targets

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

Plugins (`--with`, repeatable)

./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/project

Each plugin's requires field is printed as a post-install note so you know what external tool to set up. See Plugin system below.

Dry run

./install.sh typescript ~/path/to/project --dry-run

Previews every action without writing a byte. Good for sanity-checking before a first install.

Configuration

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 — false by default. Branches and commits do not need a ticket id (feat/add-oauth is valid). Flip to true to require one matching ticket_pattern (e.g. feat/GH-42).
ticket_pattern — ERE regex for the ticket-id portion, used only when ticket_required is true.
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 _plans in the file — copy the pair you want into the top-level fields.

Skills

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

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

Plugin system

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

`plugin.json` schema

{
"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 — which skills / rules / hooks get copied into the project's .claude/.

Available plugins

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

Writing your own

Create plugins/<name>/plugin.json with the schema above.
Add the skill / rule / hook files it references.
List them under adds, prerequisites under requires.
Install with ./install.sh <lang> --with <name> /scratch/project and confirm the files land in .claude/.

See plugins/README.md for the full guide.

Adapting to your projects

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.json to 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.

Repository structure

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)

License

dat-devkit

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.

What you get

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.

Quick start

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

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

./install.sh <language...> [/path/to/project] [--target claude|codex|gemini|hermes] [--with <plugin>]... [--dry-run]

Languages (multiple allowed for polyglot repos)

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.

Targets

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

Plugins (`--with`, repeatable)

./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/project

Each plugin's requires field is printed as a post-install note so you know what external tool to set up. See Plugin system below.

Dry run

./install.sh typescript ~/path/to/project --dry-run

Previews every action without writing a byte. Good for sanity-checking before a first install.

Configuration

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 — false by default. Branches and commits do not need a ticket id (feat/add-oauth is valid). Flip to true to require one matching ticket_pattern (e.g. feat/GH-42).
ticket_pattern — ERE regex for the ticket-id portion, used only when ticket_required is true.
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 _plans in the file — copy the pair you want into the top-level fields.

Skills

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

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

Plugin system

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

`plugin.json` schema

{
"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 — which skills / rules / hooks get copied into the project's .claude/.

Available plugins

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

Writing your own

Create plugins/<name>/plugin.json with the schema above.
Add the skill / rule / hook files it references.
List them under adds, prerequisites under requires.
Install with ./install.sh <lang> --with <name> /scratch/project and confirm the files land in .claude/.

See plugins/README.md for the full guide.

Adapting to your projects

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.json to 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.

Repository structure

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)

License

dat-devkit

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.

What you get

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.

Quick start

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

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

./install.sh <language...> [/path/to/project] [--target claude|codex|gemini|hermes] [--with <plugin>]... [--dry-run]

Languages (multiple allowed for polyglot repos)

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.

Targets

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

Plugins (`--with`, repeatable)

./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/project

Each plugin's requires field is printed as a post-install note so you know what external tool to set up. See Plugin system below.

Dry run

./install.sh typescript ~/path/to/project --dry-run

Previews every action without writing a byte. Good for sanity-checking before a first install.

Configuration

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 — false by default. Branches and commits do not need a ticket id (feat/add-oauth is valid). Flip to true to require one matching ticket_pattern (e.g. feat/GH-42).
ticket_pattern — ERE regex for the ticket-id portion, used only when ticket_required is true.
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 _plans in the file — copy the pair you want into the top-level fields.

Skills

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

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

Plugin system

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

`plugin.json` schema

{
"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 — which skills / rules / hooks get copied into the project's .claude/.

Available plugins

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

Writing your own

Create plugins/<name>/plugin.json with the schema above.
Add the skill / rule / hook files it references.
List them under adds, prerequisites under requires.
Install with ./install.sh <lang> --with <name> /scratch/project and confirm the files land in .claude/.

See plugins/README.md for the full guide.

Adapting to your projects

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.json to 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.

Repository structure

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)

License

dat-devkit

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.

What you get

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.

Quick start

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

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

./install.sh <language...> [/path/to/project] [--target claude|codex|gemini|hermes] [--with <plugin>]... [--dry-run]

Languages (multiple allowed for polyglot repos)

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.

Targets

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

Plugins (`--with`, repeatable)

./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/project

Each plugin's requires field is printed as a post-install note so you know what external tool to set up. See Plugin system below.

Dry run

./install.sh typescript ~/path/to/project --dry-run

Previews every action without writing a byte. Good for sanity-checking before a first install.

Configuration

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 — false by default. Branches and commits do not need a ticket id (feat/add-oauth is valid). Flip to true to require one matching ticket_pattern (e.g. feat/GH-42).
ticket_pattern — ERE regex for the ticket-id portion, used only when ticket_required is true.
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 _plans in the file — copy the pair you want into the top-level fields.

Skills

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

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

Plugin system

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

`plugin.json` schema

{
"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 — which skills / rules / hooks get copied into the project's .claude/.

Available plugins

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

Writing your own

Create plugins/<name>/plugin.json with the schema above.
Add the skill / rule / hook files it references.
List them under adds, prerequisites under requires.
Install with ./install.sh <lang> --with <name> /scratch/project and confirm the files land in .claude/.

See plugins/README.md for the full guide.

Adapting to your projects

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.json to 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.

Repository structure

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)

License

dat-devkit

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.

What you get

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.

Quick start

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

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

./install.sh <language...> [/path/to/project] [--target claude|codex|gemini|hermes] [--with <plugin>]... [--dry-run]

Languages (multiple allowed for polyglot repos)

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.

Targets

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

Plugins (`--with`, repeatable)

./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/project

Each plugin's requires field is printed as a post-install note so you know what external tool to set up. See Plugin system below.

Dry run

./install.sh typescript ~/path/to/project --dry-run

Previews every action without writing a byte. Good for sanity-checking before a first install.

Configuration

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 — false by default. Branches and commits do not need a ticket id (feat/add-oauth is valid). Flip to true to require one matching ticket_pattern (e.g. feat/GH-42).
ticket_pattern — ERE regex for the ticket-id portion, used only when ticket_required is true.
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 _plans in the file — copy the pair you want into the top-level fields.

Skills

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

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

Plugin system

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

`plugin.json` schema

{
"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 — which skills / rules / hooks get copied into the project's .claude/.

Available plugins

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

Writing your own

Create plugins/<name>/plugin.json with the schema above.
Add the skill / rule / hook files it references.
List them under adds, prerequisites under requires.
Install with ./install.sh <lang> --with <name> /scratch/project and confirm the files land in .claude/.

See plugins/README.md for the full guide.

Adapting to your projects

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.json to 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.

Repository structure

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)

License

dat-devkit

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.

What you get

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.

Quick start

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

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

./install.sh <language...> [/path/to/project] [--target claude|codex|gemini|hermes] [--with <plugin>]... [--dry-run]

Languages (multiple allowed for polyglot repos)

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.

Targets

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

Plugins (`--with`, repeatable)

./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/project

Each plugin's requires field is printed as a post-install note so you know what external tool to set up. See Plugin system below.

Dry run

./install.sh typescript ~/path/to/project --dry-run

Previews every action without writing a byte. Good for sanity-checking before a first install.

Configuration

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 — false by default. Branches and commits do not need a ticket id (feat/add-oauth is valid). Flip to true to require one matching ticket_pattern (e.g. feat/GH-42).
ticket_pattern — ERE regex for the ticket-id portion, used only when ticket_required is true.
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 _plans in the file — copy the pair you want into the top-level fields.

Skills

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

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

Plugin system

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

`plugin.json` schema

{
"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 — which skills / rules / hooks get copied into the project's .claude/.

Available plugins

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

Writing your own

Create plugins/<name>/plugin.json with the schema above.
Add the skill / rule / hook files it references.
List them under adds, prerequisites under requires.
Install with ./install.sh <lang> --with <name> /scratch/project and confirm the files land in .claude/.

See plugins/README.md for the full guide.

Adapting to your projects

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.json to 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.

Repository structure

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)

License

dat-devkit

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.

What you get

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.

Quick start

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

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

./install.sh <language...> [/path/to/project] [--target claude|codex|gemini|hermes] [--with <plugin>]... [--dry-run]

Languages (multiple allowed for polyglot repos)

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.

Targets

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

Plugins (`--with`, repeatable)

./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/project

Each plugin's requires field is printed as a post-install note so you know what external tool to set up. See Plugin system below.

Dry run

./install.sh typescript ~/path/to/project --dry-run

Previews every action without writing a byte. Good for sanity-checking before a first install.

Configuration

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 — false by default. Branches and commits do not need a ticket id (feat/add-oauth is valid). Flip to true to require one matching ticket_pattern (e.g. feat/GH-42).
ticket_pattern — ERE regex for the ticket-id portion, used only when ticket_required is true.
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 _plans in the file — copy the pair you want into the top-level fields.

Skills

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

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

Plugin system

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

`plugin.json` schema

{
"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 — which skills / rules / hooks get copied into the project's .claude/.

Available plugins

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

Writing your own

Create plugins/<name>/plugin.json with the schema above.
Add the skill / rule / hook files it references.
List them under adds, prerequisites under requires.
Install with ./install.sh <lang> --with <name> /scratch/project and confirm the files land in .claude/.

See plugins/README.md for the full guide.

Adapting to your projects

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.json to 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.

Repository structure

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)

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
harness		harness
plugins		plugins
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

dat-devkit

What you get

Quick start

Install matrix

Languages (multiple allowed for polyglot repos)

Targets

Plugins (--with, repeatable)

Dry run

Configuration

Skills

Hooks

Plugin system

plugin.json schema

Available plugins

Writing your own

Adapting to your projects

Repository structure

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

dat-devkit

What you get

Quick start

Install matrix

Languages (multiple allowed for polyglot repos)

Targets

Plugins (--with, repeatable)

Dry run

Configuration

Skills

Hooks

Plugin system

plugin.json schema

Available plugins

Writing your own

Adapting to your projects

Repository structure

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

dat-devkit

What you get

Quick start

Install matrix

Languages (multiple allowed for polyglot repos)

Targets

Plugins (--with, repeatable)

Dry run

Configuration

Skills

Hooks

Plugin system

plugin.json schema

Available plugins

Plugins (`--with`, repeatable)

`plugin.json` schema

Plugins (`--with`, repeatable)

`plugin.json` schema

Plugins (`--with`, repeatable)

`plugin.json` schema

Plugins (`--with`, repeatable)

`plugin.json` schema

Plugins (`--with`, repeatable)