AutoDocSync Usage Guide

This guide explains how to use the AutoDocSync VS Code extension in a repository after the extension has been installed.

What the extension expects

The extension only creates the .copilot folder when a repository configuration file exists at:

.github/autodocsync.json

and the config contains:

"enabled": true

That config file can optionally point to:

.github/agents/autodocsync.agent.md
.github/instructions/autodocsync.instructions.md

The extension validates that each route includes the required guidance:

• instructionFiles (required)
• agent / agentFile / defaultAgent (optional)

If instructionFiles is missing, the route is rejected.

Recommended repository layout

Use this structure in the repository that will use the extension:

.github/
  autodocsync.json
  agents/
    autodocsync.agent.md
  instructions/
    autodocsync.instructions.md

Sample config file (At a Minumum)

Create .github/autodocsync.json with content like this:

{
  "enabled": true,
  "sourceGlobs": [
    "src/services/Microsoft.Horizon.FinMetrics.ARR/**"
  ],
  "defaultAgent": "ARRAutoDocSync",
  "routes": [
    {
      "name": "ARR Documentation",
      "match": [
        "src/services/Microsoft.Horizon.FinMetrics.ARR/**"
      ],
      "agent": "ARRAutoDocSync",
      "agentFile": ".github/agents/arr-autodocsync.agent.md",
      "instructionFiles": [
        ".github/instructions/arr-autodocsync.instructions.md"
      ],
      "docRoots": [
        "docs/arr/**"
      ],
      "reportFormat": "End with a 2-line documentation sync report: updated docs, skipped files."
    }
  ]
}

Full template

Use this template as a complete starting point for a repo-level configuration. Replace the example agent names with real ones that exist in your Copilot environment.

{
  "enabled": true,
  "sourceGlobs": [
    "src/**"
  ],
  "excludeGlobs": [
    "**/bin/**",
    "**/obj/**",
    "**/node_modules/**",
    "**/.git/**",
    "**/dist/**",
    "**/build/**",
    "**/*.log"
  ],
  "defaultAgent": "AutoDocSyncAgent",
  "configFile": ".github/autodocsync.json",
  "copilotCliPath": "copilot",
  "maxRunMinutes": 30,
  "extraCopilotArgs": [
    "--allow-all",
    "--no-ask-user",
    "--autopilot",
    "--no-color"
  ],
  "logDirectory": ".copilot/autodocsync",
  "routes": [
    {
      "name": "Application Documentation",
      "match": [
        "src/**"
      ],
      "agent": "AutoDocSyncAgent",
      "agentFile": ".github/agents/autodocsync.agent.md",
      "instructionFiles": [
        ".github/instructions/autodocsync.instructions.md"
      ],
      "docRoots": [
        "docs/**",
        "README.md"
      ],
      "reportFormat": "End with a short documentation sync report that lists updated docs and skipped source files."
    },
    {
      "name": "Infrastructure Documentation",
      "match": [
        "infra/**",
        "scripts/**"
      ],
      "agent": "AutoDocSyncAgent",
      "instructionFiles": [
        ".github/instructions/autodocsync.instructions.md"
      ],
      "docRoots": [
        "docs/**",
        "architecture/**"
      ]
    }
  ]
}

This tells the extension:

