agenticguidancebuilder

Agentic Guidance Builder

Agentic Guidance Builder is a Python CLI for authoring modular guidance content and compiling it into a final AGENTS.md file.

This repository is the tool itself. It helps you:

• scaffold a clean guidance structure inside a repo
• write guidance as readable Markdown
• add lightweight metadata with YAML frontmatter
• render Markdown and final outputs with Jinja templates
• validate the guidance tree before building
• keep tool-specific runtime exports derived from canonical source content

What This Repository Is

This repo contains the V1 implementation of the Agentic Guidance Builder CLI.

The current product shape is intentionally simple:

• authored guidance lives under agents/guidance/
• authored non-guidance assets live under agents/content/
• adapters write tool runtime outputs as derived artifacts
• repository-level build settings live in root agd-settings.toml
• the primary compiled output is root AGENTS.md
• adapters can also export runtime files for tools like OpenCode and Copilot

Why It Exists

Most repos accumulate agent instructions in a single giant file. That gets hard to maintain.

This tool breaks that problem into smaller pieces:

• global guidance
• language guidance
• framework guidance
• project guidance
• example documents
• reusable templates and settings

Instead of hand-maintaining one large output file, you author small source documents and build the final result.

Core Workflow

1. run agd init
2. edit the Markdown files under agents/guidance/
3. optionally customize agd-settings.toml
4. optionally customize the templates under agents/guidance/templates/base/
5. run agd validate
6. run agd build

Install

This project currently targets Python >=3.13.

Install from PyPI once published:

uv tool install agenticguidancebuilder

Or install from source for local development:

uv sync --group dev

In this repository:

uv sync

Run the CLI with either:

uv run agd --help

or:

uv run agent-guidance --help

Quick Start

Initialize a repo:

uv run agd init \
  --project-name "Example Repo" \
  --languages python \
  --frameworks django,vue

Inspect discovered content:

uv run agd list

Validate the tree:

uv run agd validate

Build the compiled output:

uv run agd build

Build OpenCode runtime exports:

uv run agd build --adapter opencode

Build Copilot runtime exports:

uv run agd build --adapter copilot

Include examples:

uv run agd build --include-examples

Refresh packaged base templates in an existing repo:

uv run agd upgrade --templates

Refresh packaged starter skills and commands:

uv run agd upgrade --content

Refresh packaged tool bootstrap assets:

uv run agd upgrade --tools

Refresh all packaged templates and starter assets:

uv run agd upgrade

Generated Repo Structure

After agd init, the target repo looks like this:

agd-settings.toml
agents/
  guidance/
    guidance.md
    languages/
      <language>/
        guidance.md
        examples/
          example.md
    frameworks/
      <framework>/
        guidance.md
        examples/
          example.md
    project/
      guidance.md
      examples/
        example.md
    templates/
      base/
        agents.md.j2
        macros.j2
        section.guidance.md.j2
        section.examples.md.j2
  content/
    skills/
      test-skill.md
    commands/
      test-command.md
    agents/
      test-agent.md

How Authoring Works

Guidance Files

Compiled guidance content lives under agents/guidance/.

• agents/guidance/guidance.md is the global file
• agents/guidance/languages/<name>/guidance.md is language-specific guidance
• agents/guidance/frameworks/<name>/guidance.md is framework-specific guidance
• agents/guidance/project/guidance.md is repo-specific guidance
• examples/ documents are optional example content for those scopes

Frontmatter

Markdown files can include optional YAML frontmatter.

Example:

---
id: language-python-guidance
title: Python Guidance
description: Durable guidance for the Python language.
kind: guidance
scope: language
name: python
tags:
  - language
  - python
applies_to:
  - python
status: active
order: 1
---

# Python Guidance

## Purpose

- Explain what belongs here.

If frontmatter is omitted, defaults are derived from the file path and headings.

Examples

Example files are regular Markdown source documents with kind: example.

