agent-devkit

Tiếng Việt

Task-driven coding skills: the agent reads the repository, clarifies material decisions, implements, checks, updates affected documentation, and reviews.

Understand the task → implement → review and finish.

Version 0.10.0 — see changes and release notes.

You do not need to memorize skill names. Describe the task:

Implement this task end to end. Clarify unresolved behavior and edge cases,
summarize the plan before approval, then code, verify, update affected docs,
and review. Ask when a material decision is needed. Do not commit.

A clear, small change can skip approval only when the request names the exact file or symbol and result, impact checks keep every caller, test, config, and wiki page in scope, it touches no public API, schema, dependency, CI, security boundary, or data-loss risk, and it is not a bug. Otherwise use the Bounded feature flow: a short chat solution and approval. Architectural work uses design.md and tasks.md with one joint approval. The agent calls the next skill itself. Detailed guidance: English · Vietnamese.

Core capabilities

Capability	What it gives the agent
Semantic / RAG-style code retrieval	Optional OpenEZ semantic search, graph traversal, and caller analysis; direct source remains authoritative.
Spec- and plan-driven delivery	Approved designs, behavior-level plans with named test cases, persisted impact maps, edge-case coverage, and explicit implementation gates.
Token-aware context management	Focused source retrieval, compact handoffs, and evidence instead of dumping the whole repository into context.
Evidence-first verification	Fresh tests/checks, precise path:line findings, and failing cannot verify gaps when proof is missing.
Delegated tracing and review	No-edit briefs ask host subagents for code traces or independent diff review; the parent verifies evidence, while host permissions remain host-controlled.
Convention capture and enforcement	Repository-specific rules with provenance, approval, scoped precedence, and review evidence.
Whole-repository lean audit	Report-only delete, stdlib, native, yagni, and shrink findings with no auto-fix.

What it does

Coding agents need accurate, up-to-date context to work effectively. This project provides portable Markdown skills for bootstrapping repository context, retrieving code relationships, designing and planning changes, implementing with local conventions, debugging root causes, verifying fresh evidence, and maintaining a source-grounded LLM wiki.

Plans specify behavior and checks; implement-task writes code. An exact, low-risk, non-bug change may proceed without waiting for design approval only after brainstorm-feature verifies its named scope and impact map.

Skills

Skills are prompt-driven Markdown playbooks under skills/. Each skill has a name, description, and step-by-step instructions. document-wiki also bundles a dependency-free validator for published docs/llm/ content.

Using the skills

Skills are portable folders, not application dependencies. To use them, make the skills/<name>/ folder visible to the agent's skill loader, then invoke the skill by name or ask for the task it describes. SKILL.md is the required file.

Harness packaging

This repository is the source tree for developing skills. Keep canonical skill files under skills/; do not add an installation mirror under .agents/skills/.

• Codex: .codex-plugin/ and hooks/hooks.json provide the optional plugin integration and SessionStart bootstrap.
• Claude Code: .claude-plugin/ points to hooks/claude-codex-hooks.json and reuses the same skills/ and script.
• Cursor: .cursor-plugin/ points to hooks/cursor-hooks.json and reuses the same skills/ tree and script.
• Devin CLI: .devin-plugin/ packages the same skills/ tree as a Devin plugin; root hooks.json runs the shared SessionStart bootstrap. Local CLI/Desktop plugin hooks are best-effort and fail-open; check for AGENT-DEVKIT:ACTIVE, and invoke using-devkit manually if bootstrap is absent.
• OpenCode: .opencode/plugins/agent-devkit.js registers the canonical skills/ tree and bootstraps using-devkit through OpenCode's plugin API.

The target project, not this source repository, owns its AGENTS.md and .agents/skills/ installation files.

Devin also loads the plugin's root AGENTS.md as an always-on rule. Its development contract is scoped to the agent-devkit source repository and does not impose those repository-specific policies on consumer projects.

This repo also exposes the Codex plugin through the repo-scoped marketplace at .agents/plugins/marketplace.json. Users can install it directly from GitHub.

