Metadata-Version: 2.4
Name: agentscribe
Version: 0.1.0
Summary: One source of truth for your AI agent instructions. Generate and validate AGENTS.md, CLAUDE.md, .cursorrules, Copilot, Gemini and Windsurf instruction files from a single file.
Project-URL: Homepage, https://github.com/Lucabiz/agentscribe
Project-URL: Repository, https://github.com/Lucabiz/agentscribe
Project-URL: Issues, https://github.com/Lucabiz/agentscribe/issues
Project-URL: Changelog, https://github.com/Lucabiz/agentscribe/blob/main/CHANGELOG.md
Author: agentscribe contributors
License: MIT License
        
        Copyright (c) 2026 agentscribe contributors
        
        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
Keywords: agents,agents.md,ai,claude,cli,codex,coding-agent,copilot,cursor,developer-tools,llm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: tomli>=1.2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# agentscribe

**One source of truth for your AI agent instructions.**

Write your project's guidance once in `AGENTS.md`, and let agentscribe generate and
keep in sync every tool-specific variant — `CLAUDE.md`, Cursor rules, GitHub
Copilot instructions, Gemini, Windsurf, Cline — then lint the source and fail CI
when the copies drift.

[![CI](https://github.com/Lucabiz/agentscribe/actions/workflows/ci.yml/badge.svg)](https://github.com/Lucabiz/agentscribe/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/agentscribe.svg)](https://pypi.org/project/agentscribe/)
[![Python versions](https://img.shields.io/pypi/pyversions/agentscribe.svg)](https://pypi.org/project/agentscribe/)
[![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)

---

## The problem

Every AI coding tool reads its instructions from a different file:

| Tool | File it reads |
| --- | --- |
| OpenAI Codex | `AGENTS.md` |
| Claude Code | `CLAUDE.md` |
| Cursor | `.cursor/rules/*.mdc` (or `.cursorrules`) |
| GitHub Copilot | `.github/copilot-instructions.md` |
| Gemini CLI | `GEMINI.md` |
| Windsurf | `.windsurf/rules/` (or `.windsurfrules`) |
| Cline | `.clinerules/` |

If your team uses more than one of these — and most do now — you end up
copy-pasting the same rules into five files and watching them rot out of sync.

## The fix

Keep **one** file (`AGENTS.md`, the emerging open standard that Codex reads) and
generate the rest:

```bash
pip install agentscribe

agentscribe init      # scaffold an AGENTS.md from your project
agentscribe sync      # generate CLAUDE.md, Cursor rules, Copilot instructions, ...
agentscribe check     # in CI: fail if any generated file is out of date
agentscribe lint      # catch leaked secrets, dead file refs, bloated instructions
```

Generated files carry a "do not edit" header and are byte-stable, so `check`
gives you a clean pass/fail in CI.

## Quickstart

```bash
$ agentscribe init
Created AGENTS.md  (detected: Python)

$ agentscribe sync
  + CLAUDE.md  (Claude Code)
  + .cursor/rules/agentscribe.mdc  (Cursor)
  + .github/copilot-instructions.md  (GitHub Copilot)
Updated 3 file(s) from AGENTS.md.

$ agentscribe check
All target files are in sync with AGENTS.md.
```

Now edit `AGENTS.md` whenever your conventions change and re-run `agentscribe sync`.

## Commands

| Command | What it does |
| --- | --- |
| `agentscribe init` | Detect the project (language, package manager, test command) and write a starter `AGENTS.md`. |
| `agentscribe sync` | Generate/update every configured target file. `--dry-run` to preview, `-t claude,cursor` to limit targets. |
| `agentscribe check` | Exit non-zero if any target is missing or out of date. Made for CI. |
| `agentscribe lint` | Validate the source: leaked secrets (error), unbalanced directives (error), broken relative-path references, oversized files, missing sections. `--strict` fails on warnings. |
| `agentscribe list` | Show every target, whether it's enabled, its path, and sync status. |

Run `agentscribe <command> --help` for all flags.

## Configuration

Configuration is optional. Put it in `agentscribe.toml`:

```toml
source = "AGENTS.md"
targets = ["claude", "cursor", "copilot", "gemini"]

[lint]
max_chars = 12000

[cursor]
legacy = false                 # true -> write .cursorrules instead of .mdc
description = "Project rules"
always_apply = true
```

…or under `[tool.agentscribe]` in `pyproject.toml`. Available target keys:
`claude`, `cursor`, `copilot`, `gemini`, `windsurf`, `cline`.

## Scoping content to specific tools

Most guidance is shared, but sometimes one tool needs its own note. Use
HTML-comment directives — invisible when the file renders as Markdown:

```markdown
Shared guidance for every agent.

<!-- agentscribe:only cursor,copilot -->
This paragraph is emitted only into the Cursor and Copilot files.
<!-- agentscribe:end -->

<!-- agentscribe:except claude -->
Goes everywhere except CLAUDE.md.
<!-- agentscribe:end -->

<!-- agentscribe:ignore -->
Private notes that stay in AGENTS.md and are never copied anywhere.
<!-- agentscribe:end -->
```

Directives may be nested.

## Use in CI

Add a check so generated files can never silently drift. GitHub Actions:

```yaml
- run: pip install agentscribe
- run: agentscribe check   # fails the build if CLAUDE.md et al. are stale
- run: agentscribe lint    # fails on leaked secrets or malformed instructions
```

## Library API

Everything the CLI does is available programmatically:

```python
from agentscribe import Config, sync, check, lint

cfg = Config.load(".")
sync(cfg)  # write all target files
drift = check(cfg)  # list of out-of-date targets
findings = lint(cfg)  # list of Finding(level, rule, message, line)
```

## How is this different from copy-pasting or a symlink?

- **Symlinks** don't work: each tool wants a different *format* and *location*
  (Cursor needs YAML front-matter; Copilot lives under `.github/`), and symlinks
  are fragile on Windows and in Git.
- **Copy-pasting** is exactly the drift problem this tool removes.
- agentscribe transforms one source into each tool's real format, and `check`
  turns "did someone forget to update a file?" into a CI failure.

## Design goals

- **Near-zero dependencies.** Pure standard library on Python 3.11+ (a single
  `tomli` backport on 3.9–3.10).
- **Deterministic output.** LF endings, stable ordering — diffs stay clean.
- **Conservative linting.** Actionable findings over noisy ones.

## Contributing

Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). This project
dogfoods itself: its own `CLAUDE.md`, Cursor, and Copilot files are generated
from [`AGENTS.md`](AGENTS.md) by `agentscribe sync`, and CI runs `agentscribe check`.

## License

[MIT](LICENSE)