They are useful for:

• before/after examples
• reference snippets
• layout examples
• patterns that are easier to show than explain

Examples are only included in the compiled output when enabled.

Settings

Repository-level settings live in agd-settings.toml at the repo root.

Example:

[project]
name = "Example Repo"
summary = ""

[build]
default_output = "AGENTS.md"
include_examples_by_default = false

[vars]
product_name = "Example Repo"
repository_name = "example-repo"

Current behavior:

• project.name can supply the default project name for builds
• build.default_output can supply the default output path
• build.include_examples_by_default can supply the default example-inclusion behavior
• [vars] values are exposed to Jinja templates as vars

Template Context

Markdown and final templates can use these top-level values:

• project
• build
• selection
• settings
• vars
• doc

This keeps the authoring model lightweight while still allowing customization.

Commands

agd init

Scaffolds the guidance tree and starter files.

Common flags:

• --project-name
• --languages
• --frameworks
• --force
• --dry-run

Language and framework names are generic. The CLI scaffolds whatever names you pass.

agd build

Builds the compiled output artifact.

Common flags:

• --adapter
• --project-name
• --output
• --include-examples
• --languages
• --frameworks
• --dry-run

If filters are omitted, all discovered language and framework packages are included.

agd validate

Validates the guidance tree and reports grouped errors and warnings.

agd list

Lists discovered guidance content and shows metadata like:

• id
• scope
• name
• order
• path

agd upgrade

Refreshes packaged templates and starter assets in an existing repo.

If no scope flags are provided, it refreshes all supported packaged assets.

Common flags:

• --target
• --dry-run
• --templates
• --content
• --tools

Examples:

• agd upgrade
• agd upgrade --templates
• agd upgrade --content --tools

agd upgrade-templates

Refreshes packaged files under agents/guidance/templates/base/ in an existing repo.

Common flags:

• --target
• --dry-run

agd upgrade-content

Refreshes packaged starter content under agents/content/.

Today that includes:

• starter skills
• selected starter commands

Common flags:

• --target
• --dry-run

agd upgrade-tools

Refreshes packaged tool bootstrap assets under agents/tools/.

Common flags:

• --target
• --dry-run

agd upgrade-all

Refreshes all packaged templates and starter assets that have dedicated upgrade flows.

Common flags:

• --target
• --dry-run

Development Tasks

Useful local commands:

task ai:setup-all-agents
task ai:setup-root
task ai:setup-opencode

task ai:setup-all-agents refreshes derived runtime files from the canonical agents/ tree.

How To Customize It

1. Add Your Own Languages And Frameworks

There is no fixed allowlist.

These all work:

uv run agd init --languages python,elixir --frameworks django,phoenix

2. Edit The Markdown Source Files

The simplest customization path is just editing the authored docs under agents/guidance/.

That is usually enough for:

• repo-specific rules
• stack-specific conventions
• examples and snippets
• organization notes

3. Customize agd-settings.toml

Use the settings file when values should be shared across multiple source docs or templates.

Good uses:

• project name
• product name
• default output path
• default example behavior
• small shared variables for templating

4. Override The Build Templates

Project-specific templates live under agents/guidance/templates/base/.

If present, they override the packaged defaults:

• agents.md.j2
• macros.j2
• section.guidance.md.j2
• section.examples.md.j2

Example custom agents.md.j2:

# {{ project.name }} Guidance

Product: {{ vars.product_name }}

{% if global_guidance %}
{{ render_guidance_section(global_guidance) }}
{% endif %}

5. Keep Tool-Specific Assets Separate

Use agents/content/ for authored assets that should not be part of the compiled AGENTS.md source tree.

That includes reusable tool-agnostic authored assets like:

• skills
• commands
• agents
• other reusable authored content

Use agents/tools/ only when a future adapter genuinely needs tool-owned authored assets that cannot come from shared canonical content.

