agentic-devkit

A model-agnostic toolkit for AI-assisted product development. One global clone supplies skills, coding rules, hooks, and stack-specific agents to Claude Code, Cursor, and Codex. Each project selects the plugins it needs. The same clone also provides a local development project manager with a CLI, dashboard, and optional MCP server.

Quick Start

Install the toolkit once per machine. devkit-install uses ~/.claude/agentic-devkit as the shared clone location; the path does not require running Claude Code. It installs the universal core skills and native subagents into Cursor, Claude Code, and Codex where supported. Cursor receives ~/.cursor/skills/, ~/.cursor/agents/, an always-on skill-selection rule, and native hooks for session updates, edit gates, and prompt feedback. In Cursor Agent, invoke a skill by its frontmatter name (for example, /devkit-coder). Claude keeps its short slash commands and Senior output style; Codex invokes skills by frontmatter name (for example, $devkit-coder).

git clone https://github.com/Blaryxoff/agentic-devkit.git ~/.claude/agentic-devkit
~/.claude/agentic-devkit/bin/devkit-install

Per project, declare the stack in .devkit/toolkit.json and generate the adapters for the agents you use:

cd my-project
~/.claude/agentic-devkit/bin/devkit-resolve --init          # write .devkit/toolkit.json
~/.claude/agentic-devkit/bin/devkit-resolve --preset=laravel-only   # same, no prompts

~/.claude/agentic-devkit/bin/devkit-install --cursor         # .cursor/ rules + skills + agents + hooks + MCP
~/.claude/agentic-devkit/bin/devkit-install --codex          # .codex/ resolved skills + AGENTS.md
~/.claude/agentic-devkit/bin/devkit-install --claude         # .claude/ stack subagents, hooks, .mcp.json

Cursor uses the same core skill bodies as the other agents. Its project adapter links only the selected stack skills, emits stack subagents, and writes project rules, MCP configuration, and hooks. Re-run it when .devkit/toolkit.json or plugin infrastructure changes; skill edits flow through the links. For Claude Code, the core skills + devkit router are already global after devkit-install; the per-project --claude run is only needed when a stack ships subagents, hooks, or MCP servers. Use /nontech to rewrite technical findings for managers or other non-technical readers without exposing codebase internals.

Core workflows cover implementation, code and business-logic review, browser QA, verification, estimation, and commit/push wrapup. Stack plugins add framework-specific conventions without putting every stack's rules into an agent's context. See Available Plugins and How It Works.

Use /showcase in Claude Code or $devkit-showcase in Codex to present completed work as a portable HTML gallery of real screenshots. The showcase workflow opens the report in a sibling agterm panel in the same session, keeping the conversation visible; outside agterm it uses a browser.

Use /lunaqa <scope> in Claude Code or $devkit-lunaqa <scope> in Codex for exhaustive local browser QA with many executor lanes on the newest available Luna, functional and visual coverage, and Luna rechecks. Each pass resolves the model from Codex's catalog for all workers; the invoking agent keeps its current model and owns planning and the final verdict. Releases need no skill edits. Explicit pass mode and environment override the defaults. The Luna preset reuses devkit-browser; ordinary browser QA retains its existing routing.

Local Projects

bin/devkit-projects starts configured services, waits for readiness, and gives agents a known URL to open. Put machine-specific definitions in this repository's Git-ignored projects.json; copy examples/projects.example.json to begin. Application secrets stay in each project's .env.

~/.claude/agentic-devkit/bin/devkit-projects status
~/.claude/agentic-devkit/bin/devkit-projects start my-app
~/.claude/agentic-devkit/bin/devkit-projects ui

The dashboard runs on http://127.0.0.1:41790. It shows service checks and logs, starts and stops projects, switches configured .env profiles, and identifies port conflicts. After confirmation it can stop an eligible same-user process occupying a configured port. A project's Git worktrees appear under its card automatically; the manager assigns reusable port slots and lets you start, stop, open, inspect, or remove eligible worktrees. Project variants and worktree service templates are configured once per parent project, not once per checkout.

