Metadata-Version: 2.5
Name: ai-guidelines
Version: 1.0.1
Summary: Reproducible, safe management of reusable Markdown guidelines
Project-URL: Homepage, https://github.com/gsemet/ai-guidelines
Project-URL: Documentation, https://ai-guidelines.readthedocs.io/en/stable/
Project-URL: Repository, https://github.com/gsemet/ai-guidelines
Project-URL: Issues, https://github.com/gsemet/ai-guidelines/issues
Author: Gaetan Semet
License: MIT License
        
        Copyright (c) 2026 Gaetan Semet
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: portalocker>=2.8
Requires-Dist: pydantic>=2.0
Requires-Dist: python-frontmatter>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# ai-guidelines

`ai-guidelines` manages reusable Markdown guidelines for a project. It copies explicitly
selected files into a project, records their source and SHA-256 hashes, and can reproduce or
update that selection safely. It does not execute Markdown.

## Install

```bash
uv tool install ai-guidelines

guidelines --version
```

Git is required for remote sources; local folders need no Git.

## Quick start

Create `guidelines.yml`:

```yaml
version: 1
default_guidelines_path: .github/guidelines
guidelines:
  - source: https://github.com/example/team-guidelines.git
    ref: main
    pattern: "*.guideline.md"
```

Run `guidelines sync`, then `guidelines list`, `guidelines search LOCATION QUERY`,
`guidelines outdated`, or `guidelines update --dry-run`. Add sources with
`guidelines add LOCATION [PATTERN] --ref REF --target-path PATH --alias NAME` and remove
declarations with `guidelines remove IDENTIFIER`; installed files are preserved. `sync --dry-run`
previews changes, while `sync --frozen` replays complete locked state without resolution or writes.
Use `--refresh` and `--no-cache` with search, and `guidelines cache size` to inspect the cache.
Selectors match both `.guideline.md` and `.guidelines.md` source files, including when the suffix is
omitted. Missing source paths are reported as concise CLI errors rather than
Python tracebacks. Installed files always use the canonical `.guidelines.md` suffix.

## Python facade

```python
from pathlib import Path
from ai_guidelines import load_manifest, parse_location, sync_manifest

manifest = load_manifest(Path("guidelines.yml"))
location = parse_location(manifest.guidelines[0].source)
result = sync_manifest(Path.cwd())
print(location.canonical_source, result)
```

## Documentation

Full documentation — tutorials, how-to guides, CLI and format reference, and design
rationale — is at <https://ai-guidelines.readthedocs.io/>.

Start with the [getting-started tutorial](docs/source/tutorials/getting-started.md). To
publish guidelines for your own team, commit them to a Git repository and declare it as a
source — see [source grammar](docs/source/reference/source-grammar.md). For how acquired
sources are cached, see [how caching works](docs/source/explanation/caching.md).

See also [`SECURITY.md`](SECURITY.md) and the [`examples/`](examples/) directory.

## Guideline, instruction, and skill

A **guideline** is reusable Markdown context containing rules or practices. An **instruction
file** is loaded or injected by an agent according to its file-pattern rules. A **skill** is a
self-describing knowledge package that declares activation or loading behavior. This tool only
installs explicitly selected guidelines: it does not inject instructions, activate skills, or
decide when an agent should load a file. Put project-owned loading rules in `AGENTS.md`,
`CONSTITUTION.md`, or another project convention.

## Development

Use `just install` and `just preflight`: format check, Ruff, strict mypy, pytest with a
coverage gate, and a documentation build with warnings as errors. See
[`CONTRIBUTING.md`](CONTRIBUTING.md).

Version 1 has no importer and no migration command for lockfiles produced by other tools:
any unrecognized lockfile format is rejected with an instruction to regenerate it. Declare
your sources in `guidelines.yml` and run `guidelines sync`.
