ai-dev-team

AI Dev Team for Claude Code

Structured AI development workflow for Claude Code. Specs, audit findings, and research live in a Knowledge Base (Obsidian vault). Code lives in source repos. Context never gets lost between sessions.

---

Requirements

• Claude Code ≥ 2.1.32
• Codex CLI with mcp-server support — required for cross-audit, investigate, and developer-codex
• A Knowledge Base directory (any Markdown folder; Obsidian recommended)

---

Install

claude plugin marketplace add roman-karpovich/ai-dev-team
claude plugin install ai-dev-team

Two one-time manual steps after install:

1. Enable agent teams — add to ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

2. Register Codex MCP (required for cross-audit, investigate, developer-codex):

claude mcp add codex -s user -- codex mcp-server

Model and reasoning effort come from ~/.codex/config.toml:

model = "gpt-5.5"
model_reasoning_effort = "xhigh"

Restart Claude Code after install.

Project Config File (.ai-dev-team.yml)

The plugin reads an optional config file from the root of the project being worked on.

Precedence: .ai-dev-team.local.yml → .ai-dev-team.yml → memory → sibling heuristic → ask

Plugin-repo dogfood

Plugin developers working on ai-dev-team itself use a personal .ai-dev-team.local.yml (already in this repo's .gitignore). Do not commit .ai-dev-team.yml to the plugin repo; each developer has their own KB.

To set your local path, create .ai-dev-team.local.yml in the plugin root:

kb_path: /your/personal/kb/path

Consumer-repo adoption

For projects using this plugin via the marketplace:

To adopt team-shared config: create .ai-dev-team.yml in your project root and commit it:

kb_path: /absolute/path/to/knowledge-base
project: my-project-name
# Optional: project_type gates the security R-rule cluster at /feature code-audit time.
# Allowlist: smart_contract | backend | frontend | data_pipeline.
# Resolution chain: spec frontmatter → .ai-dev-team.local.yml → .ai-dev-team.yml → None.
# project_type: backend

Committing .ai-dev-team.yml makes the KB path team-shared across all developers.

To add a local override: create .ai-dev-team.local.yml and add .ai-dev-team.local.yml to your project's .gitignore. The local file takes priority over the committed .ai-dev-team.yml. Without the .gitignore entry, your private KB path could accidentally be committed.

An example file is included with the plugin at .ai-dev-team.yml.example.

---

Ambient workflow

After install, Claude knows when to use which skill automatically — no slash commands required. Core triggers: /feature new (add/implement/build), /feature continue (resume/where-were-we), /cross-audit (review/audit/check-for-bugs), /investigate (compare/tradeoffs/which-is-better), /kb-audit (check KB drift / kb hygiene).

The full trigger map — including Russian variants, scope-addition handling, /feature status, /feature verify, and /feature checklist — lives in two places. The authoritative copy is hooks/session-start, injected into every session at runtime. The portable paste-ready copy for your project's CLAUDE.md is in docs/claude-md-snippet.md.

At session start, Claude proactively checks for in-progress specs and reports status before asking what to do next. Slash commands still work if you prefer explicit control.

---

How to use

Starting a feature

/feature new add webhook delivery retries

What happens:

1. Claude reads the codebase and searches KB for relevant context
2. Writes a spec + execution workdoc (design/workdocs/<slug>/exec.md) with per-step planned evidence schema
3. HARD GATE — shows you the spec, waits for explicit approval before writing any code
4. Two-pass spec review: self-review (completeness check) + dual-model cross-audit of spec and workdoc
5. Baseline test — verifies the test suite is green before any new code
6. Developer implements step-by-step: failing test → implement → passing test → save captures → compliance check per step
7. Verifier runs the full test suite
8. Hand-off: choose from 4 options (merge locally / push+PR / keep / discard)

You always see the spec before a single line of code is written.

Resuming in a new session

/feature continue

Without arguments: shows all in-progress specs and lets you pick one.

/feature continue kb/repos/my-project/design/2026-04-14-webhooks.md

With a path: jumps straight to that spec, reports current status, continues from the last unchecked step. No context recovery needed — everything lives in KB.

Checking what's in flight

/feature status

Shows a table of all specs across all projects: name, status, progress (N/M steps), branch.

Running an audit