# Agent Dev Toolkit

Unified multi-agent skills core with per-agent adapters. Sync the same SDD workflows, stack skills, and policy into Cursor, Claude Code, Codex, GitHub Copilot, Antigravity, OpenCode, Grok Build, ZCode ADE, Hermes, and OpenHands.

Public — clone and fork freely; no upstream contributions; GitHub Issues are bugs only (see CONTRIBUTING.md and docs/REPO_GOVERNANCE.md). Security: SECURITY.md.

Prerequisites

Supported OS: Windows, Linux (Ubuntu, Debian, and derivatives), and macOS.

Requirement	Notes
PowerShell	Windows: PowerShell 5.1+ or pwsh 7+ (recommended). Linux / macOS: pwsh 7+ only (Windows PowerShell 5.1 is not available on those OS). Install PowerShell
Git	Clone / update this repo
Target agent	At least one supported agent (see table below)

Full install steps: docs/INSTALL.md.

What this is

Layer	Role
Core	Agent Skills (`core/skills/`), policy, router, SDD contracts — agent-neutral
Adapters	Publish core into each agent’s install layout (`~/.cursor`, `~/.claude`, …)
CLI	`toolkit.ps1`, `sync-agent.ps1`, `validate-agent.ps1`
Validation	In-repo fixtures + CI smokes — no live home write required for green

Quick start

git clone https://github.com/tibursocampos/agent-dev-toolkit.git agent-dev-toolkit
cd agent-dev-toolkit

# Primary entry — interactive Smart Manager
pwsh -NoProfile -File .\scripts\toolkit.ps1

In the menu:

Sync agent — pick an agent, then live agent home (Enter = default; writes under your profile after confirm), in-repo fixture (safe), or custom path.
Validate core only — validate-core repo contracts with no home write.
Help and docs — what each action does and equivalent -Action flags.

Advanced / scripting flags (-Action, -Agent, -InstallRoot, -AllowUserHome, -Mode) and CI smokes (Invoke-CursorCiSmoke, Invoke-ClaudeCiSmoke, …): docs/INSTALL.md, docs/VALIDATION.md.
First use end-to-end: docs/guides/01-getting-started.md.

Use skills (after sync)

Open a consumer project in your agent and invoke skills by id (slash / when the host supports it):

Workflow	Invoke
Catalog (all adapters)	`help-skills` → static `CATALOG.md` + `OPERATOR.md`
Classic SDD	`sdd-spec` → `sdd-plan` → `sdd-develop`
Backlog Refine	`refine-story` → `split-story-checklist`
Stack shortcut	`developer` or `dotnet-developer` / `react-developer` / …
Orchestrated Delivery	`memory-bank-init` → `orchestrate-analyze` → `orchestrate-deliver` → `orchestrate-develop`
Greenfield ARCH	Via Orchestrated Delivery analyze: architect draft → sim confirm (not a slash skill)

