Agent DevKit: A Practical Workflow for AI Coding Agents

AI coding agents are good at writing code. They are much less reliable at understanding an existing codebase, preserving team decisions, and keeping documentation true after the change ships.

Agent DevKit is a small, dependency-free workflow for making AI-assisted development more predictable. It gives coding agents a repeatable way to understand a repository, plan changes, implement them, verify the result, and maintain a source-grounded wiki.

The goal is not to make the agent autonomous. The goal is to make the agent useful without making the team give up control.

The problem it solves

Without a workflow, an agent often:

• starts coding before it understands the current architecture
• reads too many unrelated files and wastes context
• invents behavior that is not present in the source
• creates a plan in chat and loses it later
• marks documentation as current without checking the code
• treats a bug symptom instead of tracing the shared root cause
• produces a large diff when a smaller change would work

Agent DevKit turns these failure modes into explicit steps and review points.

What is included

The repository ships focused skills rather than one large framework:

• setup-codebase — create project guidance, documentation structure, and ignore rules
• read-codebase-context — load the smallest relevant project context before editing
• brainstorm-feature — clarify a feature and write a design spec when the change is architectural
• plan-feature — turn an approved design into an executable implementation plan
• estimate-feature — estimate plan tasks separately when the team needs delivery sizing
• implement-task — implement the approved plan with narrow scope
• systematic-debugging — investigate bugs scientifically and fix the root cause
• review-and-verify — review correctness, scope, tests, stale documentation, and unnecessary complexity
• document-wiki — create or refresh source-verified project documentation
• setup-openez — optionally connect OpenEZ code intelligence

Each skill is plain Markdown. Teams can copy the skills into .agents/skills and use them with their preferred coding agent.

A workflow that scales from small fixes to architecture

Not every task needs the same ceremony.

Bounded task

For a small, well-understood change:

1. Read the relevant context.
2. Make a short design decision in chat.
3. Implement the smallest correct change.
4. Review and verify it.
5. Update the wiki if behavior changed.

No unnecessary spec or plan file is created.

Architectural task

For a change that affects public APIs, database schema, dependencies, cross-domain behavior, or many files:

1. Brainstorm and clarify the design.
2. Save the approved design under docs/agent-devkit/specs/.
3. Create an execution plan under docs/agent-devkit/plans/.
4. Add an explicit approval gate to the plan.
5. Implement only after the plan is approved.
6. Review, verify, and update the wiki.

The spec and plan are process artifacts. They are intentionally separate from docs/llm/, which describes behavior that already exists and has been verified against source and tests.

Bug fix

Bug work uses a different path:

1. Reproduce the failure.
2. Trace all callers and the complete data flow.
3. Form one testable root-cause hypothesis.
4. Add the smallest regression check.
5. Fix the shared root cause, not only the reported endpoint.
6. Review the resulting diff and update documentation if behavior changed.

Brownfield-first project wiki

Agent DevKit is designed for repositories that already contain code.

The document-wiki skill starts with a baseline and then adds deep coverage where it helps. Wiki pages are stored as normal Markdown under:

docs/llm/
├── AGENTS.md
├── INDEX.md
├── LOG.md
├── architecture/
├── domains/
├── workflows/
├── integrations/
├── operations/
└── decisions/

Folders are created only when a real page needs them. A small project may only need architecture/ and workflows/; a larger system can document domains, integrations, operations, and decisions without forcing every project into the same shape.

Pages use normal Markdown headings and Obsidian wikilinks such as:

See [[workflows/authentication]] and [[integrations/stripe-billing]].

That means the wiki can be opened directly in Obsidian. The INDEX.md file is the entry point, and LOG.md records page-level provenance and refresh history.

The wiki is not allowed to become a second source of truth. Source code and tests remain authoritative. If evidence is missing, the page records an open question or omits the claim.

OpenEZ: optional code intelligence

Agent DevKit can work with direct file reads alone. For larger repositories, it can optionally use OpenEZ through MCP.

OpenEZ provides retrieval and relationship tools such as:

• code_query for semantic code search
• code_context for symbol and file context
• graph_neighbors for callers, dependencies, and cross-module relationships
• memory_recall and memory_write for durable technical decisions

This is useful for tracing a feature through controllers, services, persistence, jobs, external adapters, and tests.

It is more accurate to call this a code-intelligence retrieval layer than a complete product RAG system. The practical benefit is the same: the agent receives targeted, relevant context instead of repeatedly dumping the whole repository into the conversation.

OpenEZ setup is optional and user-approved. The workflow never installs or enables a remote service silently.

Why this can save tokens

Token savings come from reducing repeated, irrelevant exploration:

• read the wiki index before scanning the repository
• open only the pages and source paths relevant to the task
• use semantic retrieval for symbols and callers when available
• keep tool output bounded
• reuse verified project context across sessions
• avoid asking the agent to rediscover the same architecture every time

Agent DevKit does not promise a fixed percentage reduction. The saving depends on repository size, wiki coverage, and how much context the task actually needs. The rule is simple: retrieve the smallest context that is sufficient, then verify important claims against source and tests.

A few opinionated guardrails

The workflow deliberately keeps some boundaries explicit:

• the agent does not commit code on behalf of the user
• “implement it” after a spec does not automatically approve a high-impact plan
• plans with public API, schema, dependency, CI, or broad file impact require a separate plan approval
• generated wiki pages must list the sources they inspected
• uncommitted source changes can make a wiki page stale
• review includes an over-engineering pass: delete unnecessary code before adding abstractions
• existing data is preserved unless deletion is explicitly required

These are small rules, but they prevent expensive mistakes.

Getting started

Install the skills with the Agent Skills CLI:

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

Replace claude-code with the agent target you use. If the CLI is not available, clone the repository and copy the skills manually:

git clone https://github.com/asta-nguyen/agent-devkit.git
cp -R agent-devkit/skills/* .agents/skills/

Then start with:

1. setup-codebase for a new repository
2. read-codebase-context before a feature or bug task
3. brainstorm-feature and plan-feature for architectural work
4. implement-task only after the approval gate is satisfied
5. review-and-verify before calling the work complete
6. document-wiki whenever verified behavior changes

Final take

Agent DevKit is a lightweight operating workflow for teams using AI coding agents on real codebases.

It combines:

• focused Markdown skills
• explicit feature and bug workflows
• approval gates for high-impact plans
• an Obsidian-friendly, source-grounded wiki
• optional OpenEZ semantic and graph-based code retrieval
• minimality rules that resist over-engineering

The result is not “AI writes everything.” It is a development process where AI can move faster while the team can still understand, review, and trust the changes.

Learn more at github.com/asta-nguyen/agent-devkit.