agent-context-md 0.1.0__tar.gz

agent_context_md-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,22 @@
+---
+name: Bug report
+about: Report incorrect scanning, generation, linting, or update behavior.
+labels: bug
+---
+
+## What Happened
+
+## Expected Behavior
+
+## Reproduction
+
+```bash
+agents-md --version
+agents-md init --no-llm --dry-run
+```
+
+## Repository Signals
+
+- Language/framework:
+- Package manager:
+- Existing AGENTS.md:

agent_context_md-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,13 @@
+---
+name: Feature request
+about: Propose a focused improvement.
+labels: enhancement
+---
+
+## Problem
+
+## Proposed Behavior
+
+## Why This Belongs In v1
+
+## Alternatives Considered

agent_context_md-0.1.0/.github/actions/agents-md-lint/action.yml

@@ -0,0 +1,20 @@
+name: agents-md lint
+description: Lint an AGENTS.md file and fail when the score is below a threshold.
+inputs:
+  path:
+    description: Path to AGENTS.md
+    required: false
+    default: AGENTS.md
+  threshold:
+    description: Minimum accepted lint score
+    required: false
+    default: "60"
+runs:
+  using: composite
+  steps:
+    - name: Install agents-md from action source
+      shell: bash
+      run: python -m pip install "$GITHUB_ACTION_PATH/../../.."
+    - name: Lint AGENTS.md
+      shell: bash
+      run: agents-md lint "${{ inputs.path }}" --check --threshold "${{ inputs.threshold }}"

agent_context_md-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: python -m pip install -e .[dev]
+      - run: python -m pytest
+      - run: python -m build
+
+  agents-md:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: python -m pip install -e .
+      - run: agents-md lint AGENTS.md --check --threshold 70

agent_context_md-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agent-context-md
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

agent_context_md-0.1.0/AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS.md
+
+Generated by `agents-md`. Keep manual notes outside managed sections so `agents-md update` can preserve them.
+
+<!-- agents-md:start:stack -->
+## Stack
+- Ci: GitHub Actions
+- Language: Python
+- Package: agent-context-md 0.1.0
+- Package Manager: pip
+- Runtime: Python >=3.11
+<!-- agents-md:end:stack -->
+
+<!-- agents-md:start:commands -->
+## Commands
+- install: `python -m pip install -e .[dev]` from pyproject.toml.
+- build: `python -m build` from pyproject.toml.
+- test: `python -m pytest` from pyproject.toml.
+<!-- agents-md:end:commands -->
+
+<!-- agents-md:start:testing -->
+## Testing
+- Full suite: `python -m pytest`
+- Single test: `python -m pytest tests/test_cli.py::test_init_no_llm_writes_agents -xvs`
+- Prefer the narrowest relevant test while iterating, then run the broader check before release changes.
+<!-- agents-md:end:testing -->
+
+<!-- agents-md:start:conventions -->
+## Conventions
+- Package code uses a `src/` layout; import through the installed package path. (src/)
+- Python tests live under `tests/` as `test_*.py` files. (tests/)
+- Custom Python error class detected: `LlmError`. (src/agents_md/llm.py)
+<!-- agents-md:end:conventions -->
+
+<!-- agents-md:start:boundaries -->
+## Boundaries
+### Always Do
+- Run the narrowest relevant test before handing off a code change.
+### Ask First
+- Ask before deleting files, rewriting public history, changing release/package metadata, or running commands that mutate databases/infrastructure.
+### Never Do
+- Never commit secrets, tokens, or `.env` files.
+- Never overwrite a hand-written AGENTS.md without `--force` or an explicit confirmation.
+- Never modify `vendor/` unless the user explicitly asks.
+<!-- agents-md:end:boundaries -->
+
+<!-- agents-md:start:security -->
+## Security
+- Treat API keys as environment-only configuration; do not write them into AGENTS.md or generated logs.
+- Prefer `--no-llm` in CI unless a provider key is intentionally configured for synthesis.
+- Review generated files before publishing because AGENTS.md is meant to guide automated agents.
+<!-- agents-md:end:security -->
+
+<!-- agents-md:fingerprint {"files":{".github/workflows/ci.yml":"e3fb26fa9176b56ec99474e5a98b11f0fa1b62bbcf67a3211c125f470840e8b8",".github/workflows/publish.yml":"9c2a4ee53040cd1ff89f0ebb333470cfcf645c4d99c7b8452ab2e5f2399b8c7b","MANIFEST.in":"85d1c28249eb464538e1bbdaa1ac639db1af0753ab774b05111b4fa5690ec19b","pyproject.toml":"e46ba844a6233472372f6a03eaac0725bdf8ce82787ce06a7665c1239a2b88d1"},"version":1} -->