For a team install, use the same published release tag for Codex, Claude Code, and OpenCode. The examples use v0.10.0; update all three refs together to a release that contains the changes the team will use.

codex plugin marketplace add asta-nguyen/agent-devkit --ref v0.10.0
codex plugin add agent-devkit@agent-devkit

To move to a newer release, see Upgrade.

Claude Code users can install the same plugin from the Claude marketplace:

claude plugin marketplace add asta-nguyen/agent-devkit#v0.10.0
claude plugin install agent-devkit@agent-devkit --scope user

To move to a newer release, see Upgrade.

Cursor users can import the repository through a Cursor team marketplace, or test it locally by placing this repository under ~/.cursor/plugins/local/agent-devkit and reloading the Cursor window.

Devin CLI users can install the plugin directly from GitHub. devin plugins install has no tag option (# in its source selects a subdirectory), so a direct install follows the default branch. Devin's manifest dependency entries accept ref or sha (Devin plugin docs); this repository does not document that route.

devin plugins install asta-nguyen/agent-devkit

OpenCode uses its own plugin install. In the target project's opencode.json, add the Git-backed plugin:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "agent-devkit@git+https://github.com/asta-nguyen/agent-devkit.git#v0.10.0"
  ]
}

Restart OpenCode after changing the config. The plugin registers the bundled skills and injects using-devkit into the first user message. To move to a newer release, see Upgrade. The current adapter targets OpenCode 1.x; OpenCode V2 will require its separate plugin API adapter when V2 becomes the supported release.

For a project that discovers repository-local skills from .agents/skills, run this from the target project and replace the source path with this clone:

mkdir -p .agents/skills
cp -R /path/to/agent-devkit/skills/. .agents/skills/
find .agents/skills -name SKILL.md -print

Upgrade

Pick the new release tag and move every pinned client to it together. Replace vX.Y.Z with that tag.

Client	Pinned to a tag	Following the default branch
Codex	Set ref = "vX.Y.Z" under [marketplaces.agent-devkit] in ~/.codex/config.toml, then run codex plugin marketplace upgrade agent-devkit	codex plugin marketplace upgrade agent-devkit
Claude Code	claude plugin marketplace remove agent-devkit claude plugin marketplace add asta-nguyen/agent-devkit#vX.Y.Z claude plugin install agent-devkit@agent-devkit --scope user	claude plugin marketplace update agent-devkit claude plugin update agent-devkit@agent-devkit
OpenCode	Change #vX.Y.Z in the opencode.json plugin entry	Delete the URL's folder under ~/.cache/opencode/packages/
Devin CLI	Not supported by devin plugins install	devin plugins update agent-devkit
Cursor	Check out the tag in the local copy, or follow the team marketplace's update flow	Pull the local copy, or Refresh a GitHub-imported team marketplace (manual, or Auto Refresh; see Cursor plugin docs)

Then start a new Codex thread, restart Claude Code (or run /reload-plugins), restart OpenCode, start a new Devin session, or reload the Cursor window. Check the result with codex plugin list, claude plugin list, or devin plugins list, and look for AGENT-DEVKIT:ACTIVE in a new session.

• Codex and Claude Code refuse to add agent-devkit again from a different ref while it is still configured. Their upgrade/update commands refresh the current ref but never change it.
• Removing the Claude marketplace uninstalls its plugin, so reinstall at the same scope. See Claude Code's plugin management guide.
• Checked with Codex CLI 0.163.0, Claude Code 2.1.301, and Devin CLI 3000.11.92 (v0.8.0 → v0.9.0); the OpenCode cache and Cursor steps were not re-run.

Install with Agent Skills CLI

This repository follows the open Agent Skills layout: each skill is a skills/<name>/SKILL.md with YAML frontmatter containing name and description. No skill.json is required.

Install all skills into Claude Code with:

npx skills add asta-nguyen/agent-devkit -a claude-code

This follows the repository's default branch. For a version-pinned team installation, use the native plugin instructions above.