Register the optional stdio MCP server to give Claude Code, Codex, or Cursor project status, start/stop, logs, profile selection, and worktree actions. The CLI offers the same serving flow when MCP is unavailable. See Local projects for configuration, MCP registration, local-domain setup, and process/worktree safeguards.

Resolver CLI

• List resolved plugin names.

~/.claude/agentic-devkit/bin/devkit-resolve

• Create .devkit/toolkit.json interactively.

~/.claude/agentic-devkit/bin/devkit-resolve --init

• Check every toolkit.json and plugin.json against schemas/, then show the resolved set. Targeted validation over the draft-07 subset those schemas use, not full JSON Schema conformance.

~/.claude/agentic-devkit/bin/devkit-resolve --validate

• List resolved plugin directories.

~/.claude/agentic-devkit/bin/devkit-resolve --dirs

• Generate tool-specific config.

~/.claude/agentic-devkit/bin/devkit-resolve --adapter=...

Supported adapters: claude, cursor, codex.

Available Plugins

Plugin	Layer	Description	Dependencies
devkit-core	core	Cross-stack shared standards: workflow, git, spec/test-case process, review conventions	(always enabled)
devkit-frontend	stack	Tool-agnostic frontend architecture and generic CSS standards	core
devkit-laravel	framework	Laravel conventions: architecture, PHP, security, Inertia integration	core
devkit-nestjs	framework	NestJS architecture, security, data, jobs, testing, and review workflows	core
devkit-nextjs	framework	Next.js App Router and React server/client boundaries	core, frontend
devkit-nuxt	framework	Nuxt conventions: SSR, data-fetching, TypeScript, BEM/SCSS workflows	core, frontend, vue
devkit-vue	framework	Vue component, composable, and state organization conventions	core, frontend
devkit-inertia	framework	Inertia.js transport, page props contracts, and form/navigation behavior	core
devkit-tailwind	styling	Tailwind CSS utility conventions and tokenization rules	core
devkit-css	styling	Modern CSS intelligence layer from css.dev	core

Example Stacks

NestJS + Next.js + Tailwind

{
  "version": 1,
  "enabled": ["devkit-nestjs", "devkit-nextjs", "devkit-tailwind"]
}

Resolves: core, frontend, nestjs, nextjs, tailwind.

Laravel + Vue + Tailwind

{
  "version": 1,
  "enabled": [
    "devkit-laravel",
    "devkit-vue",
    "devkit-inertia",
    "devkit-tailwind"
  ]
}

Resolves: core, frontend, inertia, laravel, vue, tailwind — plugins are ordered by layer, then alphabetically within a layer, so a dependency is not necessarily listed before its dependent.

Nuxt

{
  "version": 1,
  "enabled": [
    "devkit-nuxt"
  ]
}

Resolves: core, frontend, nuxt, vue

Laravel API only

{
  "version": 1,
  "enabled": [
    "devkit-laravel"
  ]
}

Resolves: core -> laravel

How It Works

1. Configure enabled plugins in .devkit/toolkit.json (or run ~/.claude/agentic-devkit/bin/devkit-resolve --init).
2. Resolver auto-includes devkit-core and transitive dependencies, validates the graph, and sorts by layer.
3. Adapter generation emits tool-specific files for the resolved set only.

Adapter	Generated files
claude	.claude/settings.json (hooks), .claude/agents/*.md (stack subagents), .claude/skills/devkit-*--* symlinks (inline stack skills), .mcp.json — core skills + router are global
cursor	.cursor/skills/<frontmatter-name>/, .cursor/agents/*.md, compact conduct-index rules, MCP config, and hooks
codex	.codex/skills/devkit-*--*/ for non-core plugins and compact conduct indexes in AGENTS.md