agent_context_md-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Thanks for helping improve `agents-md`.
+
+## Local Setup
+
+```bash
+python -m pip install -e .[dev]
+python -m pytest
+```
+
+Run one focused test while iterating:
+
+```bash
+python -m pytest tests/test_quality.py::test_scores_core_sections -xvs
+```
+
+## Pull Request Expectations
+
+- Keep the core package dependency-light.
+- Add or update tests for scanner, generator, lint, or CLI behavior changes.
+- Preserve non-destructive update semantics.
+- Keep public docs accurate and short.
+- Do not commit secrets, real API keys, downloaded browser metadata, or local
+  cache/build artifacts.
+
+## Product Guardrails
+
+Ask first before changing:
+
+- Quality score thresholds or scoring weights
+- Deduplication rules
+- Managed marker comment format
+- Default LLM provider/model choices
+- Public package metadata
+
+These choices shape user trust and should be discussed as product behavior.

agent_context_md-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Osmane B.
+
+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.

agent_context_md-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include AGENTS.md
+include CONTRIBUTING.md
+recursive-include .github/actions *.yml
+recursive-include .github/ISSUE_TEMPLATE *.md
+recursive-include .github/workflows *.yml
+recursive-include docs *.svg

agent_context_md-0.1.0/PKG-INFO

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: agent-context-md
+Version: 0.1.0
+Summary: Generate short, useful AGENTS.md files without repeating what the repo already says.
+Author: Osmane B.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/osmaneb23/agents-md
+Project-URL: Issues, https://github.com/osmaneb23/agents-md/issues
+Keywords: agents.md,ai,cli,codex,claude,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.76; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=2.9; extra == "openai"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.52; extra == "gemini"
+Provides-Extra: dev
+Requires-Dist: build>=1.3; extra == "dev"
+Requires-Dist: pytest>=9.0; extra == "dev"
+Dynamic: license-file
+
+# agents-md
+
+Generate `AGENTS.md` context files that actually help AI coding agents.
+
+[![CI](https://github.com/osmaneb23/agents-md/actions/workflows/ci.yml/badge.svg)](https://github.com/osmaneb23/agents-md/actions)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+![agents-md terminal demo](docs/demo.svg)
+
+*Demo runs on a JS/TS repo. Simpler repos generate shorter files.*
+
+---
+
+ETH Zurich [tested AI coding agents](https://arxiv.org/abs/2602.11988) across 8 benchmarks with auto-generated context files, hand-written files, and nothing. Auto-generated files made performance worse in 5 of 8 cases. Inference cost jumped 20-23%. Tasks took more steps.
+
+The cause: generators write what agents can already read. Your README, your folder structure, your lint rules — the agent figures all of this out on its own. Putting it in AGENTS.md means reading it again on every task and paying for it each time.
+
+`agents-md` reads your existing docs before writing anything. Everything the agent can discover on its own gets filtered out. What's left — exact commands with real flags, conventions the agent would get wrong, hard limits — is what ends up in the file.
+
+This repo's own AGENTS.md was generated by `agents-md`.
+
+---
+
+## Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [Sample output](#sample-output)
+- [How deduplication works](#how-deduplication-works)
+- [Quality scoring](#quality-scoring)
+- [GitHub Action](#github-action)
+- [What gets detected](#what-gets-detected)
+- [Alternatives](#alternatives)
+- [Development](#development)
+
+---
+
+## Install
+
+```bash
+# Until the first PyPI release is live:
+python -m pip install "git+https://github.com/osmaneb23/agents-md.git"
+
+# After PyPI publication:
+pip install agent-context-md
+```
+
+Zero runtime dependencies. No Node.js, no Docker.
+
+LLM provider SDKs are optional extras — the tool works fully offline without them. From a source checkout:
+
+```bash
+python -m pip install -e .[anthropic]
+python -m pip install -e .[openai]
+python -m pip install -e .[gemini]
+```
+
+After PyPI publication, use `pip install agent-context-md[anthropic]` or run it with uv:
+
+```bash
+uvx --from agent-context-md agents-md init
+```
+
+---
+
+## Usage
+
+**Generate:**
+
+```bash
+# Static analysis only, no API key needed
+agents-md init --no-llm
+
+# With LLM synthesis (picks up key from env)
+ANTHROPIC_API_KEY=sk-...  agents-md init
+OPENAI_API_KEY=sk-...     agents-md init
+GEMINI_API_KEY=...        agents-md init
+
+# Explicit provider + model
+agents-md init --provider anthropic --model <model-id>
+
+# Preview without writing anything
+agents-md init --no-llm --dry-run --verbose
+
+# Append managed sections to a hand-written file
+agents-md init --merge
+```
+
+**Lint** — works on any AGENTS.md, including hand-written ones:
+
+```bash
+agents-md lint                         # score ./AGENTS.md
+agents-md lint path/to/AGENTS.md       # specific file
+agents-md lint --check --threshold 70  # exit 1 if score < 70
+agents-md lint --fix                   # remove duplicate and style-rule lines
+agents-md lint --json                  # machine-readable output
+```
+
+**Keep it current:**
+
+```bash
+agents-md update   # refresh managed sections, leave your notes alone
+agents-md diff     # show what changed in the repo since last generation
+```
+
+---
+
+## Sample output
+
+`agents-md init --no-llm` on a Next.js + TypeScript repo:
+
+```markdown
+## Stack
+- CI: GitHub Actions
+- Framework: Next.js 15.3
+- Language: TypeScript (strict mode)
+- Package Manager: pnpm 10.0.0
+- Test Runner: vitest 3.0.0
+
+## Commands
+- install: `pnpm install`
+- run: `pnpm dev`
+- build: `pnpm build`
+- test: `pnpm test`
+- lint: `pnpm lint`
+
+## Testing
+- Full suite: `pnpm test`
+- Single test: `pnpm vitest run src/auth/login.test.ts -t "should reject expired tokens"`
+- Prefer the narrowest test while iterating. Run the full suite before handing off.
+
+## Boundaries
+### Always Do
+- Run the narrowest relevant test before handing off a code change.
+### Ask First
+- Ask before running `pnpm db:migrate` — it touches migrations.
+- Ask before deleting files, rewriting history, or changing release metadata.
+### Never Do
+- Never commit secrets, tokens, or `.env` files.
+- Never overwrite a hand-written AGENTS.md without `--force` or explicit confirmation.
+```
+
+Sections are wrapped in `<!-- agents-md:start/end:section-name -->` markers. `agents-md update` uses them to refresh individual sections without touching anything you added by hand.
+
+---
+
+## How deduplication works
+
+Before writing anything, the tool reads every Markdown file in your project root and `docs/`. It extracts facts from them — commands, framework mentions, structural notes. Then for each candidate line from the extractors, it asks: does this add anything the agent can't get from those docs?
+
+```
+README says:  "We use pnpm. Run `pnpm install` to get started."
+Extractor:    install: pnpm install
+
+→ Removed. The agent can read the README.
+
+README says:  "Run the tests before pushing."
+Extractor:    single test: pytest tests/test_auth.py::test_login -xvs
+
+→ Kept. The README is vague. The exact command with flags is new.
+```
+
+Boundaries and security lines are always kept, even when they overlap with the README.
+
+Pass `--verbose` to see the full list of what was removed and why.
+
+---
+
+## Quality scoring
+
+`agents-md lint` scores any AGENTS.md out of 100 and tells you exactly what to fix.
+
+| Criterion | Points |
+|---|---|
+| Commands section with 2+ exact commands | 10 |
+| Commands include real flags (`-x`, `--watch`, etc.) | 15 |
+| Single-test command targeting one file or function | 10 |
+| Three-tier boundaries (Always / Ask First / Never) | 20 |
+| Dedicated testing section | 10 |
+| File under 150 lines | 15 |
+| No README duplication | 15 |
+| No linter-owned style rules | 5 |
+
+Score guide:
+
+- **85-100** — This file will improve agent performance.
+- **65-84** — A few improvements would help.
+- **45-64** — Key sections are missing or there's redundant content.
+- **0-44** — This file is likely slowing agent sessions down.
+
+---
+
+## GitHub Action
+
+Fail PRs when the score drops below a threshold:
+
+```yaml
+- uses: actions/checkout@v6
+- uses: actions/setup-python@v6
+  with:
+    python-version: "3.13"
+- uses: osmaneb23/agents-md/.github/actions/agents-md-lint@main
+  with:
+    path: AGENTS.md
+    threshold: "70"
+```
+
+Pin to a release tag once you cut the first release.
+
+---
+
+## What gets detected
+
+<details>
+<summary><strong>Commands</strong></summary>
+
+Scripts and tasks from `package.json`, `Makefile`, `pyproject.toml` (taskipy, poe), `Justfile`, `Taskfile.yml`. Single-test commands are inferred for pytest, unittest, Jest, Vitest, Mocha, Cargo, and Go.
+
+</details>
+
+<details>
+<summary><strong>Stack</strong></summary>
+
+Package manager detected from lock files, never guessed. Framework, language, TypeScript strict mode (from tsconfig), runtime, test runner, linter, type checker, CI system.
+
+</details>
+
+<details>
+<summary><strong>Conventions</strong></summary>
+
+`src/` layout, test naming patterns, TypeScript path aliases, named-export-only modules, barrel files with their import alias, `Result<T,E>` error-as-value patterns, centralized HTTP wrappers, catch blocks that intentionally return fallback values, `.env.example` variables, test fixture and factory directories. Only things an agent would plausibly get wrong on the first attempt.
+
+</details>
+
+<details>
+<summary><strong>Fingerprint</strong></summary>
+
+SHA-256 hashes of key manifests stored in a comment at the bottom of the file. `agents-md diff` compares them against the current state and tells you whether an update is worth running.
+
+</details>
+
+Supported: **Python**, **JavaScript/TypeScript**, **Go**, **Rust**.
+
+---
+
+## Alternatives
+
+| Tool | What it does | Where it falls short |
+|---|---|---|
+| `agents-init` (npm) | Sets up AGENTS.md + MCP config + subagents | No dedup filter. Generates the kind of bloated file the ETH study warns against. |
+| `GenerateAgents.md` (PyPI) | DSPy-based generation, any model | DSPy is a heavy dependency. No dedup. |
+| `AGENTS.md_generator` (Python) | Safe-by-default skeleton | Intentionally minimal. You still fill it in manually. |
+| Hand-written | Full control | Drifts with the codebase. No quality feedback. |
+
+---
+
+## Design decisions
+
+- **Zero runtime dependencies.** The core package installs in seconds. LLM SDKs are opt-in extras.
+- **Non-destructive updates.** `agents-md update` only touches content inside managed markers. `lint --fix` creates a `.bak` before writing. `init` prompts before overwriting.
+- **No guessing.** If the package manager can't be determined from lock files, it's left blank. A wrong command is worse than a missing one.
+- **Short over padded.** The LLM synthesis prompt explicitly tells the model to refuse to pad. A 30-line file beats a 150-line one if the repo is simple.
+- **No Node.js required.** Python only, works anywhere Python runs.
+
+---
+
+## Development
+
+The project's own [AGENTS.md](AGENTS.md) has the authoritative commands, conventions, and boundaries. Check it before changing code or opening a PR.
+
+Before changing scoring weights, deduplication rules, or managed marker formats, open an issue. These are product decisions, not implementation details.
+
+Releases go through PyPI Trusted Publishing via `.github/workflows/publish.yml`. To publish: set up a pending publisher for project `agent-context-md`, repository `osmaneb23/agents-md`, workflow `publish.yml`, environment `pypi`, then run the publish workflow.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for PR expectations.
+
+---
+
+## Sources
+
+- ETH Zurich study: [arxiv.org/abs/2602.11988](https://arxiv.org/abs/2602.11988)
+- AGENTS.md open format: [github.com/agentsmd/agents.md](https://github.com/agentsmd/agents.md)
+- GitHub's analysis of 2,500+ AGENTS.md files: [github.blog](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)
+- Augment Code guide: [augmentcode.com/guides/how-to-build-agents-md](https://www.augmentcode.com/guides/how-to-build-agents-md)