Same skill call flow; internal contracts (REQ, validate, CHANGE, EVD, STATE, TRACE, selective retrieval, navigation ## Related, clarification readiness B/I, develop session gate) are gates/artifacts inside those skills — not new slash skills or a second toolkit. SQLite/FTS is out of scope as a deliverable.

Parallel specialists for multi-facet work are the router default after sync (see core/router/AGENTS.md). Chat and persisted artifacts follow the user chat language; spawn prompts stay en-US (core/skills/_shared/agents/LANGUAGE.md). Catalog: docs/SKILLS.md. Daily decision tree: docs/guides/README.md. Credits: docs/CREDITS.md.

Supported agents

id	Display name	Typical live root	Notes
`cursor`	Cursor	`~/.cursor`	Skills, `.mdc` rules, hooks; path/secrets `preToolUse` + `beforeShellExecution` (`failClosed`, GuardCommon); `agents/`
`antigravity`	Antigravity	`~/.gemini`	Official `config/*`; PreToolUse path/secrets under `config/hooks`
`claude`	Claude Code	`~/.claude`	Skills, rules `.md`, `CLAUDE.md`, settings merge; PreToolUse path/secrets deny
`codex`	Codex	`~/.codex`	Dual-root plugin + rules; PreToolUse path/secrets; `agents/.toml`; optional `-UserScope`; default plugin-only*
`copilot`	GitHub Copilot	`~/.copilot` or `.github`	`-Mode user\|repo`; hooks `version:1` `preToolUse` path/secrets
`opencode`	OpenCode	`~/.config/opencode`	Hooks = JS `tool.execute.before` path/secrets throw; `agents=true` → `InstallRoot/agents/`
`grok`	Grok Build	`~/.grok`	Native publish; PreToolUse path/secrets; `agents=true` → `InstallRoot/agents/`
`zcode`	ZCode (Z.ai ADE)	`~/.zcode`	ADE filesystem; PreToolUse path/secrets; not GLM Coding Plan
`hermes`	Hermes	`$HERMES_HOME`	Plugin + shell `agent-hooks` path/secrets; keyed `config.yaml` only; never SOUL/tokens/gateway
`openhands`	OpenHands	Project tree; user `~/.agents`	Shell `pre_tool_use` + `guard_pre_tool.sh` (fail-closed); `subagents=none`

Per-agent contract: docs/ADAPTERS.md. Shared guard: adapters/_shared/guard-rules.md + GuardCommon.ps1.

Skills preview (40)

Group	Examples
Classic SDD	`sdd-spec`, `sdd-plan`, `sdd-develop`, `read-sdd-artifact`
Backlog Refine	`refine-story`, `split-story-checklist`
Orchestrated Delivery	`memory-bank-init`, `orchestrate-analyze`, `orchestrate-deliver`, `orchestrate-develop`
Stack	`developer`, `dotnet-developer`, `java-developer`, `react-developer`, `angular-developer`, `vue-developer`, …
Docs RAG	`document-plan`, `document-implement`
Ops	`help-skills`, `code-review`, `commit`, `push`, `open-github-pr`, `test-coverage`, `repair-dotnet-build`, …

Full list: docs/SKILLS.md · agent SoT: help-skills → _shared/skills-catalog/CATALOG.md + OPERATOR.md.

Documentation

Doc	Content
docs/README.md	Documentation index / TOC
docs/overview.md	Architecture overview (RAG-friendly)
docs/INSTALL.md	Clone, sync, live home, uninstall
docs/VALIDATION.md	validate-core + keyed uninstall asserts + AllowUserHome forward + 10 agent smokes
docs/SKILLS.md	Skill catalog
docs/CREDITS.md	Third-party inspiration (Caveman, Impeccable, Spec Kit)
docs/guides/07-caveman-mode.md	Caveman default OFF, commands, levels
docs/guides/08-orchestrator-mode.md	Orchestrator charter, `orchestrator_mode`
docs/guides/README.md	Decision tree + guides
docs/ARCHITECTURE.md	Layers and install layouts
docs/ADAPTERS.md	Adapter registry and per-agent publish
CONTRIBUTING.md	Clone/fork OK; no upstream PRs; Issues = bugs only
docs/REPO_GOVERNANCE.md	OSS audiences + policy pointers
SECURITY.md	Vulnerability reporting (no invented private email)

Domains

Domain	Content
docs/domains/core.md	Skills, policy, router, SDD
docs/domains/adapters.md	Registry + adapters
docs/domains/cli-scripts.md	toolkit / sync / validate
docs/domains/validation-ci.md	Fixtures and CI workflow

Repository layout

agent-dev-toolkit/
  core/                 # skills, policy, router, SDD contracts
  adapters/             # registry.json + per-agent modules
  scripts/              # toolkit.ps1, sync-agent, validate-agent, validation/
  docs/                 # public documentation
  memory-bank/          # durable workspace map (Orchestrated Delivery Step 0)
  .github/workflows/    # validate-toolkit.yml (+ enforce-release-source.yml)
  README.md
  CONTRIBUTING.md
  SECURITY.md

Safety

Default InstallRoot is an in-repo fixture — CI never writes under %USERPROFILE%.
Live agent home requires -AllowUserHome.
Uninstall is keyed (toolkit artifacts only) for all adapters — not a wholesale home wipe. Preserves sdd/sessions and sdd/manifest.json.

CI runs validate-core, keyed uninstall asserts, Assert-SyncAllowUserHomeForward, plus all ten agent CI smokes on push/PR to develop / master / main (see .github/workflows/validate-toolkit.yml). Release PRs into master/main must come from develop (enforce-release-source.yml).

agent-dev-toolkit