feat(skills): full engineering-workflow skill set + codex target + worktree support#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
datj9 wants to merge 2 commits into
base:master
Choose a base branch
from
Open

feat(skills): full engineering-workflow skill set + codex target + worktree support #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e8bc2b3
feat(skills): complete engineering-workflow skill set + codex target …
datnguyen-ringkas Jun 12, 2026
9ffa314
Merge remote-tracking branch 'origin/master' into feat/engineering-wo…
datnguyen-ringkas Jun 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 71 additions & 17 deletions README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ Drop it into any repo with one command and every Claude Code session in that pro
| **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`. |
| **Skills** | 15 core | Full engineering loop — align (`/grill`, `/prd`, `/to-issues`) → execute (`/feature`, `/bugfix`, `/tdd`, `/diagnose`) → verify & ship (`/review`, `/audit`, `/pr`) → maintain (`/zoom-out`, `/improve-architecture`, `/triage`, `/handoff`, `/worktree`). |
| **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.
Expand DownExpand Up@@ -63,15 +63,17 @@ Language rules install into per-language subdirectories so they never overwrite
| 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 |
| `codex` | `.codex/AGENTS.md` + `.codex/<skill>/SKILL.md` | All rules concatenated into `AGENTS.md`; skills installed as Codex skill directories (hooks/agents are Claude-only and skipped) |
| `gemini` | `.gemini/GEMINI.md` + `.gemini/<skill>/SKILL.md` | Same concatenated-rules bundle for the Gemini CLI, with the same skill-directory layout as Codex |
| `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](harness/hermes/README.md) for the full mapping from the Claude-Code target to Hermes. |

```bash
./install.sh typescript --target codex ~/path/to/project
./install.sh typescript --target hermes ~/path/to/project
```

Under the `codex` (and `gemini`) target, each core skill lands as `.codex/<skill>/SKILL.md` and each `--with` plugin's skills land in the same shape under `plugins/<name>/skills-codex/`. They are plain Markdown — Codex and Gemini pick them up automatically, no extra wiring needed.

### Plugins (`--with`, repeatable)

```bash
Expand DownExpand Up@@ -133,27 +135,66 @@ Project configuration lives in `.claude/devkit-plan.json`. It is created on firs
## Skills

Type the slash command in Claude Code, or just describe the task and the skill auto-triggers.
The skills compose into the full engineering loop:
**align → specify → decompose → execute → verify → ship → maintain → triage → hand off.**

### Align & specify

| Skill | Use it for |
|---|---|
| `/grill` | Relentless one-question-at-a-time interview that stress-tests a plan **before** any code — the fix for agent misalignment. |
| `/prd` | Synthesize the conversation (ideally after `/grill`) into `.devkit/prd.md`; optionally open it as a GitHub issue. |
| `/to-issues` | Decompose a PRD/plan into many thin **vertical-slice** GitHub issues, labeled AFK/HITL and sequenced by dependency. |

### Execute

| 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. |
| `/tdd` | Test-first workflow: red → green → refactor, enforcing coverage. |
| `/diagnose` | Systematic root-cause investigation for a failing test, flaky behavior, or confusing error. |

### Verify & ship

| Skill | Use it for |
|---|---|
| `/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. |

### Understand & maintain

| Skill | Use it for |
|---|---|
| `/zoom-out` | Map an unfamiliar area by going **up** a layer; persists durable domain terms to a project-root `CONTEXT.md`. |
| `/improve-architecture` | Find shallow-module / ball-of-mud friction, propose deepening refactors, optionally record an ADR. |
| `/triage` | Move GitHub issues through a triage state machine into actionable, labeled work with agent briefs. |
| `/handoff` | Compact the session into a temp-dir handoff doc a fresh agent can pick up cold. |
| `/worktree` | Create a git worktree and install the harness into it — parallel work with isolated workflow state. |

```text
/grill I want to add multi-tenant billing
/prd
/to-issues
/feature add a rate limiter to the login endpoint
/bugfix login returns 500 when email is missing
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/review
/audit
/pr
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/zoom-out how does the payments subsystem fit together
/improve-architecture the order module is a mess
/triage
/handoff finish the billing slice next session
/worktree make a worktree for the billing refactor
```

Several skills share a project-root **`CONTEXT.md`** — a small, human-maintained glossary
of the project's domain language — so specs, issues, and reviews all speak your terms
instead of generic boilerplate.

---

## Hooks
Expand DownExpand Up@@ -185,12 +226,18 @@ Plugins are optional, self-contained integrations with a specific tool, kept out

```
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 # manifest
├── skills/<skill>/SKILL.md # Claude target: skills it adds
├── skills-codex/<skill>/SKILL.md# codex / gemini targets: same skills, codex-shaped
├── rules/*.md # (optional) rules it adds
└── hooks/*.sh # (optional) hooks it adds
```

Skills are duplicated per target because Claude skills use the Claude frontmatter
(`disable-model-invocation`, model routing, sub-agent dispatch) which doesn't
apply to Codex/Gemini. The `codex` and `gemini` versions are stripped down to
plain Markdown that any tool can pick up.

### `plugin.json` schema

```json
Expand DownExpand Up@@ -218,6 +265,9 @@ plugins/<name>/
| `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 |

Each plugin ships both a Claude version (`skills/<name>/SKILL.md`) and a
codex/gemini version (`skills-codex/<name>/SKILL.md`).

### Writing your own

