azdospec

Status: design phase. The model is settled and the commands are written. Not yet exercised against enough real projects to call it stable.

An agent skill that runs spec-driven development entirely inside Azure DevOps. OpenSpec keeps proposals, specs and tasks as Markdown in an openspec/ folder inside the repository. AzDOSpec keeps the same model and drops the folder: every artifact is a native Azure Boards work item, every relationship is a native link, and the agent reads the current state from the board rather than the filesystem.

The result is one source of truth the whole team already looks at, where a requirement is connected to the branch that implements it, the pull request that merges it, the tests that verify it and the person who owns it.

Built on the open Agent Skills standard, so it works with any compatible agent — Claude Code, opencode, pi, and others.

How it maps

OpenSpec	Azure DevOps
Capability	Area Path
proposal.md	Feature — a single backlog item when the change has one requirement, an Epic when it spans Features
Requirement + scenarios	Backlog item (User Story / Product Backlog Item / Requirement / Issue, per process) with Gherkin acceptance criteria and an ADDED / MODIFIED / REMOVED tag
design.md	Description of the Feature
tasks.md	Checklist while proposed; child Tasks once the item reaches a sprint
Dependencies	Predecessor / Successor and Related links
specs/	Spec store — see below
Archive	Deltas applied to the spec store, items moved to Done

Capabilities are Area Paths rather than long-lived work items on purpose: a backlog is a list of work, and an item that never closes distorts every board, rollup and forecast it appears on. The reasoning behind this and the other non-obvious choices is in how it maps.

Traceability is native throughout — parent/child hierarchy, AB#<id> in commits, pull requests linked to the items they deliver, pull request completion transitioning those items, and a branch policy that refuses a pull request with no work item attached.

Commands

Command	What it does
/azdo:init	Once per repository. Resolves organization and project from the git remote, detects the available spec store, configures the branch policy and writes .azdospec.json.
/azdo:propose <idea>	Reads the current spec, drafts the whole change — Feature, one requirement per delta, task checklist — shows it as a single draft, and creates and links everything once you approve.
/azdo:apply	Refuses unless a product owner approved the requirement and it has an iteration. Creates the tasks, derives parallel streams from the dependency links, pushes a branch named for the work item, opens the pull request and posts progress as comments.
/azdo:archive	Verifies the tasks are Done, folds the deltas into the spec store and closes the change.

Full detail in commands.

Spec store

Where the merged, living specification of each capability lives. Chosen once by /azdo:init, driven by what your organization actually licenses:

Store	Requires	What it does
testplans	Basic + Test Plans	Each scenario becomes a Test Case — Design while proposed, Ready once archived, Closed when removed — in a suite per Area Path, linked Tests / Tested By to its requirement. Specification by example: the spec is executable.
wiki	Basic	Default when Test Plans is not licensed. One page per Area Path, rewritten on archive.
epic	Basic	Opt-in. One long-lived Epic per Area Path holding the spec in its description. Works anywhere, at the cost of a backlog item that never closes.
none	—	Opt-in. No merged spec; the agent reads the Done items of the Area Path.

See spec stores for how to choose.

Requirements

• An agent that supports Agent Skills or Claude Code plugins.

• The Azure CLI with the azure-devops extension, signed in:

  az extension add --name azure-devops
  az login
  

  That sign-in is the identity for everything AzDOSpec does. There is no token to create or store, and no server to configure. Every artifact is a work item, so there is no offline mode.

• A repository whose remote is an Azure DevOps repository.

Install

Claude Code — as a plugin

/plugin marketplace add Gn0m0-dei/azdospec
/plugin install azdo

This registers /azdo:init, /azdo:propose, /azdo:apply and /azdo:archive as real commands.

pi

pi install npm:azdospec

git:github.com/Gn0m0-dei/azdospec works too, if you would rather track the repository than the releases. It installs the skill and registers /azdo-init, /azdo-propose, /azdo-apply and /azdo-archive.

opencode

Add the plugin to opencode.json and it registers the four commands and the skill in one step — opencode installs it from npm itself:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["azdospec"]
}

The plugin never overwrites a command you configured yourself.

Any Agent Skills host

npx skills add Gn0m0-dei/azdospec

Or copy the skill folder (skills/azdospec/, the one containing SKILL.md) into the skills directory your agent reads — ~/.claude/skills/azdospec/, ~/.config/opencode/skills/azdospec/, ~/.pi/agent/skills/azdospec/, or the project-local equivalent.

Installed this way there are no slash commands: ask for what you want and the skill activates by description.

Host	Install	Commands
Claude Code	/plugin install azdo	/azdo:init, propose, apply, archive
pi	pi install npm:azdospec	/azdo-init, azdo-propose, azdo-apply, azdo-archive
opencode	One line in opencode.json	The same four
Any other Agent Skills host	npx skills add …	None; activates by description

Whatever the host, the Azure CLI is the connection: the same az login on every one of them, and nothing per host to configure.

Documentation

→ Getting Started — install, set up a repository, first change → Commands — what each one does, and what it refuses to do → How It Maps — the reasoning behind the model → Spec Stores — where the living spec lives → FAQ

Layout

skills/azdospec/          # the skill itself — portable to any Agent Skills host
├── SKILL.md              # model, commands, hard rules
└── references/
    ├── work-items.md     # types, fields, links, delta tags, and the CLI commands for them
    ├── init.md · propose.md · apply.md · archive.md

.claude-plugin/           # Claude Code plugin manifest and marketplace entry
commands/                 # /azdo:init · propose · apply · archive — read by all three hosts
plugins/opencode.ts       # opencode plugin: registers them, plus the skill
extensions/               # pi extension: registers them
lib/                      # what the two of them share
test/                     # pnpm test

SKILL.md is loaded whenever the skill activates; references/ files are read on demand, so only the detail a command actually needs enters the context.

The command files are deliberately thin — each one points at its procedure in references/. The behaviour lives in the skill and nowhere else, and all three hosts read the same four command files rather than each keeping a copy, so a procedure is one edit and no host can drift away from another.

Nothing ships in a host's local configuration directory: .claude/, .opencode/ and .agents/ are where your machine keeps its agent settings, so they are ignored here like in any other repository. Each host is pointed at the visible directories above through its own manifest instead.

Credits

The artifact model comes from OpenSpec; the execution discipline — progress comments, dependency-driven parallel work, one branch per change — from CCPM. Both are local-first. AzDOSpec is the remote-first take on the same idea.

Contributing

See CONTRIBUTING.md. Open an issue before a pull request that changes behaviour — the mapping is deliberate, and a discussion is cheaper than a rewritten pull request.

License

MIT — see LICENSE.