| name | update-documentation |
| description | Update project documentation after code changes. Use when files have been added, modified, or removed and documentation needs to be brought in sync. Identifies what changed and which docs to update. |
Update Documentation
Guide for keeping project documentation in sync after code changes.
Step 1: Identify What Changed
If the user told you specifically what changed, use that information.
If not, figure it out by looking at the git history.
Check for staged/unstaged changes first:
git diff --name-only
git diff --staged --name-only
If there are no local changes, look at the last few commits instead:
git log --name-only --oneline -5
Review the diffs to understand what changed semantically (new command, new flag, version bump, architecture change, etc.).
Step 2: Update Documentation
Use the table below to determine which documentation files need updating based on the type of change.
Documentation Map
| Change | Files to Update |
|---|
| New CLI command | README.md (Quick Reference table, Usage examples if needed), AGENTS.md (available commands list in Architecture > Commands), skills/azure-pipelines-tool/SKILL.md (Command Reference table, Workflows section if applicable, Key Flags table if the command has flags) |
| New/changed flag on existing command | README.md (Key Flags table), skills/azure-pipelines-tool/SKILL.md (Key Flags table, usage examples) |
| Version bump | src/AzurePipelinesTool/AzurePipelinesTool.csproj (MajorVersion/MinorVersion/PatchVersion), .claude-plugin/plugin.json (version field), .claude-plugin/marketplace.json (metadata.version and plugins[0].version) — all three must match |
| New service/layer in architecture | AGENTS.md (Key layers section) |
| New NuGet dependency | AGENTS.md only if it introduces a new architectural concept |
| Changed authentication or config | AGENTS.md (Authentication/Configuration sections), README.md (Requirements section), skills/azure-pipelines-tool/SKILL.md (Requirements section) |
| Changed error handling patterns | AGENTS.md (Error handling section) |
| Changed test framework or conventions | AGENTS.md (Tests section), .github/instructions/csharp.instructions.md (Tests section if style changed) |
| Changed build/publish process | docs/development/README.md, AGENTS.md (Build and Test Commands section) |
| Changed code style conventions | .github/instructions/csharp.instructions.md, AGENTS.md (Code Style section) |
| New workflow or CI change | docs/development/README.md (if publishing-related) |
File Purposes
These are all the documentation files in the project and what each one is responsible for:
README.md — User-facing: installation, quick reference command table, usage examples with workflows, key flags table, agent skill installation instructions.AGENTS.md — Developer/agent-facing: project overview, build/test commands, architecture description, error handling patterns, pipeline resolution, configuration, versioning rules, test conventions, code style summary.CLAUDE.md — Entry point for Claude; references AGENTS.md. Rarely needs changes.skills/azure-pipelines-tool/SKILL.md — Agent skill: how to invoke azp commands via dnx, workflows, key flags, command reference. This file is also embedded as a resource in the built tool..claude-plugin/plugin.json — Plugin metadata: name, description, version. Version must match csproj..claude-plugin/marketplace.json — Marketplace metadata: marketplace name, version, plugin list. Version must match csproj.docs/development/README.md — Development guide: prerequisites, build/test, publishing setup, version management, release procedures..github/instructions/csharp.instructions.md — C# coding style guidelines applied to **/*.cs files.src/AzurePipelinesTool/AzurePipelinesTool.csproj — Source of truth for version numbers (MajorVersion, MinorVersion, PatchVersion).
Step 3: Verify Consistency
After making updates, check that:
- Command lists match: The command list in
README.md, AGENTS.md, skills/azure-pipelines-tool/SKILL.md, and Program.cs should all list the same user-facing commands.
- Versions are in sync: The version in
AzurePipelinesTool.csproj, .claude-plugin/plugin.json, and .claude-plugin/marketplace.json must all match.
- Key flags are consistent: The flags table in
README.md and skills/azure-pipelines-tool/SKILL.md should list the same flags.