The public repository is currently asta-nguyen/agent-devkit; the shorthand asta/agent-devkit is not the repository's current GitHub path.

Install the whole set because the workflow skills reference each other; keep each skill folder intact so its supporting references are installed. Treat the copies as managed files: do not customize them in the target project. Updating overwrites same-named skills, and retired skill folders must be removed manually. Start a fresh agent session after copying so its skill list is reloaded.

The shortest routing guide is:

using-devkit                          # choose the right workflow skill
setup-codebase                         # first visit to a repo missing context
setup-openez                           # optional setup/refresh when needed and approved
read-codebase-context                  # understand code before changing it
context-handoff                        # checkpoint unfinished work before pausing
document-wiki                          # document existing app features
lean-audit                             # audit whole-repo simplicity; report only
brainstorm-feature → plan-feature      # design.md + tasks.md → one joint approval
estimate-feature                       # optional per-task AI-assisted estimate
implement-task → review-and-verify     # code, checks, affected docs, final review
systematic-debugging                   # investigate before fixing bugs

OpenEZ

OpenEZ is a separate code-intelligence MCP service. Install/index a repository and wire the clients you use, then restart those clients so their MCP tools are loaded:

openez init <repo-path>
openez index <repo-path>
openez setup codex                  # or claude / opencode

Skills use this tool-by-purpose flow:

Stage	Need	Tool
Locate	Concept or behavior	OpenEZ code_query
Locate	Approximate filename	FFF fuzzy file find
Locate	Identifier or literal	FFF grep, falling back to rg
Locate	Regex	rg
Expand	Callers and callees	OpenEZ code_context (1–2 hops)
Confirm	Dynamic or registration references	FFF multi-pattern grep, falling back to rg
Read	Large-file structure and evidence	OpenEZ code_outline, then read current source directly

Search and index results are navigation, never evidence. A plugin is optional: use one to distribute a skill, MCP server, and optional UI together; a shared SKILL.md folder is enough for the workflow itself.

Optional: FFF search

FFF adds a background watcher that updates an in-memory content index when it detects file changes, including uncommitted edits. It also provides frecency-ranked fuzzy file find, multi-pattern grep in one call, and git-aware annotations for modified, untracked, and staged files. See the official FFF README, MCP server section.

It can help in large repositories or monorepos with repeated searches, approximate filename lookups, caller/reference sweeps during review or lean-audit, or alongside OpenEZ when files changed after the last index. Costs are RAM for the content index, a background watcher, per-client MCP configuration, and a startup update check. For fff-mcp 0.11.0, --no-update-check is documented by fff-mcp --help, not the README.

OS	Install
macOS / Linux	curl -L https://dmtrkovalenko.dev/install-fff-mcp.sh | bash
Windows (PowerShell)	irm https://raw.githubusercontent.com/dmtrKovalenko/fff/main/install-mcp.ps1 | iex
macOS / Linux (Homebrew)	brew install dmtrKovalenko/fff/fff-mcp brew upgrade fff-mcp for later updates

Read the install script before piping it to a shell. For MCP registration, use an absolute binary path because desktop clients may not inherit the shell PATH: the one-line installer defaults to $HOME/.local/bin/fff-mcp, Homebrew to $(brew --prefix)/bin/fff-mcp, and Windows prints its path.

The official Codex example is:

codex mcp add fff -- "$(brew --prefix)/bin/fff-mcp"

This creates an entry in ~/.codex/config.toml like:

[mcp_servers.fff]
command = "/absolute/path/to/fff-mcp"

To skip the startup update check, add this separately by hand; it is not produced by the command above:

args = ["--no-update-check"]

For other clients, follow their official docs or the installer's printed instructions; this guide does not invent client-specific snippets: Claude Code, Cursor, OpenCode, and Devin. Restart the client after setup.

In fff-mcp 0.11.0 the tools are find_files, grep, and multi_grep; the FFF README calls them fffind, ffgrep, and fff-multi-grep. These are version examples; use the connected server's tool list if names differ. Say “FFF grep” for this capability. FFF grep uses literal identifiers; regex stays with rg. Do not copy a blanket “use FFF for any search” instruction into CLAUDE.md or AGENTS.md; devkit routing remains authoritative and FFF is optional.