1. Create `plugins/<name>/plugin.json` with the schema above.
Expand DownExpand Up@@ -257,11 +307,15 @@ dat-devkit/
│ │ ├── 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
│ │ ├── rules/*.md # common rules (incl. worktree hygiene)
│ │ ├── hooks/*.sh # hooks + _lib.sh
│ │ ├── agents/*.md # planner, coder, tester, reviewer, security
│ │ ├── skills/ # feature, bugfix, review, audit, pr, tdd, diagnose
│ │ └── bin/ # statusline, doctor, state, usage scripts
│ │ ├── skills/ # Claude-target skills (15): align → execute → ship → maintain
│ │ │ └── _shared/ # github-access.md, context-doc.md references
│ │ └── bin/ # statusline, doctor, state, worktree, usage scripts
│ ├── codex/ # codex/gemini-target skills (same set, in codex shape)
│ │ ├── _shared/ # github-access.md, context-doc.md references
│ │ └── skills/<name>/SKILL.md
│ ├── typescript/
│ │ ├── rules/*.md # TS coding-style, type-safety, testing, security, graphql
│ │ └── hooks/ # post-write-graphql.sh + hooks-extend.json
Expand All@@ -275,8 +329,8 @@ dat-devkit/
│ └── README.md # Claude→Hermes mapping
└── plugins/
├── README.md
├── gitlab/ # /gitlab-pr skill (opt-in)
└── notion-prd/ # /prd-authoring skill (opt-in)
├── gitlab/ # /gitlab-pr skill (opt-in) — skills/ for Claude, skills-codex/ for codex/gemini
└── notion-prd/ # /prd-authoring skill (opt-in) — same shape
```

---
Expand Down
47 changes: 47 additions & 0 deletions harness/codex/_shared/context-doc.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
# CONTEXT.md — Shared Project Language (Shared Reference)

Several skills (`/grill`, `/prd`, `/to-issues`, `/zoom-out`, `/improve-architecture`) read
and write a project-root `CONTEXT.md`. It's the kit's antidote to **verbosity and
misalignment**: a shared glossary so the agent and the codebase use the same words, which
cuts re-explanation and keeps specs/issues/reports in the project's own vocabulary.

## What it is

A short, durable, human-maintained file at the **project root** (`./CONTEXT.md`). It is
*not* documentation of how the code works — that's what the code and `/zoom-out` are for.
It's the **vocabulary and load-bearing facts** a newcomer (human or agent) needs to talk
about the project correctly.

## What goes in it

- **Domain glossary** — the project's nouns and verbs with one-line definitions. ("A
*Tenant* is a billing account; *Members* belong to exactly one Tenant.")
- **Key concepts / invariants** — rules that are always true and easy to violate. ("All
money is integer minor units; never floats.")
- **Module names that carry meaning** — deepened modules named during
`/improve-architecture`, so future sessions reuse the term.
- **Pointers, not prose** — "Auth lives behind the `Session` seam; see `docs/adr/004`."

## What does NOT go in it

- File-by-file tours, call graphs, or anything that goes stale on refactor (use `/zoom-out`
live instead).
- Secrets, credentials, or PII.
- Requirements or plans — those are `/prd` and issues.

## How skills use it

| Skill | Reads it to… | Writes to it when… |
|---|---|---|
| `/grill` | ask in the project's terms | (read-only) |
| `/prd` | spec in the project's terms | (read-only) |
| `/to-issues` | name issues in the project's terms | (read-only) |
| `/zoom-out` | explain in the project's terms | a new load-bearing term is discovered |
| `/improve-architecture` | reason about modules in the project's terms | a deepened module is named |

## Bootstrapping

If `CONTEXT.md` doesn't exist when a skill needs it, create a minimal one (title + empty
Glossary / Concepts sections) and add the terms you have. Keep it short — a CONTEXT.md
nobody maintains is worse than none. Pair it with ADRs in `docs/adr/` for *decisions*
(CONTEXT.md is for *vocabulary*).
51 changes: 51 additions & 0 deletions harness/codex/_shared/github-access.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
# GitHub Access — Shared Reference (Codex)

Use this whenever a Codex skill needs to read or write GitHub data (PR metadata, diffs, comments, reviews). This devkit is GitHub-only and uses the `gh` CLI.

## Step 1 — Confirm `gh` is authenticated

```bash
gh auth status
```

- If it reports a logged-in account, you're ready — use `gh` commands directly.
- If it errors or says "not logged in", tell the user to run `gh auth login`
(or set `GH_TOKEN` in their environment). Do not attempt to store tokens yourself.

## Step 2 — Common operations

```bash
# Default branch of the current repo
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name

# PR metadata (base branch matters for diffs and reviews)
gh pr view <number|url> --json number,title,baseRefName,headRefName,url

# PR diff
gh pr diff <number|url>

# Create a PR
gh pr create --title "<title>" --body "<body>" --base <default-branch>

# Comment on a PR (general note)
gh pr comment <number|url> --body "<comment>"

# Submit a review (approve / request changes / comment)
gh pr review <number|url> --comment --body "<findings>"
```

## Step 3 — API fallback

When a `gh` subcommand doesn't cover what you need, drop to the REST API via
`gh api` — it reuses the same authentication:

```bash
# Example: list review comments on a PR
gh api repos/{owner}/{repo}/pulls/<number>/comments

# Example: post an inline review comment anchored to a line
gh api repos/{owner}/{repo}/pulls/<number>/comments \
-f body="<comment>" -f commit_id="<sha>" -f path="<file>" -F line=<n> -f side=RIGHT
```

Resolve `{owner}/{repo}` with `gh repo view --json nameWithOwner --jq .nameWithOwner`.
56 changes: 56 additions & 0 deletions harness/codex/skills/audit/SKILL.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
---
name: audit
description: Runs an OWASP Top 10 security audit (access control, cryptographic failures, injection, insecure design, misconfiguration, vulnerable components, auth failures, data integrity, logging failures, SSRF) and a dependency CVE scan against the project's package manager, then writes a PASS/FAIL report to .devkit/security-audit.md and optionally posts findings to a GitHub PR. Use when the user says "audit", "security audit", "OWASP", "compliance check", "scan dependencies", "check for vulnerabilities", or before merging.
---

# Audit Workflow

Run an OWASP Top 10 review and a package vulnerability scan.

> GitHub access: follow [`_shared/github-access.md`](../_shared/github-access.md).

> Codex note: state lives in `.devkit/`. No `devkit-state.sh` binary — bump
> `.devkit/state.json` between phases.

## Step 1 — Determine scope

- GitHub PR (number or URL) provided: fetch the diff with `gh pr diff <number|url>`.
- No PR given: use the local diff, or scan the entire project.

Initialize state:
```bash
mkdir -p .devkit
SLUG="<pr-number-or-slug>"
cat > .devkit/state.json <<JSON
{
"workflow": "audit",
"slug": "$SLUG",
"current_step": 1,
"steps": ["security", "complete"]
}
JSON
```

## Step 2 — Security

Run the audit yourself in this session:
- OWASP Top 10 checks: access control, cryptographic failures, injection,
insecure design, misconfiguration, vulnerable components, auth failures,
data integrity, logging failures, SSRF
- Dependency vulnerability scan: `npm audit` (Node) or `pip-audit` (Python)
- Write the report to `.devkit/security-audit.md` with findings and a
`PASS/FAIL` verdict

Print `## AUDIT COMPLETE`. Bump `current_step` to 2.

## Step 3 — Complete

```bash
cat > .devkit/state.json <<JSON
{ "workflow": "audit", "slug": "$SLUG", "status": "complete" }
JSON
```
Print the audit summary and overall PASS/FAIL verdict.

If a PR was provided, offer to post the audit:
- `gh pr comment <number|url> --body "<audit summary>"`
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
feat(skills): full engineering-workflow skill set + codex target + worktree support#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

datj9
wants to merge
2
commits into

base:master
Choose a base branch

from

 Open


feat(skills): full engineering-workflow skill set + codex target + worktree support
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e8bc2b3

feat(skills): complete engineering-workflow skill set + codex target …


datnguyen-ringkas Jun 12, 2026
9ffa314

Merge remote-tracking branch 'origin/master' into feat/engineering-wo…


datnguyen-ringkas Jun 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


88 changes: 71 additions & 17 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ Drop it into any repo with one command and every Claude Code session in that pro
| **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`. |
| **Skills** | 15 core | Full engineering loop — align (`/grill`, `/prd`, `/to-issues`) → execute (`/feature`, `/bugfix`, `/tdd`, `/diagnose`) → verify & ship (`/review`, `/audit`, `/pr`) → maintain (`/zoom-out`, `/improve-architecture`, `/triage`, `/handoff`, `/worktree`). |
| **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.
Expand DownExpand Up@@ -63,15 +63,17 @@ Language rules install into per-language subdirectories so they never overwrite
| 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 |
| `codex` | `.codex/AGENTS.md` + `.codex/<skill>/SKILL.md` | All rules concatenated into `AGENTS.md`; skills installed as Codex skill directories (hooks/agents are Claude-only and skipped) |
| `gemini` | `.gemini/GEMINI.md` + `.gemini/<skill>/SKILL.md` | Same concatenated-rules bundle for the Gemini CLI, with the same skill-directory layout as Codex |
| `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](harness/hermes/README.md) for the full mapping from the Claude-Code target to Hermes. |

```bash
./install.sh typescript --target codex ~/path/to/project
./install.sh typescript --target hermes ~/path/to/project
```

Under the `codex` (and `gemini`) target, each core skill lands as `.codex/<skill>/SKILL.md` and each `--with` plugin's skills land in the same shape under `plugins/<name>/skills-codex/`. They are plain Markdown — Codex and Gemini pick them up automatically, no extra wiring needed.

### Plugins (`--with`, repeatable)

```bash
Expand DownExpand Up@@ -133,27 +135,66 @@ Project configuration lives in `.claude/devkit-plan.json`. It is created on firs
## Skills

Type the slash command in Claude Code, or just describe the task and the skill auto-triggers.
The skills compose into the full engineering loop:
**align → specify → decompose → execute → verify → ship → maintain → triage → hand off.**

### Align & specify

| Skill | Use it for |
|---|---|
| `/grill` | Relentless one-question-at-a-time interview that stress-tests a plan **before** any code — the fix for agent misalignment. |
| `/prd` | Synthesize the conversation (ideally after `/grill`) into `.devkit/prd.md`; optionally open it as a GitHub issue. |
| `/to-issues` | Decompose a PRD/plan into many thin **vertical-slice** GitHub issues, labeled AFK/HITL and sequenced by dependency. |

### Execute

| 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. |
| `/tdd` | Test-first workflow: red → green → refactor, enforcing coverage. |
| `/diagnose` | Systematic root-cause investigation for a failing test, flaky behavior, or confusing error. |

### Verify & ship

| Skill | Use it for |
|---|---|
| `/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. |

### Understand & maintain

| Skill | Use it for |
|---|---|
| `/zoom-out` | Map an unfamiliar area by going **up** a layer; persists durable domain terms to a project-root `CONTEXT.md`. |
| `/improve-architecture` | Find shallow-module / ball-of-mud friction, propose deepening refactors, optionally record an ADR. |
| `/triage` | Move GitHub issues through a triage state machine into actionable, labeled work with agent briefs. |
| `/handoff` | Compact the session into a temp-dir handoff doc a fresh agent can pick up cold. |
| `/worktree` | Create a git worktree and install the harness into it — parallel work with isolated workflow state. |

```text
/grill I want to add multi-tenant billing
/prd
/to-issues
/feature add a rate limiter to the login endpoint
/bugfix login returns 500 when email is missing
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/review
/audit
/pr
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/zoom-out how does the payments subsystem fit together
/improve-architecture the order module is a mess
/triage
/handoff finish the billing slice next session
/worktree make a worktree for the billing refactor
```

Several skills share a project-root **`CONTEXT.md`** — a small, human-maintained glossary
of the project's domain language — so specs, issues, and reviews all speak your terms
instead of generic boilerplate.

---

## Hooks
Expand DownExpand Up@@ -185,12 +226,18 @@ Plugins are optional, self-contained integrations with a specific tool, kept out

```
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 # manifest
├── skills/<skill>/SKILL.md # Claude target: skills it adds
├── skills-codex/<skill>/SKILL.md# codex / gemini targets: same skills, codex-shaped
├── rules/*.md # (optional) rules it adds
└── hooks/*.sh # (optional) hooks it adds
```

Skills are duplicated per target because Claude skills use the Claude frontmatter
(`disable-model-invocation`, model routing, sub-agent dispatch) which doesn't
apply to Codex/Gemini. The `codex` and `gemini` versions are stripped down to
plain Markdown that any tool can pick up.

### `plugin.json` schema

```json
Expand DownExpand Up@@ -218,6 +265,9 @@ plugins/<name>/
| `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 |

Each plugin ships both a Claude version (`skills/<name>/SKILL.md`) and a
codex/gemini version (`skills-codex/<name>/SKILL.md`).

### Writing your own

1. Create `plugins/<name>/plugin.json` with the schema above.
Expand DownExpand Up@@ -257,11 +307,15 @@ dat-devkit/
│ │ ├── 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
│ │ ├── rules/*.md # common rules (incl. worktree hygiene)
│ │ ├── hooks/*.sh # hooks + _lib.sh
│ │ ├── agents/*.md # planner, coder, tester, reviewer, security
│ │ ├── skills/ # feature, bugfix, review, audit, pr, tdd, diagnose
│ │ └── bin/ # statusline, doctor, state, usage scripts
│ │ ├── skills/ # Claude-target skills (15): align → execute → ship → maintain
│ │ │ └── _shared/ # github-access.md, context-doc.md references
│ │ └── bin/ # statusline, doctor, state, worktree, usage scripts
│ ├── codex/ # codex/gemini-target skills (same set, in codex shape)
│ │ ├── _shared/ # github-access.md, context-doc.md references
│ │ └── skills/<name>/SKILL.md
│ ├── typescript/
│ │ ├── rules/*.md # TS coding-style, type-safety, testing, security, graphql
│ │ └── hooks/ # post-write-graphql.sh + hooks-extend.json
Expand All@@ -275,8 +329,8 @@ dat-devkit/
│ └── README.md # Claude→Hermes mapping
└── plugins/
 ├── README.md
 ├── gitlab/ # /gitlab-pr skill (opt-in)
 └── notion-prd/ # /prd-authoring skill (opt-in)
 ├── gitlab/ # /gitlab-pr skill (opt-in) — skills/ for Claude, skills-codex/ for codex/gemini
 └── notion-prd/ # /prd-authoring skill (opt-in) — same shape
```

---
Expand Down

47 changes: 47 additions & 0 deletions
harness/codex/_shared/context-doc.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
# CONTEXT.md — Shared Project Language (Shared Reference)

Several skills (`/grill`, `/prd`, `/to-issues`, `/zoom-out`, `/improve-architecture`) read
and write a project-root `CONTEXT.md`. It's the kit's antidote to **verbosity and
misalignment**: a shared glossary so the agent and the codebase use the same words, which
cuts re-explanation and keeps specs/issues/reports in the project's own vocabulary.

## What it is

A short, durable, human-maintained file at the **project root** (`./CONTEXT.md`). It is
*not* documentation of how the code works — that's what the code and `/zoom-out` are for.
It's the **vocabulary and load-bearing facts** a newcomer (human or agent) needs to talk
about the project correctly.

## What goes in it

- **Domain glossary** — the project's nouns and verbs with one-line definitions. ("A
 *Tenant* is a billing account; *Members* belong to exactly one Tenant.")
- **Key concepts / invariants** — rules that are always true and easy to violate. ("All
 money is integer minor units; never floats.")
- **Module names that carry meaning** — deepened modules named during
 `/improve-architecture`, so future sessions reuse the term.
- **Pointers, not prose** — "Auth lives behind the `Session` seam; see `docs/adr/004`."

## What does NOT go in it

- File-by-file tours, call graphs, or anything that goes stale on refactor (use `/zoom-out`
 live instead).
- Secrets, credentials, or PII.
- Requirements or plans — those are `/prd` and issues.

## How skills use it

| Skill | Reads it to… | Writes to it when… |
|---|---|---|
| `/grill` | ask in the project's terms | (read-only) |
| `/prd` | spec in the project's terms | (read-only) |
| `/to-issues` | name issues in the project's terms | (read-only) |
| `/zoom-out` | explain in the project's terms | a new load-bearing term is discovered |
| `/improve-architecture` | reason about modules in the project's terms | a deepened module is named |

## Bootstrapping

If `CONTEXT.md` doesn't exist when a skill needs it, create a minimal one (title + empty
Glossary / Concepts sections) and add the terms you have. Keep it short — a CONTEXT.md
nobody maintains is worse than none. Pair it with ADRs in `docs/adr/` for *decisions*
(CONTEXT.md is for *vocabulary*).

51 changes: 51 additions & 0 deletions
harness/codex/_shared/github-access.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
# GitHub Access — Shared Reference (Codex)

Use this whenever a Codex skill needs to read or write GitHub data (PR metadata, diffs, comments, reviews). This devkit is GitHub-only and uses the `gh` CLI.

## Step 1 — Confirm `gh` is authenticated

```bash
gh auth status
```

- If it reports a logged-in account, you're ready — use `gh` commands directly.
- If it errors or says "not logged in", tell the user to run `gh auth login`
 (or set `GH_TOKEN` in their environment). Do not attempt to store tokens yourself.

## Step 2 — Common operations

```bash
# Default branch of the current repo
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name

# PR metadata (base branch matters for diffs and reviews)
gh pr view <number|url> --json number,title,baseRefName,headRefName,url

# PR diff
gh pr diff <number|url>

# Create a PR
gh pr create --title "<title>" --body "<body>" --base <default-branch>

# Comment on a PR (general note)
gh pr comment <number|url> --body "<comment>"

# Submit a review (approve / request changes / comment)
gh pr review <number|url> --comment --body "<findings>"
```

## Step 3 — API fallback

When a `gh` subcommand doesn't cover what you need, drop to the REST API via
`gh api` — it reuses the same authentication:

```bash
# Example: list review comments on a PR
gh api repos/{owner}/{repo}/pulls/<number>/comments

# Example: post an inline review comment anchored to a line
gh api repos/{owner}/{repo}/pulls/<number>/comments \
 -f body="<comment>" -f commit_id="<sha>" -f path="<file>" -F line=<n> -f side=RIGHT
```

Resolve `{owner}/{repo}` with `gh repo view --json nameWithOwner --jq .nameWithOwner`.

56 changes: 56 additions & 0 deletions
harness/codex/skills/audit/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
---
name: audit
description: Runs an OWASP Top 10 security audit (access control, cryptographic failures, injection, insecure design, misconfiguration, vulnerable components, auth failures, data integrity, logging failures, SSRF) and a dependency CVE scan against the project's package manager, then writes a PASS/FAIL report to .devkit/security-audit.md and optionally posts findings to a GitHub PR. Use when the user says "audit", "security audit", "OWASP", "compliance check", "scan dependencies", "check for vulnerabilities", or before merging.
---

# Audit Workflow

Run an OWASP Top 10 review and a package vulnerability scan.

> GitHub access: follow [`_shared/github-access.md`](../_shared/github-access.md).

> Codex note: state lives in `.devkit/`. No `devkit-state.sh` binary — bump
> `.devkit/state.json` between phases.

## Step 1 — Determine scope

- GitHub PR (number or URL) provided: fetch the diff with `gh pr diff <number|url>`.
- No PR given: use the local diff, or scan the entire project.

Initialize state:
```bash
mkdir -p .devkit
SLUG="<pr-number-or-slug>"
cat > .devkit/state.json <<JSON
{
 "workflow": "audit",
 "slug": "$SLUG",
 "current_step": 1,
 "steps": ["security", "complete"]
}
JSON
```

## Step 2 — Security

Run the audit yourself in this session:
- OWASP Top 10 checks: access control, cryptographic failures, injection,
 insecure design, misconfiguration, vulnerable components, auth failures,
 data integrity, logging failures, SSRF
- Dependency vulnerability scan: `npm audit` (Node) or `pip-audit` (Python)
- Write the report to `.devkit/security-audit.md` with findings and a
 `PASS/FAIL` verdict

Print `## AUDIT COMPLETE`. Bump `current_step` to 2.

## Step 3 — Complete

```bash
cat > .devkit/state.json <<JSON
{ "workflow": "audit", "slug": "$SLUG", "status": "complete" }
JSON
```
Print the audit summary and overall PASS/FAIL verdict.

If a PR was provided, offer to post the audit:
- `gh pr comment <number|url> --body "<audit summary>"`
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(skills): full engineering-workflow skill set + codex target + worktree support#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

datj9
wants to merge
2
commits into

base:master
Choose a base branch

from

 Open


feat(skills): full engineering-workflow skill set + codex target + worktree support
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e8bc2b3

feat(skills): complete engineering-workflow skill set + codex target …


datnguyen-ringkas Jun 12, 2026
9ffa314

Merge remote-tracking branch 'origin/master' into feat/engineering-wo…


datnguyen-ringkas Jun 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


88 changes: 71 additions & 17 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ Drop it into any repo with one command and every Claude Code session in that pro
| **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`. |
| **Skills** | 15 core | Full engineering loop — align (`/grill`, `/prd`, `/to-issues`) → execute (`/feature`, `/bugfix`, `/tdd`, `/diagnose`) → verify & ship (`/review`, `/audit`, `/pr`) → maintain (`/zoom-out`, `/improve-architecture`, `/triage`, `/handoff`, `/worktree`). |
| **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.
Expand DownExpand Up@@ -63,15 +63,17 @@ Language rules install into per-language subdirectories so they never overwrite
| 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 |
| `codex` | `.codex/AGENTS.md` + `.codex/<skill>/SKILL.md` | All rules concatenated into `AGENTS.md`; skills installed as Codex skill directories (hooks/agents are Claude-only and skipped) |
| `gemini` | `.gemini/GEMINI.md` + `.gemini/<skill>/SKILL.md` | Same concatenated-rules bundle for the Gemini CLI, with the same skill-directory layout as Codex |
| `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](harness/hermes/README.md) for the full mapping from the Claude-Code target to Hermes. |

```bash
./install.sh typescript --target codex ~/path/to/project
./install.sh typescript --target hermes ~/path/to/project
```

Under the `codex` (and `gemini`) target, each core skill lands as `.codex/<skill>/SKILL.md` and each `--with` plugin's skills land in the same shape under `plugins/<name>/skills-codex/`. They are plain Markdown — Codex and Gemini pick them up automatically, no extra wiring needed.

### Plugins (`--with`, repeatable)

```bash
Expand DownExpand Up@@ -133,27 +135,66 @@ Project configuration lives in `.claude/devkit-plan.json`. It is created on firs
## Skills

Type the slash command in Claude Code, or just describe the task and the skill auto-triggers.
The skills compose into the full engineering loop:
**align → specify → decompose → execute → verify → ship → maintain → triage → hand off.**

### Align & specify

| Skill | Use it for |
|---|---|
| `/grill` | Relentless one-question-at-a-time interview that stress-tests a plan **before** any code — the fix for agent misalignment. |
| `/prd` | Synthesize the conversation (ideally after `/grill`) into `.devkit/prd.md`; optionally open it as a GitHub issue. |
| `/to-issues` | Decompose a PRD/plan into many thin **vertical-slice** GitHub issues, labeled AFK/HITL and sequenced by dependency. |

### Execute

| 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. |
| `/tdd` | Test-first workflow: red → green → refactor, enforcing coverage. |
| `/diagnose` | Systematic root-cause investigation for a failing test, flaky behavior, or confusing error. |

### Verify & ship

| Skill | Use it for |
|---|---|
| `/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. |

### Understand & maintain

| Skill | Use it for |
|---|---|
| `/zoom-out` | Map an unfamiliar area by going **up** a layer; persists durable domain terms to a project-root `CONTEXT.md`. |
| `/improve-architecture` | Find shallow-module / ball-of-mud friction, propose deepening refactors, optionally record an ADR. |
| `/triage` | Move GitHub issues through a triage state machine into actionable, labeled work with agent briefs. |
| `/handoff` | Compact the session into a temp-dir handoff doc a fresh agent can pick up cold. |
| `/worktree` | Create a git worktree and install the harness into it — parallel work with isolated workflow state. |

```text
/grill I want to add multi-tenant billing
/prd
/to-issues
/feature add a rate limiter to the login endpoint
/bugfix login returns 500 when email is missing
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/review
/audit
/pr
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/zoom-out how does the payments subsystem fit together
/improve-architecture the order module is a mess
/triage
/handoff finish the billing slice next session
/worktree make a worktree for the billing refactor
```

Several skills share a project-root **`CONTEXT.md`** — a small, human-maintained glossary
of the project's domain language — so specs, issues, and reviews all speak your terms
instead of generic boilerplate.

---

## Hooks
Expand DownExpand Up@@ -185,12 +226,18 @@ Plugins are optional, self-contained integrations with a specific tool, kept out

```
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 # manifest
├── skills/<skill>/SKILL.md # Claude target: skills it adds
├── skills-codex/<skill>/SKILL.md# codex / gemini targets: same skills, codex-shaped
├── rules/*.md # (optional) rules it adds
└── hooks/*.sh # (optional) hooks it adds
```

Skills are duplicated per target because Claude skills use the Claude frontmatter
(`disable-model-invocation`, model routing, sub-agent dispatch) which doesn't
apply to Codex/Gemini. The `codex` and `gemini` versions are stripped down to
plain Markdown that any tool can pick up.

### `plugin.json` schema

```json
Expand DownExpand Up@@ -218,6 +265,9 @@ plugins/<name>/
| `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 |

Each plugin ships both a Claude version (`skills/<name>/SKILL.md`) and a
codex/gemini version (`skills-codex/<name>/SKILL.md`).

### Writing your own

1. Create `plugins/<name>/plugin.json` with the schema above.
Expand DownExpand Up@@ -257,11 +307,15 @@ dat-devkit/
│ │ ├── 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
│ │ ├── rules/*.md # common rules (incl. worktree hygiene)
│ │ ├── hooks/*.sh # hooks + _lib.sh
│ │ ├── agents/*.md # planner, coder, tester, reviewer, security
│ │ ├── skills/ # feature, bugfix, review, audit, pr, tdd, diagnose
│ │ └── bin/ # statusline, doctor, state, usage scripts
│ │ ├── skills/ # Claude-target skills (15): align → execute → ship → maintain
│ │ │ └── _shared/ # github-access.md, context-doc.md references
│ │ └── bin/ # statusline, doctor, state, worktree, usage scripts
│ ├── codex/ # codex/gemini-target skills (same set, in codex shape)
│ │ ├── _shared/ # github-access.md, context-doc.md references
│ │ └── skills/<name>/SKILL.md
│ ├── typescript/
│ │ ├── rules/*.md # TS coding-style, type-safety, testing, security, graphql
│ │ └── hooks/ # post-write-graphql.sh + hooks-extend.json
Expand All@@ -275,8 +329,8 @@ dat-devkit/
│ └── README.md # Claude→Hermes mapping
└── plugins/
 ├── README.md
 ├── gitlab/ # /gitlab-pr skill (opt-in)
 └── notion-prd/ # /prd-authoring skill (opt-in)
 ├── gitlab/ # /gitlab-pr skill (opt-in) — skills/ for Claude, skills-codex/ for codex/gemini
 └── notion-prd/ # /prd-authoring skill (opt-in) — same shape
```

---
Expand Down

47 changes: 47 additions & 0 deletions
harness/codex/_shared/context-doc.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
# CONTEXT.md — Shared Project Language (Shared Reference)

Several skills (`/grill`, `/prd`, `/to-issues`, `/zoom-out`, `/improve-architecture`) read
and write a project-root `CONTEXT.md`. It's the kit's antidote to **verbosity and
misalignment**: a shared glossary so the agent and the codebase use the same words, which
cuts re-explanation and keeps specs/issues/reports in the project's own vocabulary.

## What it is

A short, durable, human-maintained file at the **project root** (`./CONTEXT.md`). It is
*not* documentation of how the code works — that's what the code and `/zoom-out` are for.
It's the **vocabulary and load-bearing facts** a newcomer (human or agent) needs to talk
about the project correctly.

## What goes in it

- **Domain glossary** — the project's nouns and verbs with one-line definitions. ("A
 *Tenant* is a billing account; *Members* belong to exactly one Tenant.")
- **Key concepts / invariants** — rules that are always true and easy to violate. ("All
 money is integer minor units; never floats.")
- **Module names that carry meaning** — deepened modules named during
 `/improve-architecture`, so future sessions reuse the term.
- **Pointers, not prose** — "Auth lives behind the `Session` seam; see `docs/adr/004`."

## What does NOT go in it

- File-by-file tours, call graphs, or anything that goes stale on refactor (use `/zoom-out`
 live instead).
- Secrets, credentials, or PII.
- Requirements or plans — those are `/prd` and issues.

## How skills use it

| Skill | Reads it to… | Writes to it when… |
|---|---|---|
| `/grill` | ask in the project's terms | (read-only) |
| `/prd` | spec in the project's terms | (read-only) |
| `/to-issues` | name issues in the project's terms | (read-only) |
| `/zoom-out` | explain in the project's terms | a new load-bearing term is discovered |
| `/improve-architecture` | reason about modules in the project's terms | a deepened module is named |

## Bootstrapping

If `CONTEXT.md` doesn't exist when a skill needs it, create a minimal one (title + empty
Glossary / Concepts sections) and add the terms you have. Keep it short — a CONTEXT.md
nobody maintains is worse than none. Pair it with ADRs in `docs/adr/` for *decisions*
(CONTEXT.md is for *vocabulary*).

51 changes: 51 additions & 0 deletions
harness/codex/_shared/github-access.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
# GitHub Access — Shared Reference (Codex)

Use this whenever a Codex skill needs to read or write GitHub data (PR metadata, diffs, comments, reviews). This devkit is GitHub-only and uses the `gh` CLI.

## Step 1 — Confirm `gh` is authenticated

```bash
gh auth status
```

- If it reports a logged-in account, you're ready — use `gh` commands directly.
- If it errors or says "not logged in", tell the user to run `gh auth login`
 (or set `GH_TOKEN` in their environment). Do not attempt to store tokens yourself.

## Step 2 — Common operations

```bash
# Default branch of the current repo
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name

# PR metadata (base branch matters for diffs and reviews)
gh pr view <number|url> --json number,title,baseRefName,headRefName,url

# PR diff
gh pr diff <number|url>

# Create a PR
gh pr create --title "<title>" --body "<body>" --base <default-branch>

# Comment on a PR (general note)
gh pr comment <number|url> --body "<comment>"

# Submit a review (approve / request changes / comment)
gh pr review <number|url> --comment --body "<findings>"
```

## Step 3 — API fallback

When a `gh` subcommand doesn't cover what you need, drop to the REST API via
`gh api` — it reuses the same authentication:

```bash
# Example: list review comments on a PR
gh api repos/{owner}/{repo}/pulls/<number>/comments

# Example: post an inline review comment anchored to a line
gh api repos/{owner}/{repo}/pulls/<number>/comments \
 -f body="<comment>" -f commit_id="<sha>" -f path="<file>" -F line=<n> -f side=RIGHT
```

Resolve `{owner}/{repo}` with `gh repo view --json nameWithOwner --jq .nameWithOwner`.

56 changes: 56 additions & 0 deletions
harness/codex/skills/audit/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
---
name: audit
description: Runs an OWASP Top 10 security audit (access control, cryptographic failures, injection, insecure design, misconfiguration, vulnerable components, auth failures, data integrity, logging failures, SSRF) and a dependency CVE scan against the project's package manager, then writes a PASS/FAIL report to .devkit/security-audit.md and optionally posts findings to a GitHub PR. Use when the user says "audit", "security audit", "OWASP", "compliance check", "scan dependencies", "check for vulnerabilities", or before merging.
---

# Audit Workflow

Run an OWASP Top 10 review and a package vulnerability scan.

> GitHub access: follow [`_shared/github-access.md`](../_shared/github-access.md).

> Codex note: state lives in `.devkit/`. No `devkit-state.sh` binary — bump
> `.devkit/state.json` between phases.

## Step 1 — Determine scope

- GitHub PR (number or URL) provided: fetch the diff with `gh pr diff <number|url>`.
- No PR given: use the local diff, or scan the entire project.

Initialize state:
```bash
mkdir -p .devkit
SLUG="<pr-number-or-slug>"
cat > .devkit/state.json <<JSON
{
 "workflow": "audit",
 "slug": "$SLUG",
 "current_step": 1,
 "steps": ["security", "complete"]
}
JSON
```

## Step 2 — Security

Run the audit yourself in this session:
- OWASP Top 10 checks: access control, cryptographic failures, injection,
 insecure design, misconfiguration, vulnerable components, auth failures,
 data integrity, logging failures, SSRF
- Dependency vulnerability scan: `npm audit` (Node) or `pip-audit` (Python)
- Write the report to `.devkit/security-audit.md` with findings and a
 `PASS/FAIL` verdict

Print `## AUDIT COMPLETE`. Bump `current_step` to 2.

## Step 3 — Complete

```bash
cat > .devkit/state.json <<JSON
{ "workflow": "audit", "slug": "$SLUG", "status": "complete" }
JSON
```
Print the audit summary and overall PASS/FAIL verdict.

If a PR was provided, offer to post the audit:
- `gh pr comment <number|url> --body "<audit summary>"`
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(skills): full engineering-workflow skill set + codex target + worktree support#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

datj9
wants to merge
2
commits into

base:master
Choose a base branch

from

 Open


feat(skills): full engineering-workflow skill set + codex target + worktree support
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e8bc2b3

feat(skills): complete engineering-workflow skill set + codex target …


datnguyen-ringkas Jun 12, 2026
9ffa314

Merge remote-tracking branch 'origin/master' into feat/engineering-wo…


datnguyen-ringkas Jun 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


88 changes: 71 additions & 17 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ Drop it into any repo with one command and every Claude Code session in that pro
| **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`. |
| **Skills** | 15 core | Full engineering loop — align (`/grill`, `/prd`, `/to-issues`) → execute (`/feature`, `/bugfix`, `/tdd`, `/diagnose`) → verify & ship (`/review`, `/audit`, `/pr`) → maintain (`/zoom-out`, `/improve-architecture`, `/triage`, `/handoff`, `/worktree`). |
| **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.
Expand DownExpand Up@@ -63,15 +63,17 @@ Language rules install into per-language subdirectories so they never overwrite
| 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 |
| `codex` | `.codex/AGENTS.md` + `.codex/<skill>/SKILL.md` | All rules concatenated into `AGENTS.md`; skills installed as Codex skill directories (hooks/agents are Claude-only and skipped) |
| `gemini` | `.gemini/GEMINI.md` + `.gemini/<skill>/SKILL.md` | Same concatenated-rules bundle for the Gemini CLI, with the same skill-directory layout as Codex |
| `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](harness/hermes/README.md) for the full mapping from the Claude-Code target to Hermes. |

```bash
./install.sh typescript --target codex ~/path/to/project
./install.sh typescript --target hermes ~/path/to/project
```

Under the `codex` (and `gemini`) target, each core skill lands as `.codex/<skill>/SKILL.md` and each `--with` plugin's skills land in the same shape under `plugins/<name>/skills-codex/`. They are plain Markdown — Codex and Gemini pick them up automatically, no extra wiring needed.

### Plugins (`--with`, repeatable)

```bash
Expand DownExpand Up@@ -133,27 +135,66 @@ Project configuration lives in `.claude/devkit-plan.json`. It is created on firs
## Skills

Type the slash command in Claude Code, or just describe the task and the skill auto-triggers.
The skills compose into the full engineering loop:
**align → specify → decompose → execute → verify → ship → maintain → triage → hand off.**

### Align & specify

| Skill | Use it for |
|---|---|
| `/grill` | Relentless one-question-at-a-time interview that stress-tests a plan **before** any code — the fix for agent misalignment. |
| `/prd` | Synthesize the conversation (ideally after `/grill`) into `.devkit/prd.md`; optionally open it as a GitHub issue. |
| `/to-issues` | Decompose a PRD/plan into many thin **vertical-slice** GitHub issues, labeled AFK/HITL and sequenced by dependency. |

### Execute

| 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. |
| `/tdd` | Test-first workflow: red → green → refactor, enforcing coverage. |
| `/diagnose` | Systematic root-cause investigation for a failing test, flaky behavior, or confusing error. |

### Verify & ship

| Skill | Use it for |
|---|---|
| `/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. |

### Understand & maintain

| Skill | Use it for |
|---|---|
| `/zoom-out` | Map an unfamiliar area by going **up** a layer; persists durable domain terms to a project-root `CONTEXT.md`. |
| `/improve-architecture` | Find shallow-module / ball-of-mud friction, propose deepening refactors, optionally record an ADR. |
| `/triage` | Move GitHub issues through a triage state machine into actionable, labeled work with agent briefs. |
| `/handoff` | Compact the session into a temp-dir handoff doc a fresh agent can pick up cold. |
| `/worktree` | Create a git worktree and install the harness into it — parallel work with isolated workflow state. |

```text
/grill I want to add multi-tenant billing
/prd
/to-issues
/feature add a rate limiter to the login endpoint
/bugfix login returns 500 when email is missing
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/review
/audit
/pr
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/zoom-out how does the payments subsystem fit together
/improve-architecture the order module is a mess
/triage
/handoff finish the billing slice next session
/worktree make a worktree for the billing refactor
```

Several skills share a project-root **`CONTEXT.md`** — a small, human-maintained glossary
of the project's domain language — so specs, issues, and reviews all speak your terms
instead of generic boilerplate.

---

## Hooks
Expand DownExpand Up@@ -185,12 +226,18 @@ Plugins are optional, self-contained integrations with a specific tool, kept out

```
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 # manifest
├── skills/<skill>/SKILL.md # Claude target: skills it adds
├── skills-codex/<skill>/SKILL.md# codex / gemini targets: same skills, codex-shaped
├── rules/*.md # (optional) rules it adds
└── hooks/*.sh # (optional) hooks it adds
```

Skills are duplicated per target because Claude skills use the Claude frontmatter
(`disable-model-invocation`, model routing, sub-agent dispatch) which doesn't
apply to Codex/Gemini. The `codex` and `gemini` versions are stripped down to
plain Markdown that any tool can pick up.

### `plugin.json` schema

```json
Expand DownExpand Up@@ -218,6 +265,9 @@ plugins/<name>/
| `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 |

Each plugin ships both a Claude version (`skills/<name>/SKILL.md`) and a
codex/gemini version (`skills-codex/<name>/SKILL.md`).

### Writing your own

1. Create `plugins/<name>/plugin.json` with the schema above.
Expand DownExpand Up@@ -257,11 +307,15 @@ dat-devkit/
│ │ ├── 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
│ │ ├── rules/*.md # common rules (incl. worktree hygiene)
│ │ ├── hooks/*.sh # hooks + _lib.sh
│ │ ├── agents/*.md # planner, coder, tester, reviewer, security
│ │ ├── skills/ # feature, bugfix, review, audit, pr, tdd, diagnose
│ │ └── bin/ # statusline, doctor, state, usage scripts
│ │ ├── skills/ # Claude-target skills (15): align → execute → ship → maintain
│ │ │ └── _shared/ # github-access.md, context-doc.md references
│ │ └── bin/ # statusline, doctor, state, worktree, usage scripts
│ ├── codex/ # codex/gemini-target skills (same set, in codex shape)
│ │ ├── _shared/ # github-access.md, context-doc.md references
│ │ └── skills/<name>/SKILL.md
│ ├── typescript/
│ │ ├── rules/*.md # TS coding-style, type-safety, testing, security, graphql
│ │ └── hooks/ # post-write-graphql.sh + hooks-extend.json
Expand All@@ -275,8 +329,8 @@ dat-devkit/
│ └── README.md # Claude→Hermes mapping
└── plugins/
 ├── README.md
 ├── gitlab/ # /gitlab-pr skill (opt-in)
 └── notion-prd/ # /prd-authoring skill (opt-in)
 ├── gitlab/ # /gitlab-pr skill (opt-in) — skills/ for Claude, skills-codex/ for codex/gemini
 └── notion-prd/ # /prd-authoring skill (opt-in) — same shape
```

---
Expand Down

47 changes: 47 additions & 0 deletions
harness/codex/_shared/context-doc.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
# CONTEXT.md — Shared Project Language (Shared Reference)

Several skills (`/grill`, `/prd`, `/to-issues`, `/zoom-out`, `/improve-architecture`) read
and write a project-root `CONTEXT.md`. It's the kit's antidote to **verbosity and
misalignment**: a shared glossary so the agent and the codebase use the same words, which
cuts re-explanation and keeps specs/issues/reports in the project's own vocabulary.

## What it is

A short, durable, human-maintained file at the **project root** (`./CONTEXT.md`). It is
*not* documentation of how the code works — that's what the code and `/zoom-out` are for.
It's the **vocabulary and load-bearing facts** a newcomer (human or agent) needs to talk
about the project correctly.

## What goes in it

- **Domain glossary** — the project's nouns and verbs with one-line definitions. ("A
 *Tenant* is a billing account; *Members* belong to exactly one Tenant.")
- **Key concepts / invariants** — rules that are always true and easy to violate. ("All
 money is integer minor units; never floats.")
- **Module names that carry meaning** — deepened modules named during
 `/improve-architecture`, so future sessions reuse the term.
- **Pointers, not prose** — "Auth lives behind the `Session` seam; see `docs/adr/004`."

## What does NOT go in it

- File-by-file tours, call graphs, or anything that goes stale on refactor (use `/zoom-out`
 live instead).
- Secrets, credentials, or PII.
- Requirements or plans — those are `/prd` and issues.

## How skills use it

| Skill | Reads it to… | Writes to it when… |
|---|---|---|
| `/grill` | ask in the project's terms | (read-only) |
| `/prd` | spec in the project's terms | (read-only) |
| `/to-issues` | name issues in the project's terms | (read-only) |
| `/zoom-out` | explain in the project's terms | a new load-bearing term is discovered |
| `/improve-architecture` | reason about modules in the project's terms | a deepened module is named |

## Bootstrapping

If `CONTEXT.md` doesn't exist when a skill needs it, create a minimal one (title + empty
Glossary / Concepts sections) and add the terms you have. Keep it short — a CONTEXT.md
nobody maintains is worse than none. Pair it with ADRs in `docs/adr/` for *decisions*
(CONTEXT.md is for *vocabulary*).

51 changes: 51 additions & 0 deletions
harness/codex/_shared/github-access.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
# GitHub Access — Shared Reference (Codex)

Use this whenever a Codex skill needs to read or write GitHub data (PR metadata, diffs, comments, reviews). This devkit is GitHub-only and uses the `gh` CLI.

## Step 1 — Confirm `gh` is authenticated

```bash
gh auth status
```

- If it reports a logged-in account, you're ready — use `gh` commands directly.
- If it errors or says "not logged in", tell the user to run `gh auth login`
 (or set `GH_TOKEN` in their environment). Do not attempt to store tokens yourself.

## Step 2 — Common operations

```bash
# Default branch of the current repo
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name

# PR metadata (base branch matters for diffs and reviews)
gh pr view <number|url> --json number,title,baseRefName,headRefName,url

# PR diff
gh pr diff <number|url>

# Create a PR
gh pr create --title "<title>" --body "<body>" --base <default-branch>

# Comment on a PR (general note)
gh pr comment <number|url> --body "<comment>"

# Submit a review (approve / request changes / comment)
gh pr review <number|url> --comment --body "<findings>"
```

## Step 3 — API fallback

When a `gh` subcommand doesn't cover what you need, drop to the REST API via
`gh api` — it reuses the same authentication:

```bash
# Example: list review comments on a PR
gh api repos/{owner}/{repo}/pulls/<number>/comments

# Example: post an inline review comment anchored to a line
gh api repos/{owner}/{repo}/pulls/<number>/comments \
 -f body="<comment>" -f commit_id="<sha>" -f path="<file>" -F line=<n> -f side=RIGHT
```

Resolve `{owner}/{repo}` with `gh repo view --json nameWithOwner --jq .nameWithOwner`.

56 changes: 56 additions & 0 deletions
harness/codex/skills/audit/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
---
name: audit
description: Runs an OWASP Top 10 security audit (access control, cryptographic failures, injection, insecure design, misconfiguration, vulnerable components, auth failures, data integrity, logging failures, SSRF) and a dependency CVE scan against the project's package manager, then writes a PASS/FAIL report to .devkit/security-audit.md and optionally posts findings to a GitHub PR. Use when the user says "audit", "security audit", "OWASP", "compliance check", "scan dependencies", "check for vulnerabilities", or before merging.
---

# Audit Workflow

Run an OWASP Top 10 review and a package vulnerability scan.

> GitHub access: follow [`_shared/github-access.md`](../_shared/github-access.md).

> Codex note: state lives in `.devkit/`. No `devkit-state.sh` binary — bump
> `.devkit/state.json` between phases.

## Step 1 — Determine scope

- GitHub PR (number or URL) provided: fetch the diff with `gh pr diff <number|url>`.
- No PR given: use the local diff, or scan the entire project.

Initialize state:
```bash
mkdir -p .devkit
SLUG="<pr-number-or-slug>"
cat > .devkit/state.json <<JSON
{
 "workflow": "audit",
 "slug": "$SLUG",
 "current_step": 1,
 "steps": ["security", "complete"]
}
JSON
```

## Step 2 — Security

Run the audit yourself in this session:
- OWASP Top 10 checks: access control, cryptographic failures, injection,
 insecure design, misconfiguration, vulnerable components, auth failures,
 data integrity, logging failures, SSRF
- Dependency vulnerability scan: `npm audit` (Node) or `pip-audit` (Python)
- Write the report to `.devkit/security-audit.md` with findings and a
 `PASS/FAIL` verdict

Print `## AUDIT COMPLETE`. Bump `current_step` to 2.

## Step 3 — Complete

```bash
cat > .devkit/state.json <<JSON
{ "workflow": "audit", "slug": "$SLUG", "status": "complete" }
JSON
```
Print the audit summary and overall PASS/FAIL verdict.

If a PR was provided, offer to post the audit:
- `gh pr comment <number|url> --body "<audit summary>"`
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
feat(skills): full engineering-workflow skill set + codex target + worktree support#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

datj9
wants to merge
2
commits into

base:master
Choose a base branch

from

 Open


feat(skills): full engineering-workflow skill set + codex target + worktree support
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e8bc2b3

feat(skills): complete engineering-workflow skill set + codex target …


datnguyen-ringkas Jun 12, 2026
9ffa314

Merge remote-tracking branch 'origin/master' into feat/engineering-wo…


datnguyen-ringkas Jun 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


88 changes: 71 additions & 17 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ Drop it into any repo with one command and every Claude Code session in that pro
| **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`. |
| **Skills** | 15 core | Full engineering loop — align (`/grill`, `/prd`, `/to-issues`) → execute (`/feature`, `/bugfix`, `/tdd`, `/diagnose`) → verify & ship (`/review`, `/audit`, `/pr`) → maintain (`/zoom-out`, `/improve-architecture`, `/triage`, `/handoff`, `/worktree`). |
| **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.
Expand DownExpand Up@@ -63,15 +63,17 @@ Language rules install into per-language subdirectories so they never overwrite
| 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 |
| `codex` | `.codex/AGENTS.md` + `.codex/<skill>/SKILL.md` | All rules concatenated into `AGENTS.md`; skills installed as Codex skill directories (hooks/agents are Claude-only and skipped) |
| `gemini` | `.gemini/GEMINI.md` + `.gemini/<skill>/SKILL.md` | Same concatenated-rules bundle for the Gemini CLI, with the same skill-directory layout as Codex |
| `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](harness/hermes/README.md) for the full mapping from the Claude-Code target to Hermes. |

```bash
./install.sh typescript --target codex ~/path/to/project
./install.sh typescript --target hermes ~/path/to/project
```

Under the `codex` (and `gemini`) target, each core skill lands as `.codex/<skill>/SKILL.md` and each `--with` plugin's skills land in the same shape under `plugins/<name>/skills-codex/`. They are plain Markdown — Codex and Gemini pick them up automatically, no extra wiring needed.

### Plugins (`--with`, repeatable)

```bash
Expand DownExpand Up@@ -133,27 +135,66 @@ Project configuration lives in `.claude/devkit-plan.json`. It is created on firs
## Skills

Type the slash command in Claude Code, or just describe the task and the skill auto-triggers.
The skills compose into the full engineering loop:
**align → specify → decompose → execute → verify → ship → maintain → triage → hand off.**

### Align & specify

| Skill | Use it for |
|---|---|
| `/grill` | Relentless one-question-at-a-time interview that stress-tests a plan **before** any code — the fix for agent misalignment. |
| `/prd` | Synthesize the conversation (ideally after `/grill`) into `.devkit/prd.md`; optionally open it as a GitHub issue. |
| `/to-issues` | Decompose a PRD/plan into many thin **vertical-slice** GitHub issues, labeled AFK/HITL and sequenced by dependency. |

### Execute

| 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. |
| `/tdd` | Test-first workflow: red → green → refactor, enforcing coverage. |
| `/diagnose` | Systematic root-cause investigation for a failing test, flaky behavior, or confusing error. |

### Verify & ship

| Skill | Use it for |
|---|---|
| `/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. |

### Understand & maintain

| Skill | Use it for |
|---|---|
| `/zoom-out` | Map an unfamiliar area by going **up** a layer; persists durable domain terms to a project-root `CONTEXT.md`. |
| `/improve-architecture` | Find shallow-module / ball-of-mud friction, propose deepening refactors, optionally record an ADR. |
| `/triage` | Move GitHub issues through a triage state machine into actionable, labeled work with agent briefs. |
| `/handoff` | Compact the session into a temp-dir handoff doc a fresh agent can pick up cold. |
| `/worktree` | Create a git worktree and install the harness into it — parallel work with isolated workflow state. |

```text
/grill I want to add multi-tenant billing
/prd
/to-issues
/feature add a rate limiter to the login endpoint
/bugfix login returns 500 when email is missing
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/review
/audit
/pr
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/zoom-out how does the payments subsystem fit together
/improve-architecture the order module is a mess
/triage
/handoff finish the billing slice next session
/worktree make a worktree for the billing refactor
```

Several skills share a project-root **`CONTEXT.md`** — a small, human-maintained glossary
of the project's domain language — so specs, issues, and reviews all speak your terms
instead of generic boilerplate.

---

## Hooks
Expand DownExpand Up@@ -185,12 +226,18 @@ Plugins are optional, self-contained integrations with a specific tool, kept out

```
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 # manifest
├── skills/<skill>/SKILL.md # Claude target: skills it adds
├── skills-codex/<skill>/SKILL.md# codex / gemini targets: same skills, codex-shaped
├── rules/*.md # (optional) rules it adds
└── hooks/*.sh # (optional) hooks it adds
```

Skills are duplicated per target because Claude skills use the Claude frontmatter
(`disable-model-invocation`, model routing, sub-agent dispatch) which doesn't
apply to Codex/Gemini. The `codex` and `gemini` versions are stripped down to
plain Markdown that any tool can pick up.

### `plugin.json` schema

```json
Expand DownExpand Up@@ -218,6 +265,9 @@ plugins/<name>/
| `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 |

Each plugin ships both a Claude version (`skills/<name>/SKILL.md`) and a
codex/gemini version (`skills-codex/<name>/SKILL.md`).

### Writing your own

1. Create `plugins/<name>/plugin.json` with the schema above.
Expand DownExpand Up@@ -257,11 +307,15 @@ dat-devkit/
│ │ ├── 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
│ │ ├── rules/*.md # common rules (incl. worktree hygiene)
│ │ ├── hooks/*.sh # hooks + _lib.sh
│ │ ├── agents/*.md # planner, coder, tester, reviewer, security
│ │ ├── skills/ # feature, bugfix, review, audit, pr, tdd, diagnose
│ │ └── bin/ # statusline, doctor, state, usage scripts
│ │ ├── skills/ # Claude-target skills (15): align → execute → ship → maintain
│ │ │ └── _shared/ # github-access.md, context-doc.md references
│ │ └── bin/ # statusline, doctor, state, worktree, usage scripts
│ ├── codex/ # codex/gemini-target skills (same set, in codex shape)
│ │ ├── _shared/ # github-access.md, context-doc.md references
│ │ └── skills/<name>/SKILL.md
│ ├── typescript/
│ │ ├── rules/*.md # TS coding-style, type-safety, testing, security, graphql
│ │ └── hooks/ # post-write-graphql.sh + hooks-extend.json
Expand All@@ -275,8 +329,8 @@ dat-devkit/
│ └── README.md # Claude→Hermes mapping
└── plugins/
 ├── README.md
 ├── gitlab/ # /gitlab-pr skill (opt-in)
 └── notion-prd/ # /prd-authoring skill (opt-in)
 ├── gitlab/ # /gitlab-pr skill (opt-in) — skills/ for Claude, skills-codex/ for codex/gemini
 └── notion-prd/ # /prd-authoring skill (opt-in) — same shape
```

---
Expand Down

47 changes: 47 additions & 0 deletions
harness/codex/_shared/context-doc.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
# CONTEXT.md — Shared Project Language (Shared Reference)

Several skills (`/grill`, `/prd`, `/to-issues`, `/zoom-out`, `/improve-architecture`) read
and write a project-root `CONTEXT.md`. It's the kit's antidote to **verbosity and
misalignment**: a shared glossary so the agent and the codebase use the same words, which
cuts re-explanation and keeps specs/issues/reports in the project's own vocabulary.

## What it is

A short, durable, human-maintained file at the **project root** (`./CONTEXT.md`). It is
*not* documentation of how the code works — that's what the code and `/zoom-out` are for.
It's the **vocabulary and load-bearing facts** a newcomer (human or agent) needs to talk
about the project correctly.

## What goes in it

- **Domain glossary** — the project's nouns and verbs with one-line definitions. ("A
 *Tenant* is a billing account; *Members* belong to exactly one Tenant.")
- **Key concepts / invariants** — rules that are always true and easy to violate. ("All
 money is integer minor units; never floats.")
- **Module names that carry meaning** — deepened modules named during
 `/improve-architecture`, so future sessions reuse the term.
- **Pointers, not prose** — "Auth lives behind the `Session` seam; see `docs/adr/004`."

## What does NOT go in it

- File-by-file tours, call graphs, or anything that goes stale on refactor (use `/zoom-out`
 live instead).
- Secrets, credentials, or PII.
- Requirements or plans — those are `/prd` and issues.

## How skills use it

| Skill | Reads it to… | Writes to it when… |
|---|---|---|
| `/grill` | ask in the project's terms | (read-only) |
| `/prd` | spec in the project's terms | (read-only) |
| `/to-issues` | name issues in the project's terms | (read-only) |
| `/zoom-out` | explain in the project's terms | a new load-bearing term is discovered |
| `/improve-architecture` | reason about modules in the project's terms | a deepened module is named |

## Bootstrapping

If `CONTEXT.md` doesn't exist when a skill needs it, create a minimal one (title + empty
Glossary / Concepts sections) and add the terms you have. Keep it short — a CONTEXT.md
nobody maintains is worse than none. Pair it with ADRs in `docs/adr/` for *decisions*
(CONTEXT.md is for *vocabulary*).

51 changes: 51 additions & 0 deletions
harness/codex/_shared/github-access.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
# GitHub Access — Shared Reference (Codex)

Use this whenever a Codex skill needs to read or write GitHub data (PR metadata, diffs, comments, reviews). This devkit is GitHub-only and uses the `gh` CLI.

## Step 1 — Confirm `gh` is authenticated

```bash
gh auth status
```

- If it reports a logged-in account, you're ready — use `gh` commands directly.
- If it errors or says "not logged in", tell the user to run `gh auth login`
 (or set `GH_TOKEN` in their environment). Do not attempt to store tokens yourself.

## Step 2 — Common operations

```bash
# Default branch of the current repo
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name

# PR metadata (base branch matters for diffs and reviews)
gh pr view <number|url> --json number,title,baseRefName,headRefName,url

# PR diff
gh pr diff <number|url>

# Create a PR
gh pr create --title "<title>" --body "<body>" --base <default-branch>

# Comment on a PR (general note)
gh pr comment <number|url> --body "<comment>"

# Submit a review (approve / request changes / comment)
gh pr review <number|url> --comment --body "<findings>"
```

## Step 3 — API fallback

When a `gh` subcommand doesn't cover what you need, drop to the REST API via
`gh api` — it reuses the same authentication:

```bash
# Example: list review comments on a PR
gh api repos/{owner}/{repo}/pulls/<number>/comments

# Example: post an inline review comment anchored to a line
gh api repos/{owner}/{repo}/pulls/<number>/comments \
 -f body="<comment>" -f commit_id="<sha>" -f path="<file>" -F line=<n> -f side=RIGHT
```

Resolve `{owner}/{repo}` with `gh repo view --json nameWithOwner --jq .nameWithOwner`.

56 changes: 56 additions & 0 deletions
harness/codex/skills/audit/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
---
name: audit
description: Runs an OWASP Top 10 security audit (access control, cryptographic failures, injection, insecure design, misconfiguration, vulnerable components, auth failures, data integrity, logging failures, SSRF) and a dependency CVE scan against the project's package manager, then writes a PASS/FAIL report to .devkit/security-audit.md and optionally posts findings to a GitHub PR. Use when the user says "audit", "security audit", "OWASP", "compliance check", "scan dependencies", "check for vulnerabilities", or before merging.
---

# Audit Workflow

Run an OWASP Top 10 review and a package vulnerability scan.

> GitHub access: follow [`_shared/github-access.md`](../_shared/github-access.md).

> Codex note: state lives in `.devkit/`. No `devkit-state.sh` binary — bump
> `.devkit/state.json` between phases.

## Step 1 — Determine scope

- GitHub PR (number or URL) provided: fetch the diff with `gh pr diff <number|url>`.
- No PR given: use the local diff, or scan the entire project.

Initialize state:
```bash
mkdir -p .devkit
SLUG="<pr-number-or-slug>"
cat > .devkit/state.json <<JSON
{
 "workflow": "audit",
 "slug": "$SLUG",
 "current_step": 1,
 "steps": ["security", "complete"]
}
JSON
```

## Step 2 — Security

Run the audit yourself in this session:
- OWASP Top 10 checks: access control, cryptographic failures, injection,
 insecure design, misconfiguration, vulnerable components, auth failures,
 data integrity, logging failures, SSRF
- Dependency vulnerability scan: `npm audit` (Node) or `pip-audit` (Python)
- Write the report to `.devkit/security-audit.md` with findings and a
 `PASS/FAIL` verdict

Print `## AUDIT COMPLETE`. Bump `current_step` to 2.

## Step 3 — Complete

```bash
cat > .devkit/state.json <<JSON
{ "workflow": "audit", "slug": "$SLUG", "status": "complete" }
JSON
```
Print the audit summary and overall PASS/FAIL verdict.

If a PR was provided, offer to post the audit:
- `gh pr comment <number|url> --body "<audit summary>"`
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(skills): full engineering-workflow skill set + codex target + worktree support#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

datj9
wants to merge
2
commits into

base:master
Choose a base branch

from

 Open


feat(skills): full engineering-workflow skill set + codex target + worktree support
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e8bc2b3

feat(skills): complete engineering-workflow skill set + codex target …


datnguyen-ringkas Jun 12, 2026
9ffa314

Merge remote-tracking branch 'origin/master' into feat/engineering-wo…


datnguyen-ringkas Jun 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


88 changes: 71 additions & 17 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ Drop it into any repo with one command and every Claude Code session in that pro
| **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`. |
| **Skills** | 15 core | Full engineering loop — align (`/grill`, `/prd`, `/to-issues`) → execute (`/feature`, `/bugfix`, `/tdd`, `/diagnose`) → verify & ship (`/review`, `/audit`, `/pr`) → maintain (`/zoom-out`, `/improve-architecture`, `/triage`, `/handoff`, `/worktree`). |
| **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.
Expand DownExpand Up@@ -63,15 +63,17 @@ Language rules install into per-language subdirectories so they never overwrite
| 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 |
| `codex` | `.codex/AGENTS.md` + `.codex/<skill>/SKILL.md` | All rules concatenated into `AGENTS.md`; skills installed as Codex skill directories (hooks/agents are Claude-only and skipped) |
| `gemini` | `.gemini/GEMINI.md` + `.gemini/<skill>/SKILL.md` | Same concatenated-rules bundle for the Gemini CLI, with the same skill-directory layout as Codex |
| `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](harness/hermes/README.md) for the full mapping from the Claude-Code target to Hermes. |

```bash
./install.sh typescript --target codex ~/path/to/project
./install.sh typescript --target hermes ~/path/to/project
```

Under the `codex` (and `gemini`) target, each core skill lands as `.codex/<skill>/SKILL.md` and each `--with` plugin's skills land in the same shape under `plugins/<name>/skills-codex/`. They are plain Markdown — Codex and Gemini pick them up automatically, no extra wiring needed.

### Plugins (`--with`, repeatable)

```bash
Expand DownExpand Up@@ -133,27 +135,66 @@ Project configuration lives in `.claude/devkit-plan.json`. It is created on firs
## Skills

Type the slash command in Claude Code, or just describe the task and the skill auto-triggers.
The skills compose into the full engineering loop:
**align → specify → decompose → execute → verify → ship → maintain → triage → hand off.**

### Align & specify

| Skill | Use it for |
|---|---|
| `/grill` | Relentless one-question-at-a-time interview that stress-tests a plan **before** any code — the fix for agent misalignment. |
| `/prd` | Synthesize the conversation (ideally after `/grill`) into `.devkit/prd.md`; optionally open it as a GitHub issue. |
| `/to-issues` | Decompose a PRD/plan into many thin **vertical-slice** GitHub issues, labeled AFK/HITL and sequenced by dependency. |

### Execute

| 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. |
| `/tdd` | Test-first workflow: red → green → refactor, enforcing coverage. |
| `/diagnose` | Systematic root-cause investigation for a failing test, flaky behavior, or confusing error. |

### Verify & ship

| Skill | Use it for |
|---|---|
| `/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. |

### Understand & maintain

| Skill | Use it for |
|---|---|
| `/zoom-out` | Map an unfamiliar area by going **up** a layer; persists durable domain terms to a project-root `CONTEXT.md`. |
| `/improve-architecture` | Find shallow-module / ball-of-mud friction, propose deepening refactors, optionally record an ADR. |
| `/triage` | Move GitHub issues through a triage state machine into actionable, labeled work with agent briefs. |
| `/handoff` | Compact the session into a temp-dir handoff doc a fresh agent can pick up cold. |
| `/worktree` | Create a git worktree and install the harness into it — parallel work with isolated workflow state. |

```text
/grill I want to add multi-tenant billing
/prd
/to-issues
/feature add a rate limiter to the login endpoint
/bugfix login returns 500 when email is missing
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/review
/audit
/pr
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/zoom-out how does the payments subsystem fit together
/improve-architecture the order module is a mess
/triage
/handoff finish the billing slice next session
/worktree make a worktree for the billing refactor
```

Several skills share a project-root **`CONTEXT.md`** — a small, human-maintained glossary
of the project's domain language — so specs, issues, and reviews all speak your terms
instead of generic boilerplate.

---

## Hooks
Expand DownExpand Up@@ -185,12 +226,18 @@ Plugins are optional, self-contained integrations with a specific tool, kept out

```
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 # manifest
├── skills/<skill>/SKILL.md # Claude target: skills it adds
├── skills-codex/<skill>/SKILL.md# codex / gemini targets: same skills, codex-shaped
├── rules/*.md # (optional) rules it adds
└── hooks/*.sh # (optional) hooks it adds
```

Skills are duplicated per target because Claude skills use the Claude frontmatter
(`disable-model-invocation`, model routing, sub-agent dispatch) which doesn't
apply to Codex/Gemini. The `codex` and `gemini` versions are stripped down to
plain Markdown that any tool can pick up.

### `plugin.json` schema

```json
Expand DownExpand Up@@ -218,6 +265,9 @@ plugins/<name>/
| `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 |

Each plugin ships both a Claude version (`skills/<name>/SKILL.md`) and a
codex/gemini version (`skills-codex/<name>/SKILL.md`).

### Writing your own

1. Create `plugins/<name>/plugin.json` with the schema above.
Expand DownExpand Up@@ -257,11 +307,15 @@ dat-devkit/
│ │ ├── 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
│ │ ├── rules/*.md # common rules (incl. worktree hygiene)
│ │ ├── hooks/*.sh # hooks + _lib.sh
│ │ ├── agents/*.md # planner, coder, tester, reviewer, security
│ │ ├── skills/ # feature, bugfix, review, audit, pr, tdd, diagnose
│ │ └── bin/ # statusline, doctor, state, usage scripts
│ │ ├── skills/ # Claude-target skills (15): align → execute → ship → maintain
│ │ │ └── _shared/ # github-access.md, context-doc.md references
│ │ └── bin/ # statusline, doctor, state, worktree, usage scripts
│ ├── codex/ # codex/gemini-target skills (same set, in codex shape)
│ │ ├── _shared/ # github-access.md, context-doc.md references
│ │ └── skills/<name>/SKILL.md
│ ├── typescript/
│ │ ├── rules/*.md # TS coding-style, type-safety, testing, security, graphql
│ │ └── hooks/ # post-write-graphql.sh + hooks-extend.json
Expand All@@ -275,8 +329,8 @@ dat-devkit/
│ └── README.md # Claude→Hermes mapping
└── plugins/
 ├── README.md
 ├── gitlab/ # /gitlab-pr skill (opt-in)
 └── notion-prd/ # /prd-authoring skill (opt-in)
 ├── gitlab/ # /gitlab-pr skill (opt-in) — skills/ for Claude, skills-codex/ for codex/gemini
 └── notion-prd/ # /prd-authoring skill (opt-in) — same shape
```

---
Expand Down

47 changes: 47 additions & 0 deletions
harness/codex/_shared/context-doc.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
# CONTEXT.md — Shared Project Language (Shared Reference)

Several skills (`/grill`, `/prd`, `/to-issues`, `/zoom-out`, `/improve-architecture`) read
and write a project-root `CONTEXT.md`. It's the kit's antidote to **verbosity and
misalignment**: a shared glossary so the agent and the codebase use the same words, which
cuts re-explanation and keeps specs/issues/reports in the project's own vocabulary.

## What it is

A short, durable, human-maintained file at the **project root** (`./CONTEXT.md`). It is
*not* documentation of how the code works — that's what the code and `/zoom-out` are for.
It's the **vocabulary and load-bearing facts** a newcomer (human or agent) needs to talk
about the project correctly.

## What goes in it

- **Domain glossary** — the project's nouns and verbs with one-line definitions. ("A
 *Tenant* is a billing account; *Members* belong to exactly one Tenant.")
- **Key concepts / invariants** — rules that are always true and easy to violate. ("All
 money is integer minor units; never floats.")
- **Module names that carry meaning** — deepened modules named during
 `/improve-architecture`, so future sessions reuse the term.
- **Pointers, not prose** — "Auth lives behind the `Session` seam; see `docs/adr/004`."

## What does NOT go in it

- File-by-file tours, call graphs, or anything that goes stale on refactor (use `/zoom-out`
 live instead).
- Secrets, credentials, or PII.
- Requirements or plans — those are `/prd` and issues.

## How skills use it

| Skill | Reads it to… | Writes to it when… |
|---|---|---|
| `/grill` | ask in the project's terms | (read-only) |
| `/prd` | spec in the project's terms | (read-only) |
| `/to-issues` | name issues in the project's terms | (read-only) |
| `/zoom-out` | explain in the project's terms | a new load-bearing term is discovered |
| `/improve-architecture` | reason about modules in the project's terms | a deepened module is named |

## Bootstrapping

If `CONTEXT.md` doesn't exist when a skill needs it, create a minimal one (title + empty
Glossary / Concepts sections) and add the terms you have. Keep it short — a CONTEXT.md
nobody maintains is worse than none. Pair it with ADRs in `docs/adr/` for *decisions*
(CONTEXT.md is for *vocabulary*).

51 changes: 51 additions & 0 deletions
harness/codex/_shared/github-access.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
# GitHub Access — Shared Reference (Codex)

Use this whenever a Codex skill needs to read or write GitHub data (PR metadata, diffs, comments, reviews). This devkit is GitHub-only and uses the `gh` CLI.

## Step 1 — Confirm `gh` is authenticated

```bash
gh auth status
```

- If it reports a logged-in account, you're ready — use `gh` commands directly.
- If it errors or says "not logged in", tell the user to run `gh auth login`
 (or set `GH_TOKEN` in their environment). Do not attempt to store tokens yourself.

## Step 2 — Common operations

```bash
# Default branch of the current repo
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name

# PR metadata (base branch matters for diffs and reviews)
gh pr view <number|url> --json number,title,baseRefName,headRefName,url

# PR diff
gh pr diff <number|url>

# Create a PR
gh pr create --title "<title>" --body "<body>" --base <default-branch>

# Comment on a PR (general note)
gh pr comment <number|url> --body "<comment>"

# Submit a review (approve / request changes / comment)
gh pr review <number|url> --comment --body "<findings>"
```

## Step 3 — API fallback

When a `gh` subcommand doesn't cover what you need, drop to the REST API via
`gh api` — it reuses the same authentication:

```bash
# Example: list review comments on a PR
gh api repos/{owner}/{repo}/pulls/<number>/comments

# Example: post an inline review comment anchored to a line
gh api repos/{owner}/{repo}/pulls/<number>/comments \
 -f body="<comment>" -f commit_id="<sha>" -f path="<file>" -F line=<n> -f side=RIGHT
```

Resolve `{owner}/{repo}` with `gh repo view --json nameWithOwner --jq .nameWithOwner`.

56 changes: 56 additions & 0 deletions
harness/codex/skills/audit/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
---
name: audit
description: Runs an OWASP Top 10 security audit (access control, cryptographic failures, injection, insecure design, misconfiguration, vulnerable components, auth failures, data integrity, logging failures, SSRF) and a dependency CVE scan against the project's package manager, then writes a PASS/FAIL report to .devkit/security-audit.md and optionally posts findings to a GitHub PR. Use when the user says "audit", "security audit", "OWASP", "compliance check", "scan dependencies", "check for vulnerabilities", or before merging.
---

# Audit Workflow

Run an OWASP Top 10 review and a package vulnerability scan.

> GitHub access: follow [`_shared/github-access.md`](../_shared/github-access.md).

> Codex note: state lives in `.devkit/`. No `devkit-state.sh` binary — bump
> `.devkit/state.json` between phases.

## Step 1 — Determine scope

- GitHub PR (number or URL) provided: fetch the diff with `gh pr diff <number|url>`.
- No PR given: use the local diff, or scan the entire project.

Initialize state:
```bash
mkdir -p .devkit
SLUG="<pr-number-or-slug>"
cat > .devkit/state.json <<JSON
{
 "workflow": "audit",
 "slug": "$SLUG",
 "current_step": 1,
 "steps": ["security", "complete"]
}
JSON
```

## Step 2 — Security

Run the audit yourself in this session:
- OWASP Top 10 checks: access control, cryptographic failures, injection,
 insecure design, misconfiguration, vulnerable components, auth failures,
 data integrity, logging failures, SSRF
- Dependency vulnerability scan: `npm audit` (Node) or `pip-audit` (Python)
- Write the report to `.devkit/security-audit.md` with findings and a
 `PASS/FAIL` verdict

Print `## AUDIT COMPLETE`. Bump `current_step` to 2.

## Step 3 — Complete

```bash
cat > .devkit/state.json <<JSON
{ "workflow": "audit", "slug": "$SLUG", "status": "complete" }
JSON
```
Print the audit summary and overall PASS/FAIL verdict.

If a PR was provided, offer to post the audit:
- `gh pr comment <number|url> --body "<audit summary>"`
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(skills): full engineering-workflow skill set + codex target + worktree support#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

datj9
wants to merge
2
commits into

base:master
Choose a base branch

from

 Open


feat(skills): full engineering-workflow skill set + codex target + worktree support
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e8bc2b3

feat(skills): complete engineering-workflow skill set + codex target …


datnguyen-ringkas Jun 12, 2026
9ffa314

Merge remote-tracking branch 'origin/master' into feat/engineering-wo…


datnguyen-ringkas Jun 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


88 changes: 71 additions & 17 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ Drop it into any repo with one command and every Claude Code session in that pro
| **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`. |
| **Skills** | 15 core | Full engineering loop — align (`/grill`, `/prd`, `/to-issues`) → execute (`/feature`, `/bugfix`, `/tdd`, `/diagnose`) → verify & ship (`/review`, `/audit`, `/pr`) → maintain (`/zoom-out`, `/improve-architecture`, `/triage`, `/handoff`, `/worktree`). |
| **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.
Expand DownExpand Up@@ -63,15 +63,17 @@ Language rules install into per-language subdirectories so they never overwrite
| 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 |
| `codex` | `.codex/AGENTS.md` + `.codex/<skill>/SKILL.md` | All rules concatenated into `AGENTS.md`; skills installed as Codex skill directories (hooks/agents are Claude-only and skipped) |
| `gemini` | `.gemini/GEMINI.md` + `.gemini/<skill>/SKILL.md` | Same concatenated-rules bundle for the Gemini CLI, with the same skill-directory layout as Codex |
| `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](harness/hermes/README.md) for the full mapping from the Claude-Code target to Hermes. |

```bash
./install.sh typescript --target codex ~/path/to/project
./install.sh typescript --target hermes ~/path/to/project
```

Under the `codex` (and `gemini`) target, each core skill lands as `.codex/<skill>/SKILL.md` and each `--with` plugin's skills land in the same shape under `plugins/<name>/skills-codex/`. They are plain Markdown — Codex and Gemini pick them up automatically, no extra wiring needed.

### Plugins (`--with`, repeatable)

```bash
Expand DownExpand Up@@ -133,27 +135,66 @@ Project configuration lives in `.claude/devkit-plan.json`. It is created on firs
## Skills

Type the slash command in Claude Code, or just describe the task and the skill auto-triggers.
The skills compose into the full engineering loop:
**align → specify → decompose → execute → verify → ship → maintain → triage → hand off.**

### Align & specify

| Skill | Use it for |
|---|---|
| `/grill` | Relentless one-question-at-a-time interview that stress-tests a plan **before** any code — the fix for agent misalignment. |
| `/prd` | Synthesize the conversation (ideally after `/grill`) into `.devkit/prd.md`; optionally open it as a GitHub issue. |
| `/to-issues` | Decompose a PRD/plan into many thin **vertical-slice** GitHub issues, labeled AFK/HITL and sequenced by dependency. |

### Execute

| 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. |
| `/tdd` | Test-first workflow: red → green → refactor, enforcing coverage. |
| `/diagnose` | Systematic root-cause investigation for a failing test, flaky behavior, or confusing error. |

### Verify & ship

| Skill | Use it for |
|---|---|
| `/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. |

### Understand & maintain

| Skill | Use it for |
|---|---|
| `/zoom-out` | Map an unfamiliar area by going **up** a layer; persists durable domain terms to a project-root `CONTEXT.md`. |
| `/improve-architecture` | Find shallow-module / ball-of-mud friction, propose deepening refactors, optionally record an ADR. |
| `/triage` | Move GitHub issues through a triage state machine into actionable, labeled work with agent briefs. |
| `/handoff` | Compact the session into a temp-dir handoff doc a fresh agent can pick up cold. |
| `/worktree` | Create a git worktree and install the harness into it — parallel work with isolated workflow state. |

```text
/grill I want to add multi-tenant billing
/prd
/to-issues
/feature add a rate limiter to the login endpoint
/bugfix login returns 500 when email is missing
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/review
/audit
/pr
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/zoom-out how does the payments subsystem fit together
/improve-architecture the order module is a mess
/triage
/handoff finish the billing slice next session
/worktree make a worktree for the billing refactor
```

Several skills share a project-root **`CONTEXT.md`** — a small, human-maintained glossary
of the project's domain language — so specs, issues, and reviews all speak your terms
instead of generic boilerplate.

---

## Hooks
Expand DownExpand Up@@ -185,12 +226,18 @@ Plugins are optional, self-contained integrations with a specific tool, kept out

```
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 # manifest
├── skills/<skill>/SKILL.md # Claude target: skills it adds
├── skills-codex/<skill>/SKILL.md# codex / gemini targets: same skills, codex-shaped
├── rules/*.md # (optional) rules it adds
└── hooks/*.sh # (optional) hooks it adds
```

Skills are duplicated per target because Claude skills use the Claude frontmatter
(`disable-model-invocation`, model routing, sub-agent dispatch) which doesn't
apply to Codex/Gemini. The `codex` and `gemini` versions are stripped down to
plain Markdown that any tool can pick up.

### `plugin.json` schema

```json
Expand DownExpand Up@@ -218,6 +265,9 @@ plugins/<name>/
| `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 |

Each plugin ships both a Claude version (`skills/<name>/SKILL.md`) and a
codex/gemini version (`skills-codex/<name>/SKILL.md`).

### Writing your own

1. Create `plugins/<name>/plugin.json` with the schema above.
Expand DownExpand Up@@ -257,11 +307,15 @@ dat-devkit/
│ │ ├── 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
│ │ ├── rules/*.md # common rules (incl. worktree hygiene)
│ │ ├── hooks/*.sh # hooks + _lib.sh
│ │ ├── agents/*.md # planner, coder, tester, reviewer, security
│ │ ├── skills/ # feature, bugfix, review, audit, pr, tdd, diagnose
│ │ └── bin/ # statusline, doctor, state, usage scripts
│ │ ├── skills/ # Claude-target skills (15): align → execute → ship → maintain
│ │ │ └── _shared/ # github-access.md, context-doc.md references
│ │ └── bin/ # statusline, doctor, state, worktree, usage scripts
│ ├── codex/ # codex/gemini-target skills (same set, in codex shape)
│ │ ├── _shared/ # github-access.md, context-doc.md references
│ │ └── skills/<name>/SKILL.md
│ ├── typescript/
│ │ ├── rules/*.md # TS coding-style, type-safety, testing, security, graphql
│ │ └── hooks/ # post-write-graphql.sh + hooks-extend.json
Expand All@@ -275,8 +329,8 @@ dat-devkit/
│ └── README.md # Claude→Hermes mapping
└── plugins/
 ├── README.md
 ├── gitlab/ # /gitlab-pr skill (opt-in)
 └── notion-prd/ # /prd-authoring skill (opt-in)
 ├── gitlab/ # /gitlab-pr skill (opt-in) — skills/ for Claude, skills-codex/ for codex/gemini
 └── notion-prd/ # /prd-authoring skill (opt-in) — same shape
```

---
Expand Down

47 changes: 47 additions & 0 deletions
harness/codex/_shared/context-doc.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
# CONTEXT.md — Shared Project Language (Shared Reference)

Several skills (`/grill`, `/prd`, `/to-issues`, `/zoom-out`, `/improve-architecture`) read
and write a project-root `CONTEXT.md`. It's the kit's antidote to **verbosity and
misalignment**: a shared glossary so the agent and the codebase use the same words, which
cuts re-explanation and keeps specs/issues/reports in the project's own vocabulary.

## What it is

A short, durable, human-maintained file at the **project root** (`./CONTEXT.md`). It is
*not* documentation of how the code works — that's what the code and `/zoom-out` are for.
It's the **vocabulary and load-bearing facts** a newcomer (human or agent) needs to talk
about the project correctly.

## What goes in it

- **Domain glossary** — the project's nouns and verbs with one-line definitions. ("A
 *Tenant* is a billing account; *Members* belong to exactly one Tenant.")
- **Key concepts / invariants** — rules that are always true and easy to violate. ("All
 money is integer minor units; never floats.")
- **Module names that carry meaning** — deepened modules named during
 `/improve-architecture`, so future sessions reuse the term.
- **Pointers, not prose** — "Auth lives behind the `Session` seam; see `docs/adr/004`."

## What does NOT go in it

- File-by-file tours, call graphs, or anything that goes stale on refactor (use `/zoom-out`
 live instead).
- Secrets, credentials, or PII.
- Requirements or plans — those are `/prd` and issues.

## How skills use it

| Skill | Reads it to… | Writes to it when… |
|---|---|---|
| `/grill` | ask in the project's terms | (read-only) |
| `/prd` | spec in the project's terms | (read-only) |
| `/to-issues` | name issues in the project's terms | (read-only) |
| `/zoom-out` | explain in the project's terms | a new load-bearing term is discovered |
| `/improve-architecture` | reason about modules in the project's terms | a deepened module is named |

## Bootstrapping

If `CONTEXT.md` doesn't exist when a skill needs it, create a minimal one (title + empty
Glossary / Concepts sections) and add the terms you have. Keep it short — a CONTEXT.md
nobody maintains is worse than none. Pair it with ADRs in `docs/adr/` for *decisions*
(CONTEXT.md is for *vocabulary*).

51 changes: 51 additions & 0 deletions
harness/codex/_shared/github-access.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
# GitHub Access — Shared Reference (Codex)

Use this whenever a Codex skill needs to read or write GitHub data (PR metadata, diffs, comments, reviews). This devkit is GitHub-only and uses the `gh` CLI.

## Step 1 — Confirm `gh` is authenticated

```bash
gh auth status
```

- If it reports a logged-in account, you're ready — use `gh` commands directly.
- If it errors or says "not logged in", tell the user to run `gh auth login`
 (or set `GH_TOKEN` in their environment). Do not attempt to store tokens yourself.

## Step 2 — Common operations

```bash
# Default branch of the current repo
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name

# PR metadata (base branch matters for diffs and reviews)
gh pr view <number|url> --json number,title,baseRefName,headRefName,url

# PR diff
gh pr diff <number|url>

# Create a PR
gh pr create --title "<title>" --body "<body>" --base <default-branch>

# Comment on a PR (general note)
gh pr comment <number|url> --body "<comment>"

# Submit a review (approve / request changes / comment)
gh pr review <number|url> --comment --body "<findings>"
```

## Step 3 — API fallback

When a `gh` subcommand doesn't cover what you need, drop to the REST API via
`gh api` — it reuses the same authentication:

```bash
# Example: list review comments on a PR
gh api repos/{owner}/{repo}/pulls/<number>/comments

# Example: post an inline review comment anchored to a line
gh api repos/{owner}/{repo}/pulls/<number>/comments \
 -f body="<comment>" -f commit_id="<sha>" -f path="<file>" -F line=<n> -f side=RIGHT
```

Resolve `{owner}/{repo}` with `gh repo view --json nameWithOwner --jq .nameWithOwner`.

56 changes: 56 additions & 0 deletions
harness/codex/skills/audit/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
---
name: audit
description: Runs an OWASP Top 10 security audit (access control, cryptographic failures, injection, insecure design, misconfiguration, vulnerable components, auth failures, data integrity, logging failures, SSRF) and a dependency CVE scan against the project's package manager, then writes a PASS/FAIL report to .devkit/security-audit.md and optionally posts findings to a GitHub PR. Use when the user says "audit", "security audit", "OWASP", "compliance check", "scan dependencies", "check for vulnerabilities", or before merging.
---

# Audit Workflow

Run an OWASP Top 10 review and a package vulnerability scan.

> GitHub access: follow [`_shared/github-access.md`](../_shared/github-access.md).

> Codex note: state lives in `.devkit/`. No `devkit-state.sh` binary — bump
> `.devkit/state.json` between phases.

## Step 1 — Determine scope

- GitHub PR (number or URL) provided: fetch the diff with `gh pr diff <number|url>`.
- No PR given: use the local diff, or scan the entire project.

Initialize state:
```bash
mkdir -p .devkit
SLUG="<pr-number-or-slug>"
cat > .devkit/state.json <<JSON
{
 "workflow": "audit",
 "slug": "$SLUG",
 "current_step": 1,
 "steps": ["security", "complete"]
}
JSON
```

## Step 2 — Security

Run the audit yourself in this session:
- OWASP Top 10 checks: access control, cryptographic failures, injection,
 insecure design, misconfiguration, vulnerable components, auth failures,
 data integrity, logging failures, SSRF
- Dependency vulnerability scan: `npm audit` (Node) or `pip-audit` (Python)
- Write the report to `.devkit/security-audit.md` with findings and a
 `PASS/FAIL` verdict

Print `## AUDIT COMPLETE`. Bump `current_step` to 2.

## Step 3 — Complete

```bash
cat > .devkit/state.json <<JSON
{ "workflow": "audit", "slug": "$SLUG", "status": "complete" }
JSON
```
Print the audit summary and overall PASS/FAIL verdict.

If a PR was provided, offer to post the audit:
- `gh pr comment <number|url> --body "<audit summary>"`
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
feat(skills): full engineering-workflow skill set + codex target + worktree support#2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Open

datj9
wants to merge
2
commits into

base:master
Choose a base branch

from

 Open


feat(skills): full engineering-workflow skill set + codex target + worktree support
#2
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
e8bc2b3

feat(skills): complete engineering-workflow skill set + codex target …


datnguyen-ringkas Jun 12, 2026
9ffa314

Merge remote-tracking branch 'origin/master' into feat/engineering-wo…


datnguyen-ringkas Jun 12, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


88 changes: 71 additions & 17 deletions
README.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,7 +13,7 @@ Drop it into any repo with one command and every Claude Code session in that pro
| **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`. |
| **Skills** | 15 core | Full engineering loop — align (`/grill`, `/prd`, `/to-issues`) → execute (`/feature`, `/bugfix`, `/tdd`, `/diagnose`) → verify & ship (`/review`, `/audit`, `/pr`) → maintain (`/zoom-out`, `/improve-architecture`, `/triage`, `/handoff`, `/worktree`). |
| **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.
Expand DownExpand Up@@ -63,15 +63,17 @@ Language rules install into per-language subdirectories so they never overwrite
| 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 |
| `codex` | `.codex/AGENTS.md` + `.codex/<skill>/SKILL.md` | All rules concatenated into `AGENTS.md`; skills installed as Codex skill directories (hooks/agents are Claude-only and skipped) |
| `gemini` | `.gemini/GEMINI.md` + `.gemini/<skill>/SKILL.md` | Same concatenated-rules bundle for the Gemini CLI, with the same skill-directory layout as Codex |
| `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](harness/hermes/README.md) for the full mapping from the Claude-Code target to Hermes. |

```bash
./install.sh typescript --target codex ~/path/to/project
./install.sh typescript --target hermes ~/path/to/project
```

Under the `codex` (and `gemini`) target, each core skill lands as `.codex/<skill>/SKILL.md` and each `--with` plugin's skills land in the same shape under `plugins/<name>/skills-codex/`. They are plain Markdown — Codex and Gemini pick them up automatically, no extra wiring needed.

### Plugins (`--with`, repeatable)

```bash
Expand DownExpand Up@@ -133,27 +135,66 @@ Project configuration lives in `.claude/devkit-plan.json`. It is created on firs
## Skills

Type the slash command in Claude Code, or just describe the task and the skill auto-triggers.
The skills compose into the full engineering loop:
**align → specify → decompose → execute → verify → ship → maintain → triage → hand off.**

### Align & specify

| Skill | Use it for |
|---|---|
| `/grill` | Relentless one-question-at-a-time interview that stress-tests a plan **before** any code — the fix for agent misalignment. |
| `/prd` | Synthesize the conversation (ideally after `/grill`) into `.devkit/prd.md`; optionally open it as a GitHub issue. |
| `/to-issues` | Decompose a PRD/plan into many thin **vertical-slice** GitHub issues, labeled AFK/HITL and sequenced by dependency. |

### Execute

| 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. |
| `/tdd` | Test-first workflow: red → green → refactor, enforcing coverage. |
| `/diagnose` | Systematic root-cause investigation for a failing test, flaky behavior, or confusing error. |

### Verify & ship

| Skill | Use it for |
|---|---|
| `/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. |

### Understand & maintain

| Skill | Use it for |
|---|---|
| `/zoom-out` | Map an unfamiliar area by going **up** a layer; persists durable domain terms to a project-root `CONTEXT.md`. |
| `/improve-architecture` | Find shallow-module / ball-of-mud friction, propose deepening refactors, optionally record an ADR. |
| `/triage` | Move GitHub issues through a triage state machine into actionable, labeled work with agent briefs. |
| `/handoff` | Compact the session into a temp-dir handoff doc a fresh agent can pick up cold. |
| `/worktree` | Create a git worktree and install the harness into it — parallel work with isolated workflow state. |

```text
/grill I want to add multi-tenant billing
/prd
/to-issues
/feature add a rate limiter to the login endpoint
/bugfix login returns 500 when email is missing
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/review
/audit
/pr
/tdd parse ISO-8601 durations
/diagnose why does the cache test fail only in CI
/zoom-out how does the payments subsystem fit together
/improve-architecture the order module is a mess
/triage
/handoff finish the billing slice next session
/worktree make a worktree for the billing refactor
```

Several skills share a project-root **`CONTEXT.md`** — a small, human-maintained glossary
of the project's domain language — so specs, issues, and reviews all speak your terms
instead of generic boilerplate.

---

## Hooks
Expand DownExpand Up@@ -185,12 +226,18 @@ Plugins are optional, self-contained integrations with a specific tool, kept out

```
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 # manifest
├── skills/<skill>/SKILL.md # Claude target: skills it adds
├── skills-codex/<skill>/SKILL.md# codex / gemini targets: same skills, codex-shaped
├── rules/*.md # (optional) rules it adds
└── hooks/*.sh # (optional) hooks it adds
```

Skills are duplicated per target because Claude skills use the Claude frontmatter
(`disable-model-invocation`, model routing, sub-agent dispatch) which doesn't
apply to Codex/Gemini. The `codex` and `gemini` versions are stripped down to
plain Markdown that any tool can pick up.

### `plugin.json` schema

```json
Expand DownExpand Up@@ -218,6 +265,9 @@ plugins/<name>/
| `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 |

Each plugin ships both a Claude version (`skills/<name>/SKILL.md`) and a
codex/gemini version (`skills-codex/<name>/SKILL.md`).

### Writing your own

1. Create `plugins/<name>/plugin.json` with the schema above.
Expand DownExpand Up@@ -257,11 +307,15 @@ dat-devkit/
│ │ ├── 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
│ │ ├── rules/*.md # common rules (incl. worktree hygiene)
│ │ ├── hooks/*.sh # hooks + _lib.sh
│ │ ├── agents/*.md # planner, coder, tester, reviewer, security
│ │ ├── skills/ # feature, bugfix, review, audit, pr, tdd, diagnose
│ │ └── bin/ # statusline, doctor, state, usage scripts
│ │ ├── skills/ # Claude-target skills (15): align → execute → ship → maintain
│ │ │ └── _shared/ # github-access.md, context-doc.md references
│ │ └── bin/ # statusline, doctor, state, worktree, usage scripts
│ ├── codex/ # codex/gemini-target skills (same set, in codex shape)
│ │ ├── _shared/ # github-access.md, context-doc.md references
│ │ └── skills/<name>/SKILL.md
│ ├── typescript/
│ │ ├── rules/*.md # TS coding-style, type-safety, testing, security, graphql
│ │ └── hooks/ # post-write-graphql.sh + hooks-extend.json
Expand All@@ -275,8 +329,8 @@ dat-devkit/
│ └── README.md # Claude→Hermes mapping
└── plugins/
 ├── README.md
 ├── gitlab/ # /gitlab-pr skill (opt-in)
 └── notion-prd/ # /prd-authoring skill (opt-in)
 ├── gitlab/ # /gitlab-pr skill (opt-in) — skills/ for Claude, skills-codex/ for codex/gemini
 └── notion-prd/ # /prd-authoring skill (opt-in) — same shape
```

---
Expand Down

47 changes: 47 additions & 0 deletions
harness/codex/_shared/context-doc.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
# CONTEXT.md — Shared Project Language (Shared Reference)

Several skills (`/grill`, `/prd`, `/to-issues`, `/zoom-out`, `/improve-architecture`) read
and write a project-root `CONTEXT.md`. It's the kit's antidote to **verbosity and
misalignment**: a shared glossary so the agent and the codebase use the same words, which
cuts re-explanation and keeps specs/issues/reports in the project's own vocabulary.

## What it is

A short, durable, human-maintained file at the **project root** (`./CONTEXT.md`). It is
*not* documentation of how the code works — that's what the code and `/zoom-out` are for.
It's the **vocabulary and load-bearing facts** a newcomer (human or agent) needs to talk
about the project correctly.

## What goes in it

- **Domain glossary** — the project's nouns and verbs with one-line definitions. ("A
 *Tenant* is a billing account; *Members* belong to exactly one Tenant.")
- **Key concepts / invariants** — rules that are always true and easy to violate. ("All
 money is integer minor units; never floats.")
- **Module names that carry meaning** — deepened modules named during
 `/improve-architecture`, so future sessions reuse the term.
- **Pointers, not prose** — "Auth lives behind the `Session` seam; see `docs/adr/004`."

## What does NOT go in it

- File-by-file tours, call graphs, or anything that goes stale on refactor (use `/zoom-out`
 live instead).
- Secrets, credentials, or PII.
- Requirements or plans — those are `/prd` and issues.

## How skills use it

| Skill | Reads it to… | Writes to it when… |
|---|---|---|
| `/grill` | ask in the project's terms | (read-only) |
| `/prd` | spec in the project's terms | (read-only) |
| `/to-issues` | name issues in the project's terms | (read-only) |
| `/zoom-out` | explain in the project's terms | a new load-bearing term is discovered |
| `/improve-architecture` | reason about modules in the project's terms | a deepened module is named |

## Bootstrapping

If `CONTEXT.md` doesn't exist when a skill needs it, create a minimal one (title + empty
Glossary / Concepts sections) and add the terms you have. Keep it short — a CONTEXT.md
nobody maintains is worse than none. Pair it with ADRs in `docs/adr/` for *decisions*
(CONTEXT.md is for *vocabulary*).

51 changes: 51 additions & 0 deletions
harness/codex/_shared/github-access.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
# GitHub Access — Shared Reference (Codex)

Use this whenever a Codex skill needs to read or write GitHub data (PR metadata, diffs, comments, reviews). This devkit is GitHub-only and uses the `gh` CLI.

## Step 1 — Confirm `gh` is authenticated

```bash
gh auth status
```

- If it reports a logged-in account, you're ready — use `gh` commands directly.
- If it errors or says "not logged in", tell the user to run `gh auth login`
 (or set `GH_TOKEN` in their environment). Do not attempt to store tokens yourself.

## Step 2 — Common operations

```bash
# Default branch of the current repo
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name

# PR metadata (base branch matters for diffs and reviews)
gh pr view <number|url> --json number,title,baseRefName,headRefName,url

# PR diff
gh pr diff <number|url>

# Create a PR
gh pr create --title "<title>" --body "<body>" --base <default-branch>

# Comment on a PR (general note)
gh pr comment <number|url> --body "<comment>"

# Submit a review (approve / request changes / comment)
gh pr review <number|url> --comment --body "<findings>"
```

## Step 3 — API fallback

When a `gh` subcommand doesn't cover what you need, drop to the REST API via
`gh api` — it reuses the same authentication:

```bash
# Example: list review comments on a PR
gh api repos/{owner}/{repo}/pulls/<number>/comments

# Example: post an inline review comment anchored to a line
gh api repos/{owner}/{repo}/pulls/<number>/comments \
 -f body="<comment>" -f commit_id="<sha>" -f path="<file>" -F line=<n> -f side=RIGHT
```

Resolve `{owner}/{repo}` with `gh repo view --json nameWithOwner --jq .nameWithOwner`.

56 changes: 56 additions & 0 deletions
harness/codex/skills/audit/SKILL.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
---
name: audit
description: Runs an OWASP Top 10 security audit (access control, cryptographic failures, injection, insecure design, misconfiguration, vulnerable components, auth failures, data integrity, logging failures, SSRF) and a dependency CVE scan against the project's package manager, then writes a PASS/FAIL report to .devkit/security-audit.md and optionally posts findings to a GitHub PR. Use when the user says "audit", "security audit", "OWASP", "compliance check", "scan dependencies", "check for vulnerabilities", or before merging.
---

# Audit Workflow

Run an OWASP Top 10 review and a package vulnerability scan.

> GitHub access: follow [`_shared/github-access.md`](../_shared/github-access.md).

> Codex note: state lives in `.devkit/`. No `devkit-state.sh` binary — bump
> `.devkit/state.json` between phases.

## Step 1 — Determine scope

- GitHub PR (number or URL) provided: fetch the diff with `gh pr diff <number|url>`.
- No PR given: use the local diff, or scan the entire project.

Initialize state:
```bash
mkdir -p .devkit
SLUG="<pr-number-or-slug>"
cat > .devkit/state.json <<JSON
{
 "workflow": "audit",
 "slug": "$SLUG",
 "current_step": 1,
 "steps": ["security", "complete"]
}
JSON
```

## Step 2 — Security

Run the audit yourself in this session:
- OWASP Top 10 checks: access control, cryptographic failures, injection,
 insecure design, misconfiguration, vulnerable components, auth failures,
 data integrity, logging failures, SSRF
- Dependency vulnerability scan: `npm audit` (Node) or `pip-audit` (Python)
- Write the report to `.devkit/security-audit.md` with findings and a
 `PASS/FAIL` verdict

Print `## AUDIT COMPLETE`. Bump `current_step` to 2.

## Step 3 — Complete

```bash
cat > .devkit/state.json <<JSON
{ "workflow": "audit", "slug": "$SLUG", "status": "complete" }
JSON
```
Print the audit summary and overall PASS/FAIL verdict.

If a PR was provided, offer to post the audit:
- `gh pr comment <number|url> --body "<audit summary>"`
Loading