agentscribe: Instructions file for GitHub Copilot

agentscribe

Guidance for AI coding agents working in this repository. This file is the single source of truth. The tool-specific files (CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md) are generated from it by agentscribe sync — never edit them by hand.

Overview

agentscribe is a small CLI + library that generates tool-specific AI instruction files (CLAUDE.md, Cursor rules, Copilot instructions, ...) from a single AGENTS.md, and validates that source. The code lives under src/agentscribe/:

• config.py — load configuration from agentscribe.toml or [tool.agentscribe].
• source.py — parse the source and apply agentscribe:only/except/ignore scoping.
• targets.py — the registry of output files and how each is formatted.
• sync.py — plan, write, and drift-check target files.
• lint.py — conservative static checks over the source.
• detect.py / templates.py — power agentscribe init.
• cli.py — argparse front end.

Setup & commands

Task	Command
Install (editable, with dev deps)	pip install -e ".[dev]"
Run tests	pytest
Lint	ruff check .
Format	ruff format .
Run the tool	agentscribe <command> (e.g. agentscribe sync)

Code style & conventions

• Target Python 3.9+. Every module starts with from __future__ import annotations so built-in generics (list[str]) are safe in annotations.
• Keep runtime dependencies at zero (the only exception is the tomli backport on Python < 3.11). Do not add dependencies without strong justification.
• Match the surrounding style; keep functions small and pure where possible.
• Generated output must stay deterministic: LF line endings, stable ordering.

Testing

• Run the full suite with pytest before considering a change done.
• Add or update tests in tests/ for any behavior you change.
• Every CLI command and lint rule should have coverage.