Update Documentation

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

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:

1. 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.
2. Versions are in sync: The version in AzurePipelinesTool.csproj, .claude-plugin/plugin.json, and .claude-plugin/marketplace.json must all match.
3. Key flags are consistent: The flags table in README.md and skills/azure-pipelines-tool/SKILL.md should list the same flags.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.