Use frontmatter roles to describe adapter-specific projection behavior when needed. For example, a canonical command can carry a role like opencode-command or copilot-repository-instructions without changing the top-level source taxonomy.

When a tool needs a bootstrap or base file that is not naturally derived from shared canonical content, keep that authored source in agents/tools/<tool>/. For example, OpenCode can use agents/tools/opencode/opencode.json as the canonical base config that the adapter copies to the repo root.

Adapters

The build pipeline currently supports these adapters:

• agents-md - writes the compiled AGENTS.md only
• opencode - writes AGENTS.md, .opencode/commands/, .opencode/agents/, .opencode/skills/, and opencode.json
• copilot - writes AGENTS.md, .github/copilot-instructions.md, .github/instructions/, .github/skills/, and .github/agents/

Authoring stays markdown-first:

• canonical guidance stays in agents/guidance/
• reusable single-file skills, commands, and agents stay in agents/content/
• agents/tools/ is reserved for assets that are truly tool-specific and cannot come from the shared canonical content layer

The baked-in assets are intentionally single files so adapters can read one canonical source and remap it into the output layout each tool expects. For example, agents/content/agents/context-gatherer.md is the single authored source and the adapters generate OpenCode and Copilot agent files from it.

6. Customize The Packaged Starters

This tool ships with packaged starter assets for:

• guidance files
• example files
• settings
• skills
• selected starter commands
• build templates

During agd init, those packaged assets are copied into the target repository and become normal editable project files. Tool-specific or optional starter assets are only scaffolded when a packaged source file exists.

If you want newer packaged defaults later without re-running full init, use the upgrade commands:

• agd upgrade
• agd upgrade-templates
• agd upgrade-content
• agd upgrade-tools
• agd upgrade-all

Using It In Other Projects

The intended flow is to install the CLI once, then run it inside any repository you want to scaffold or build.

Examples:

# install once
uv tool install agenticguidancebuilder

# scaffold guidance in another repo
cd /path/to/other-repo
agd init --project-name "Other Repo" --languages python --frameworks django

# validate and build there
agd validate
agd build

Default Skills

The scaffold currently includes default skills such as:

• agents/content/skills/code-change-review.md
• agents/content/skills/guidance-layout-migration.md

It is designed to support strict, deterministic review work by requiring the reviewer to:

• state the exact scope
• read the applicable guidance docs first
• read applicable example docs
• compare the code to the closest existing in-repo pattern
• map each guidance/example file to a verdict
• tie every finding to a file plus a rule, example, or pattern
• report verification status and blind spots

This keeps review work grounded in the actual guidance tree instead of drifting into taste-only feedback.

Logging And CLI Behavior

The CLI uses simple prefixed output:

• INFO: for progress
• OK: for successful actions
• WARN: for non-fatal states like skipped or unchanged files
• ERROR: for failures

This keeps the CLI readable while still being easy to scan in automation.

Documentation In This Repo

• README.md - product overview and usage
• agents/AGENTS.md - repo-specific development guidance for this repository itself

Development

Run local checks with:

uv run ruff check src tests
uv run pytest
uv build

Refresh derived guidance/runtime files with:

task ai:setup-all-agents

Building & Publishing To PyPI

1. Update the version in pyproject.toml.
2. Build artifacts locally with uv build.
3. Inspect dist/ to verify the wheel and sdist contents.
4. Publish manually with uv publish --token <pypi-token> if needed.

GitHub Actions also publishes on tag pushes matching v* using the PYPI_TOKEN repository secret.

If you prefer PyPI trusted publishing later, the workflow is already split into build and publish jobs, so switching from PYPI_TOKEN to OIDC is straightforward.

Current Status

The current implementation is a focused V1.

• stable authoring flow: init -> list -> validate -> build
• stable output target: AGENTS.md
• adapter architecture is present for future expansion
• tool-specific exports are intentionally deferred until later adapters are added