Metadata-Version: 2.4
Name: agenticguidancebuilder
Version: 1.1.1
Summary: Scaffold and compile modular agent guidance into AGENTS.md
Project-URL: Homepage, https://github.com/GriffinBoris/AgenticGuidanceBuilder
Project-URL: Repository, https://github.com/GriffinBoris/AgenticGuidanceBuilder
Project-URL: Issues, https://github.com/GriffinBoris/AgenticGuidanceBuilder/issues
Author: griffinboris
Keywords: agents,cli,guidance,markdown,templates
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.13
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pyyaml>=6.0.2
Description-Content-Type: text/markdown

# 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:

```bash
uv tool install agenticguidancebuilder
```

Or install from source for local development:

```bash
uv sync --group dev
```

In this repository:

```bash
uv sync
```

Run the CLI with either:

```bash
uv run agd --help
```

or:

```bash
uv run agent-guidance --help
```

## Quick Start

Initialize a repo:

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

Inspect discovered content:

```bash
uv run agd list
```

Validate the tree:

```bash
uv run agd validate
```

Build the compiled output:

```bash
uv run agd build
```

Build OpenCode runtime exports:

```bash
uv run agd build --adapter opencode
```

Build Copilot runtime exports:

```bash
uv run agd build --adapter copilot
```

Include examples:

```bash
uv run agd build --include-examples
```

## Generated Repo Structure

After `agd init`, the target repo looks like this:

```text
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:

```md
---
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:

```toml
[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`

## Development Tasks

Useful local commands:

```bash
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:

```bash
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`:

```jinja2
# {{ 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.

## 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:

```bash
# 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 one default skill:

- `agents/content/skills/code-change-review.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:

```bash
uv run ruff check src tests
uv run pytest
uv build
```

Refresh derived guidance/runtime files with:

```bash
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