Generated text (conduct paths in .mdc / AGENTS.md) references the global clone at ~/.claude/agentic-devkit, so output is identical regardless of where the project lives on disk. Disabled plugins do not enter generated AI context.

devkit-install keeps only devkit-core skills globally for Codex and Cursor and removes stale global non-core links. Cursor skill links use each SKILL.md frontmatter name, because Cursor requires that name to match the folder. Their project adapters link only resolved non-core skills, including transitive dependencies; plugins such as devkit-css stay absent unless explicitly enabled. Generated AGENTS.md / .mdc rules point to one conduct index per plugin and require scope-driven loading instead of listing the full conduct corpus. Re-run the adapter after changing .devkit/toolkit.json or after a toolkit update changes generated policy/conduct routing, then start a new agent session to refresh its skill catalog. Run bin/devkit-install again to refresh copied global Claude guidance; its installed shell hooks and symlinked core skills otherwise read the updated clone directly.

The global install also merges native Codex PreToolUse coder and comment gates into ~/.codex/config.toml. Any legacy ~/.codex/hooks.json entries are migrated into that same file so Codex loads a single hook representation for the global layer. On the first apply_patch edit in a session the coder gate blocks once and instructs Codex to load devkit-coder, which pulls in the core and active-stack conduct before the edit is retried. Review and trust the hooks with /hooks after installation or changes.

Claude Code Setup

Core skills and the devkit stack-router are installed globally by devkit-install (symlinked into ~/.claude/skills/), so Claude Code auto-discovers them in every project. Core skills auto-match natively; the devkit router reads .devkit/toolkit.json and loads the matching stack skill + conduct on demand from the global clone.

Run the per-project Claude adapter only when a stack ships subagents, hooks, or MCP servers:

~/.claude/agentic-devkit/bin/devkit-install --claude --project=.

This emits .claude/agents/*.md (stack subagents), .claude/settings.json (plugin hooks), and .mcp.json — all referencing the global clone. Re-run only when the enabled-plugin set or infra files change; skill/conduct edits propagate live through the clone (kept current by the daily auto-update hook).

Repository Layout

plugins/              Convention-based plugin discovery (plugins/*/plugin.json)
  core/               skills/, conduct/, commands/ (authored Claude slash commands), hooks/, output-styles/
  frontend/
  laravel/
  nestjs/
  nextjs/
  nuxt/
  vue/
  inertia/
  tailwind/
  css/
bin/
  devkit-install      Global installer: core skills + router + subagents + slash commands + auto-update hook
  devkit-update       Timestamp-guarded `git pull --ff-only` for the global clone
  devkit-resolve      CLI: init/resolve/validate/adapter generation
  devkit-projects     Local project manager: status/start/stop/logs/profile/UI/MCP
project_manager/      Process, dashboard, and MCP implementation
adapters/
  _lib/resolve.sh     Shared resolution logic
  _lib/hooks.sh       Shared hook merge/translation helpers
  claude/generate
  cursor/generate
  codex/generate
schemas/              JSON schemas for toolkit and plugin manifests
examples/             Starter .devkit/toolkit.json presets
  projects.example.json  Generic local-project configuration
docs/runbooks/        Operational setup guides, including local projects
tests/                Shell test suite (`tests/run-all.sh`)
howto/                Developer guides (Russian)

Extending the Toolkit

Add a plugin

1. Create plugins/<name>/plugin.json.
2. Add skills at plugins/<name>/skills/<skill>/SKILL.md.
3. Add conduct docs at plugins/<name>/conduct/*.md (if applicable).
4. Verify in a consuming project with ~/.claude/agentic-devkit/bin/devkit-resolve --validate.

Add a skill

Add SKILL.md under plugins/<plugin>/skills/<skill-name>/. Adapters pick it up on next generation.

Add an adapter

See adapters/README.md.

Requirements

• jq
• python3 (3.9+ for the local project manager)
• bash 3.2+
• Optional: lsof to identify and stop external processes occupying project ports from the dashboard