CtrlK
BlogDocsLog inGet started
Tessl Logo

mcollina/init

Creates, updates, or optimizes an AGENTS.md file for a repository with minimal, high-signal instructions covering non-discoverable coding conventions, tooling quirks, workflow preferences, and project-specific rules that agents cannot infer from reading the codebase. Use when setting up agent instructions or Claude configuration for a new repository, when an existing AGENTS.md is too long, generic, or stale, when agents repeatedly make avoidable mistakes, or when repository workflows have changed and the agent configuration needs pruning. Applies a discoverability filter—omitting anything Claude can learn from README, code, config, or directory structure—and a quality gate to verify each line remains accurate and operationally significant.

85

1.14x
Quality

94%

Does it follow best practices?

Impact

72%

1.14x

Average score across 5 eval scenarios

SecuritybySnyk

Passed

No known issues

Overview
Quality
Evals
Security
Files

task.mdevals/scenario-1/

Task

We've just onboarded a new developer and want to set up agent configuration for this repository so that AI tools can help effectively. Please create an AGENTS.md file in the repository root that will help AI coding assistants work productively with this codebase without making mistakes.

The repository files are inlined below.

Output

Produce a single file: AGENTS.md at the repository root.

Inlined repository files

pyproject.toml

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "acme-api"
version = "0.1.0"
description = "ACME internal API service"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.111.0",
    "uvicorn[standard]>=0.29.0",
    "sqlalchemy>=2.0.0",
    "alembic>=1.13.0",
    "psycopg2-binary>=2.9.9",
    "pydantic>=2.7.0",
    "pydantic-settings>=2.2.0",
    "httpx>=0.27.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "pytest-asyncio>=0.23.0",
    "pytest-cov>=5.0.0",
    "factory-boy>=3.3.0",
    "ruff>=0.4.0",
]

[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]
addopts = "--cov=src --cov-report=term-missing"

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]
ignore = ["E501"]

[tool.ruff.lint.isort]
known-first-party = ["acme_api"]

[tool.hatch.build.targets.wheel]
packages = ["src/acme_api"]

README.md

# acme-api

Internal REST API for the ACME platform, built with Python, FastAPI, and PostgreSQL.

## Stack

- **Language**: Python 3.11+
- **Framework**: FastAPI
- **Database**: PostgreSQL 15 (via SQLAlchemy 2.0 + Alembic)
- **Task queue**: None (kept simple intentionally)

## Repository layout

acme-api/ ├── src/ │ └── acme_api/ │ ├── routers/ # FastAPI route definitions │ ├── services/ # Business logic │ ├── models/ # SQLAlchemy ORM models │ ├── schemas/ # Pydantic request/response models │ └── db.py # Database session management ├── tests/ │ ├── unit/ │ └── integration/ ├── legacy/ # See note below ├── alembic/ # Database migrations └── pyproject.toml

## Installation

1. Install [uv](https://docs.astral.sh/uv/) if you haven't already:
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
  1. Install dependencies: 
    uv sync --extra dev
  2. Copy the environment template and fill in your local values: 
    cp .env.example .env

Running the development server

uv run uvicorn acme_api.main:app --reload --port 8001

The API will be available at http://localhost:8001. Note: the docs site and some older internal wiki pages reference port 8000 — that's outdated; the dev server has used 8001 since we hit a conflict with another local service last year.

Running tests

uv run pytest

Important: always use uv run pytest, not plain pytest. There is a known bug in one of our test fixtures that causes stale cache entries when pytest is invoked outside the uv-managed environment, leading to intermittent and hard-to-diagnose test failures. This is not enforced by configuration — it relies on developer/agent discipline.

Database migrations

uv run alembic upgrade head   # apply all pending migrations
uv run alembic revision --autogenerate -m "describe change"  # create new migration

Code style

Linting and formatting are handled by ruff, which is configured in pyproject.toml. Run the linter with:

uv run ruff check .
uv run ruff format .

CI will fail on any ruff violations.

The legacy/ directory

Do not delete or restructure legacy/. This directory contains code that has been superseded by the current src/acme_api/ structure and is not actively developed. However, three production services in the payments and notifications domains still import directly from it, and removing it will cause silent import errors in those services at runtime. Deprecation is tracked in ACME-1847; migration is scheduled but not yet complete.

Contributing

Open a pull request against main. All checks must pass before merge.

---

### `.github/workflows/ci.yml`

```yaml
name: CI

on:
  push:
    branches: ["main"]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4
        with:
          version: "0.4.x"
      - run: uv sync --extra dev
      - run: uv run ruff check .
      - run: uv run ruff format --check .

  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_USER: acme
          POSTGRES_PASSWORD: acme
          POSTGRES_DB: acme_test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4
        with:
          version: "0.4.x"
      - run: uv sync --extra dev
      - run: uv run pytest
        env:
          DATABASE_URL: postgresql://acme:acme@localhost:5432/acme_test

evals

scenario-1

criteria.json

task.md

SKILL.md

tile.json