• watch files in src/**
• use the route when matching source files are changed
• follow the agent file and instruction file
• update documentation only under the configured docRoots

Properties in .github/autodocsync.json

Mandatory vs optional summary

Mandatory for AutoDocSync to do anything useful:

• enabled: true
• at least one route entry in routes when using route-based execution
• each route must include instructionFiles with at least one file
• match should be present on each route
• agent, agentFile, and defaultAgent are optional and only used when provided

Optional but commonly used:

• defaultAgent
• sourceGlobs
• excludeGlobs
• docRoots
• reportFormat
• custom logDirectory

Sample agent file

Create .github/agents/autodocsync.agent.md with the agent guidance you want the Copilot CLI to use.

Example:

# AutoDocSync Agent

You are helping keep repository documentation up to date.

- Review changed source files.
- Update only relevant documentation.
- Keep tone and structure consistent with the existing docs.
- Ignore generated files, build output, and test artifacts.
- Return a brief final report with what changed.

Sample instruction file

Create .github/instructions/autodocsync.instructions.md with instructions like:

# AutoDocSync Instructions

Use these instructions as a starting point for documentation updates.

## Goal

Keep repository documentation aligned with source changes.

## Scope

- Read every changed source file before editing documentation.
- Update only documented files under the configured docRoots.
- Do not modify source code or generated outputs.
- Prefer updating existing documentation instead of creating new files.

## Final report

End each run with a short report that includes:

- documents updated
- source files reviewed
- skipped files and reasons
- any documentation gaps needing human review

How the extension behaves

Once installed and enabled:

• it watches for source file changes
• checks whether the changed files match configured route patterns
• loads the repo config from .github/autodocsync.json
• invokes Copilot CLI using the selected route
• updates documentation under the matching docRoots
• writes logs under .copilot/autodocsync

The .copilot folder is created only when all of the following are true:

• the repo contains .github/autodocsync.json
• the config file exists and is valid JSON
• the config contains "enabled": true
• AutoDocSync has started successfully for the current workspace

If the config is missing, disabled, or the workspace is not trusted, the extension will not create the .copilot state folder.

What is created under .copilot/autodocsync

When AutoDocSync starts successfully, it creates a state folder similar to:

.copilot/
  autodocsync/
    autodocsync.log
    last-source-signature.txt
    prompt-<timestamp>.txt
    logs/
      copilot-<timestamp>.log

Purpose of each file

• autodocsync.log

  • main runtime log from the extension itself
  • shows when AutoDocSync started, when files changed, and whether a run was skipped
  • helps confirm that the extension is active and which workspace it is monitoring

• last-source-signature.txt

  • stores the hash of the last processed set of changed source files
  • prevents duplicate runs for identical source changes
  • useful to understand whether a run was intentionally skipped as a duplicate

• prompt-<timestamp>.txt

  • the exact Copilot prompt generated for a run
  • contains the changed files, route info, instructions, and doc root constraints
  • ideal for debugging why the model chose certain docs or ignored some files

• logs/copilot-<timestamp>.log

  • raw stdout/stderr from the Copilot CLI invocation
  • contains the actual command line and the model response/error text
  • the most useful file when debugging agent selection, permission issues, prompt problems, or model errors

How these files help debug issues

If something fails, start with the newest files in .copilot/autodocsync:

1. Read autodocsync.log to see whether AutoDocSync started and whether it detected changes.
2. Open the newest prompt-<timestamp>.txt to confirm the prompt matches the expected files and route.
3. Open the newest logs/copilot-<timestamp>.log to inspect the agent invocation and model response or failure.
4. If a run was skipped, check last-source-signature.txt to determine whether it was intentionally deduplicated.

This makes it much easier to diagnose:

• missing or incorrect config
• invalid agent name
• bad source glob matching
• no files detected under src/**
• Copilot CLI authentication issues
• route validation problems
• runtime exceptions while invoking the model

Default agent behavior (defaultAgent)

The defaultAgent field is the fallback agent name used when a route does not explicitly provide a matching agent or when no route matches the changed files.

Example:

"defaultAgent": "AutoDocSyncAgent"

Requirements / expectations

defaultAgent is optional. If it is provided, it should be an actual Copilot agent that exists in the environment where the extension is running. If the agent name is invalid, the Copilot CLI will fail with an error similar to:

No such agent: AutoDocSyncAgent

If no agent is provided, the extension will rely on the required instructionFiles instead.

Recommended pattern

• set defaultAgent only when you know a safe, repo-appropriate agent is available
• set a route-level agent only when you want route-specific overrides
• make sure every route includes:
  • instructionFiles with at least one file
• use agentFile only when you want to add extra agent guidance alongside the instruction files

If a route does not include instructionFiles, the extension rejects it during config validation.

Typical workflow in a repo

1. Install the extension.
2. Add .github/autodocsync.json.
3. Add .github/agents/autodocsync.agent.md.
4. Add .github/instructions/autodocsync.instructions.md.
5. Open the repo in VS Code.
6. Ensure the workspace is trusted.
7. Start AutoDocSync from the VS Code command palette or extension commands.
8. Change source files and let AutoDocSync update documentation.

Useful commands

Start AutoDocSync

From the VS Code command palette:

• AutoDocSync: Start

Run once manually

• AutoDocSync: Run Once

Open config/settings

• AutoDocSync: Open Configuration

Notes

• The extension only runs in trusted workspaces.
• Default config path is .github/autodocsync.json.
• Default log folder is .copilot/autodocsync.
• The autodocsync.* settings namespace matches the package name.