Skip to content

AGENTS.md

Latest commit

 

History

History
111 lines (80 loc) · 3.91 KB

AGENTS.md

File metadata and controls

111 lines (80 loc) · 3.91 KB
Raw

AGENTS.md

Purpose

This repository contains a Python reference implementation of intentc, a compiler that turns intent packages into verifiable artifacts.

Agents working in this repo should preserve deterministic compiler behavior and favor small, testable changes.

Environment

  • Language: Python
  • Environment and dependency manager: uv
  • Pinned Python: 3.14.2

Setup

  • Sync dependencies: uv sync --dev
  • Run commands inside the project environment: uv run <command>

Core libraries

  • PyYAML for intent authoring input
  • jsonschema for schema validation
  • typer for the CLI
  • pytest for tests
  • ruff for linting

Coding instructions

  • Keep modules small and focused on one compiler concern.
  • Prefer creating a newer small module with a clear single responsibility and public API over extending an existing module that already has a different concern.
  • Start a module as a single file such as mymodule.py.
  • If a module grows too large, split it into a package such as mymodule/, but keep the responsibility clear and avoid nested packages.
  • Design public APIs explicitly. Public APIs are classes or functions intended for use by other modules.
  • Add proper unit tests for public APIs.
  • Modules should depend only on public APIs from other modules.
  • Do not use non-public APIs across modules.
  • Treat names prefixed with _ as non-public implementation details.
  • Use type hints on public functions and prefer explicit return types.
  • Favor pure functions for normalization, validation, and artifact generation.
  • Use pathlib for filesystem work.
  • Keep I/O at the edges of the codebase.
  • Prefer dataclasses or typed mappings over loose dictionary mutation.
  • Raise explicit domain-specific errors for schema, normalization, and compile failures.
  • Keep output deterministic by sorting keys and normalizing ordering before serialization.

Quality gates

Before finishing a change, keep ruff clean and cover behavior with pytest.

Common checks:

  • uv run ruff check intentc tests tools
  • uv run pytest

For compiler smoke coverage:

  • uv run python tools/intentc/scripts/ci_compile_gate.py

Primary repo references

Use these files as the planning and specification sources of truth:

  • docs/intents/webhook-idempotency.intent.yaml
  • planning/intentc/implementation-plan.md
  • planning/intentc/backlog.yaml
  • planning/intentc/enforcement-implementation-plan.md
  • planning/intentc/enforcement-backlog.yaml
  • planning/intentc/traceability-matrix-template.yaml
  • planning/intentc/risk-and-decisions.md
  • planning/intentc/enforcement-risk-and-decisions.md
  • prompts/02-intentc-enforcement.prompt.md
  • tools/intentc/schema/intent-package-v1alpha1.schema.json
  • tools/intentc/spec/compiler-pipeline.md
  • tools/intentc/spec/generation-manifest.schema.json

Main workflows

Validate an intent

uv run python -m intentc validate docs/intents/webhook-idempotency.intent.yaml

Compile an intent

uv run python -m intentc compile docs/intents/webhook-idempotency.intent.yaml --out /tmp/intentc-build

Expected compile outputs include:

  • normalized.intent.json
  • traceability.graph.json
  • clauses.index.json
  • reports/coverage-map.json
  • reports/missing-coverage.json
  • tests/*.feature
  • tests/test_inv_*.py
  • policies/**
  • runtime/**
  • generation-manifest.json

Regenerate the manifest

uv run python -m intentc generation-manifest /tmp/intentc-build/normalized.intent.json

Agent behavior expectations

  • Prefer minimal, working increments.
  • Do not introduce nondeterministic output formats.
  • When modifying compiler outputs, update tests that assert emitted artifacts.
  • When changing manifest structure, also update the manifest schema and related tests.
  • When working on enforcement, align with planning/intentc/enforcement-backlog.yaml and prompts/02-intentc-enforcement.prompt.md.
  • Keep changes consistent with the repository's Python-first, CLI-driven workflow.