FFF is never required. Without it, skills use rg and reach the same results.

Bootstrap & context

Skill	Purpose
using-devkit	Route a task to the correct devkit workflow before editing.
setup-codebase	Create missing context files and capture missing repository conventions; safe to rerun when conventions are absent.
setup-openez	Ask before CLI install, existing AGENTS.md guidance, or client wiring; report CLI indexing and MCP verification separately, including an unverified MCP query when tools do not load.
read-codebase-context	Choose search by the question and trace code paths before feature work or wiki generation.
context-handoff	Save a compact evidence checkpoint when a session must pause or is approaching its context limit.

Feature development

Skill	Purpose
brainstorm-feature	Classify scope, clarify and get design approval; route Spike to investigation, Bounded to implementation, and Architectural through a change folder.
plan-feature	Write tasks.md beside design.md, summarize the plan, and present one joint approval; legacy plans keep their existing location/gate.
estimate-feature	Optionally estimate every task in an Architectural change or legacy plan in AI-assisted engineering hours.
implement-task	Run existing relevant checks before the first source edit, execute approved tasks, record progress/results, and update affected documentation before final review.
systematic-debugging	Find root cause, classify the bug, define verification, then fix bounded bugs or hand architectural bugs off for design.
review-and-verify	Iron Law: no completion claims without fresh evidence. Diff review, code review reception, red flags.

Auditing

Skill	Purpose
lean-audit	Audit a whole repository for over-engineering and bloat; report validated simplicity cuts without applying fixes.

Wiki lifecycle

Skill	Purpose
document-wiki	Automatically update affected behavior in an existing wiki during a task; standalone requests retain baseline inventory and feature selection.

Deep pages use evidence-backed folders only when needed: architecture/ for system structure, domains/ for state and requirements, workflows/ for user/operator flows, integrations/ for external systems, operations/ for jobs/cron/deployment, and decisions/ for source-backed decisions. Small repos may need only architecture/ and workflows/; empty folders are never created.

Example workflows

1. Bootstrap a new repository

setup-codebase
  → creates AGENTS.md, CLAUDE.md, docs/llm/ skeleton
  → ignores local Obsidian artifacts and .openez index data

Invoke setup-codebase in an agent session; it reads repository evidence and creates only missing, project-specific context files. It also appends missing /docs/.obsidian/, /docs/Untitled*.md, /docs/Untitled*.canvas, and .openez/ rules to .gitignore without untracking existing files.

2. Implement a feature from scratch

Clarify behavior and relevant edge cases from repository evidence
  → Architectural: write design.md + tasks.md (+ delta.md when needed)
  → Summarize goal, scope, tasks, verification, documentation, and risks
  → One joint approval
  → Code each task, check, record progress/results
  → Automatically update affected docs in an existing wiki; merge delta first
  → Final review of code and docs
  → Archive/relink after passing review; report evidence

The agent handles these actions internally. You answer material questions and approve the solution when needed. It fixes in-scope failures and reruns, then stops if the same blocker remains after a fix attempt with no new information, after three failed attempts on one blocker (then returns to brainstorm-feature), or when a fix needs out-of-scope work or a user decision. Code-task setup creates necessary missing context without silently creating a wiki. Standalone wiki setup remains separate; a planning-only request does not start code.

3. Debug a bug

systematic-debugging          → investigate and classify
  ├─ Bug question             → report evidence and stop
  ├─ Architectural            → brainstorm-feature → plan-feature
  └─ Bounded                  → verify plan → regression check → fix
                              ↓
                              review-and-verify

When implementation calls debugging for an active task, debugging returns its fix/check evidence to that task. The parent implementation owns final review and archive.

4. Document an existing app

setup-codebase             → create the missing wiki skeleton
  ↓
document-wiki              → create or refresh the domain baseline map;
                              then choose undocumented features or confirmed gaps

License

MIT — see LICENSE.