agent-devkit

Tiếng Việt

Evidence-first, spec-driven workflow toolkit for coding agents — with semantic code retrieval, token-aware context flow, and hard review gates.

Turn a vague request into a traceable change:

retrieve context → capture decisions → write spec/plan → implement → verify

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, Global Constraints, 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.
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.

Skills

Skills are prompt-driven Markdown playbooks under skills/. Each skill has a name, description, and step-by-step instructions. No scripts — the agent follows the instructions directly.

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; agents/openai.yaml only adds Codex/OpenAI UI metadata.

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

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

codex plugin marketplace add asta-nguyen/agent-devkit --ref main
codex plugin add agent-devkit@agent-devkit

Use codex plugin marketplace upgrade agent-devkit after pushing updates, then start a new Codex thread to load the new plugin version.

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

claude plugin marketplace add asta-nguyen/agent-devkit
claude plugin install agent-devkit@agent-devkit

Refresh it after pushing updates with claude plugin marketplace update agent-devkit, then run /reload-plugins in Claude Code.

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 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"
  ]
}

Restart OpenCode after changing the config. The plugin registers the bundled skills and injects using-devkit into the first user message. 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

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

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. 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                           # recommended semantic index for non-trivial repos
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      # architectural work: save spec then plan
estimate-feature                       # optional per-task AI-assisted estimate
implement-task → review-and-verify     # review, fix blockers once, review again
systematic-debugging                   # investigate before fixing bugs

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 may prefer OpenEZ MCP tools when present, but must keep a direct-source fallback. A plugin is optional: use one when you want to distribute a skill, MCP server, and optional UI together; a shared SKILL.md folder is enough for the workflow itself.

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	Install, initialize, index, and verify OpenEZ MCP connection for a repository.
read-codebase-context	Query OpenEZ and trace code paths. Used 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 task (spike/bounded/architectural), clarify scope, get design approval.
plan-feature	Save an approved architectural plan under docs/agent-devkit/plans/ with bite-sized, verifiable tasks.
estimate-feature	Optionally estimate every completed plan task in AI-assisted engineering hours.
implement-task	Execute an approved plan: trace code, make the smallest change, verify, then flag wiki coverage.
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	Build a source-grounded domain baseline, then let the user choose missing or stale feature coverage.

Deep pages use evidence-backed folders only when needed: architecture/ for system structure, domains/ for state and business rules, 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

brainstorm-feature        → clarify scope, get design approval
  ↓
docs/agent-devkit/specs/  → save approved architectural design
  ↓
setup-codebase            → new projects only: create initial contract
  ↓
plan-feature              → save ordered plan under docs/agent-devkit/plans/
  ↓
estimate-feature          → optional: save per-task ranges under docs/agent-devkit/estimates/
  ↓
implement-task            → code, verify, run checks
  ↓
review-and-verify         → pass/fail report with evidence and blockers
  ↓
fix blockers once, then review again; stop if still failing
  ↓
document-wiki             → refresh documentation for the changed feature

3. Debug a bug

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

4. Document an existing app

setup-codebase             → create the missing wiki skeleton
  ↓
document-wiki              → create or refresh the domain baseline map;
                              then choose missing/stale feature coverage

License

MIT — see LICENSE.