agentic-dev-kit

An Agent Plugin that bundles skills for planning and shipping work with AI coding agents.

It also connects the hosted Azure DevOps MCP server, limited to work-item, iteration, and repository tools.

The ado-implement flow

pick interview mode   grill (decisions) or teach (decisions + why + recall)
  connect             MCP server, else az CLI
  select item         yours, or by ID
  assess item         descriptive work item check, offer rewrite
  settle scope        acceptance checklist, small-PR split
  branch              off the base branch you choose, freshly fetched
  implement           red -> green: unit, accessibility (axe), UI (Playwright); lint touched files
  commit              message drafted from the work item, linked to it
  review              PR Reviewer subagent (read-only) -> findings -> fixes
  pull request        body via `pr`, pushed and linked on your yes
  hand back           evidence per criterion, optional ADO state/comment

After the PR opens, pr-review takes over:

author     collect open threads -> triage (fix / answer / push back / defer)
           -> fix test-first -> reply + resolve -> repeat until all settled
reviewer   pick PR -> check out head -> PR Reviewer subagent -> verify findings
           -> choose what to post + vote -> post on your yes -> re-review later

Each step ends at a gate where you decide; nothing is pushed or written to Azure DevOps without your yes.

Start with just the item and the mode, and let the skill drive:

/ado-implement https://dev.azure.com/<org>/<project>/_workitems/edit/<id> teach

Anything else you add (for example "one question at a time") overrides the skill's defaults for pace. The steps and gates still apply. Best practices (descriptive work items, small PRs, branch and commit hygiene) are checked along the way: see PRACTICES.md and TESTING.md.

Install

VS Code (GitHub Copilot): run Chat: Install Plugin From Source and enter https://github.com/puttagunta/agentic-dev-kit.

Recommend it to everyone working in a repo: add .github/copilot/settings.json to that repo:

{
  "extraKnownMarketplaces": {
    "agentic-dev-kit": {
      "source": { "source": "github", "repo": "puttagunta/agentic-dev-kit" }
    }
  },
  "enabledPlugins": {
    "agentic-dev-kit@agentic-dev-kit": true
  }
}

VS Code then offers to install it the first time someone sends a chat message in that repo.

Your organization's security and privacy controls

The Security and Privacy reviewers apply a baseline (security, privacy) that every company will want to tailor. Three extension points, from lightest to heaviest:

1. Per repo: add .github/review-controls/security.md or privacy.md in the same format as the baseline. Your controls add to the baseline; reusing a baseline ID (SEC-03) replaces it. These files are always read from the target branch, so a PR can't rewrite the controls it's checked against.
2. Scanners and sign-off: list read-only scanner commands under ## Scanners (they run only after you approve each command) and the teams that sign off on escalate findings under ## Escalation (added as required PR reviewers).
3. Org-wide: fork this plugin and edit the baseline, or add your internal read-only tools (for example a data-classification MCP server) to the tools list in security-reviewer.agent.md or privacy-reviewer.agent.md.

Setup

The skills check their own prerequisites: a preflight before each run (git version, az + azure-devops extension, gh and its sign-in for GitHub repos, node for web projects, the .NET SDK for .NET projects, working-tree state) and a postflight after (working tree, stash, starting branch restored, branch pushed, temp files cleaned). Run them yourself from a repo:

<plugin>/scripts/check.sh pre ado-implement     # or: pr-review
<plugin>/scripts/check.sh pre ado-implement --skip gh   # skip checks you'll fix later: git, az, gh, node, dotnet
<plugin>/scripts/check.sh post ado-implement

Install anything missing with scripts/install.sh (macOS via Homebrew; Linux prints the commands) or scripts/install.ps1 (Windows via winget). Both show what they'll run and ask first; sign-ins (az login, gh auth login) stay with you.

If a tool works in your terminal but the check says it won't run, VS Code is still using the PATH it read at launch. Quit and reopen VS Code after changing your shell profile.

Guardrails

The skills' instructions and the check scripts guide the agent; they don't stop it. Three layers do:

1. Read-only reviewer agents: the PR, Security, and Privacy reviewers are given only read and search tools.
2. A PreToolUse hook (com.github.copilot/hooks/hooks.json running scripts/guardrails.sh, or guardrails.ps1 on Windows), checked by the client before every tool call while the plugin is enabled:
   • Denies: git push --force / -f / +refspec, direct pushes to main, master, develop, release/*, git reset --hard, git clean -f, git branch -D, git checkout . / git restore ., git stash drop|clear, --no-verify, and bypassing branch policies.
   • Asks: any other git push (including --force-with-lease), gh pr writes, gh api writes and GraphQL mutations, az repos pr / az boards writes, az devops invoke writes, every Azure DevOps MCP write tool, and recursive deletes outside .git/agentic-dev-kit/.
   • Hooks are in preview in VS Code: enable chat.useHooks and trust the workspace. In Claude Code, register scripts/guardrails.sh as a PreToolUse hook in your settings.
   • The hook finds the script through the client's plugin-root variable, else the default install folders under ~/.vscode, ~/.vscode-insiders, and ~/.copilot. If it finds none, it lets tool calls through and prints a warning, because Copilot denies every tool call when a PreToolUse hook errors.
   • To change the rules, edit the script and run scripts/guardrails.test.sh.
3. Your repository's own policies, the only layer that holds when everything else fails. Recommended:
   • Azure Repos branch policies on the default branch: require a PR with at least one reviewer, block authors approving their own changes, require linked work items, require comment resolution, require build validation, and add automatic reviewers for security- and privacy-sensitive paths.
   • GitHub: a ruleset with the same rules, CODEOWNERS, and secret scanning with push protection.
   • Least privilege: personal access tokens or Entra app scopes limited to Work Items and Code; set X-MCP-Readonly: true in mcp.json for anyone who only reads.
   • Working solo: keep every rule above except the approver: on Azure Repos, 1 approver with the author's own vote counting; on GitHub, 0 required approvals. The branch-policies skill applies this, and ado-implement then posts the AI reviewers' findings on each PR as its review record.

Authentication

The plugin contains no credentials. Each user signs in with their own account:

• Azure DevOps MCP server: your client prompts for a Microsoft Entra sign-in the first time a tool is used. Your Azure DevOps organization must be backed by Microsoft Entra ID.
• Fallback: if the MCP server can't authenticate, ado-implement switches to the az CLI (az boards, az repos), using az login or a personal access token you export as AZURE_DEVOPS_EXT_PAT in your own terminal.
• GitHub-hosted code: pull requests are opened with the gh CLI, signed in with gh auth login.

Client support

Skills work in any client that supports Agent Skills. The hosted Azure DevOps server signs in natively in VS Code, GitHub Copilot CLI, and the GitHub Copilot app. Claude Code and Cursor need a custom Microsoft Entra app registration (setup guide); in other clients, ado-implement falls back to the az CLI.

Contributing

Each skill lives in skills/<name>/SKILL.md; the folder name must match the skill's name. Custom agents are Copilot-specific, so they live in com.github.copilot/agents/<name>.agent.md; other clients ignore that folder, and ado-implement falls back to a general subagent that reads the same file. Bump version in plugin.json with every release so installed copies update.

License

MIT. The pr, grilling, grill-me, and teach skills come from mattpocock/skills (MIT).