Skip to content

AGENTS.md

Latest commit

 

History

History
167 lines (158 loc) · 16.9 KB

AGENTS.md

File metadata and controls

167 lines (158 loc) · 16.9 KB
Raw

AGENTS.md

Purpose

  • Repo: coding-ethos
  • Overview: Python CLI plus bundled ETHOS enforcement package for generating ETHOS.md, AGENTS.md, CLAUDE.md, GEMINI.md, and supporting agent context files from a shared YAML ethos plus an optional repo-specific overlay.

Commands

  • install: make install
  • status: make status
  • test: make test
  • check: make check
  • validate: make validate
  • pre-commit: make pre-commit
  • install-hooks: make install-hooks
  • pre-push: make pre-push
  • go-test: make go-test
  • sync-tool-configs: make sync-tool-configs
  • check-tool-configs: make check-tool-configs
  • sync-gemini-prompts: make sync-gemini-prompts
  • check-gemini-prompts: make check-gemini-prompts
  • pre-commit-all: make pre-commit-all
  • generate: make generate
  • merge-existing: make generate-merge
  • help: make help

Key Paths

  • makefile: Makefile
  • source: coding_ethos/
  • cli: coding_ethos/cli.py
  • loaders: coding_ethos/loaders.py
  • renderers: coding_ethos/renderers.py
  • markdown_seed: coding_ethos/markdown_seed.py
  • merge_logic: coding_ethos/merging.py
  • gemini_prompt_pack: go/internal/geminiprompts/
  • presets: coding_ethos/presets.py
  • models: coding_ethos/models.py
  • tests: tests/test_cli.py
  • primary_ethos: coding_ethos.yml
  • repo_overlay: repo_ethos.yml
  • overlay_example: repo_ethos.example.yml
  • bundle_config: config.yaml
  • consumer_override_example: repo_config.example.yaml
  • precommit_bundle: pre-commit/
  • go_hook_runner: go/cmd/coding-ethos-hook-runner/

Repo Notes

  • coding_ethos.yml is the shared source contract; repo_ethos.yml is the repo-local refinement layer.
  • config.yaml is the bundle-wide enforcement source of truth; consuming repos refine it with repo_config.yaml-style overrides at their own repo root.
  • The Makefile is the preferred repo-local operator interface for generation, generated repo-root tool configs, the generated Gemini prompt pack, and bundled Go hook workflows.
  • The bundled ETHOS pre-commit enforcement package lives under pre-commit/ and installs direct Go runner shims into .git/hooks/.
  • style.python_version is the single Python-version authority across generated tool configs, the pyupgrade autofix pass, and repo-root consistency checks for .python-version, pyproject.toml, mypy.ini, pyrightconfig.json, ruff.toml, and .golangci.yml's lll line-length setting.
  • Hook runtime, policy enforcement, Python policy checks, and bundled analyzer orchestration now live in go/cmd/coding-ethos-hook-runner/ inside the shared Go module; pre-commit/hooks/ contains hook assets and narrow bootstrap shims.
  • Source-aware enforcement follows the AST/CEL/SARIF architecture documented in docs/AST_CEL_SARIF_ARCHITECTURE.md. Extend shared Go Tree-sitter fact collection first, express configurable decisions in CEL where possible, and let SARIF carry stable AST identity and remediation metadata. Do not add ad hoc text scanners or policy-specific AST walkers before checking this path.
  • If you fix hook, policy, lint-capture, runtime, generated-config, or parent integration behavior, run make build before claiming the bug is fixed. Without rebuilding, the parent repo can keep executing stale runtime binaries and configs, which means the fix has not actually landed for agents.
  • Prefer replacing shell and Python implementation glue with Go wherever practical. Every branch should identify at least one related shell or Python path that can move into compiled Go, even if the branch only documents why it is not the right time to migrate it.
  • The CLI should stay thin. Most behavior belongs in loaders, renderers, markdown seeding, and merge helpers.
  • Gemini prompt authoring now lives under pre-commit/prompts/ as Jinja templates; the active Go runner should consume generated prompt packs instead of duplicating prompt text in code.
  • When flags, output layout, merge behavior, or overlay semantics change, update README.md, repo_ethos.example.yml, and tests/test_cli.py in the same change.
  • This repo currently exposes make check as its canonical automated verification gate; use make test or uv run pytest only as focused Python-test helpers.

Agent Operating Discipline

  • Load .agents/skills/agent-operating-discipline/SKILL.md before broad implementation, refactor, review, or debugging work.
  • State task interpretation, assumptions, ambiguity, and trade-offs before broad changes.
  • Prefer the smallest sufficient implementation; avoid speculative abstractions, options, and extension points.
  • Keep edits surgical: every changed line should trace to the request or cleanup directly caused by the change.
  • Define verifiable success criteria and run focused checks before claiming completion.

Non-Negotiable Ethos

  • 01. SOLID is Law: Enforce SOLID and simplicity; remove speculative abstractions. [tags: architecture, design, simplicity] Quick ref: Enforce SOLID and simplicity; remove speculative abstractions. | We do not view the SOLID principles as academic suggestions. | SOLID governs structure; these principles govern complexity:
  • 02. Fail Fast, Fail Hard (Overview): Crash early on ambiguous startup and configuration states instead of degrading silently. [tags: startup, reliability, configuration] Quick ref: Crash early on ambiguous startup and configuration states instead of degrading silently. | Ambiguity is the enemy of reliability.
  • 03. No Conditional Imports: Treat required imports as hard dependencies and fail immediately if they are missing. [tags: dependency, startup, reliability] Quick ref: Treat required imports as hard dependencies and fail immediately if they are missing. | We strictly ban the "soft dependency" pattern.
  • 04. Static Analysis is the First Line of Defense: Make ruff and mypy blocking quality gates rather than advisory tools. [tags: tooling, linting, typing] Quick ref: Make ruff and mypy blocking quality gates rather than advisory tools. | We rely on linters (ruff) and type checkers (mypy) to catch errors before the code ever runs. | Static analysis belongs in enforced local hooks and CI, not in optional tribal knowledge.
  • 05. No Optional Types for Required Dependencies: Model required dependencies as non-optional and default to full-strength behavior. [tags: typing, dependency, defaults] Quick ref: Model required dependencies as non-optional and default to full-strength behavior. | We strictly ban | None (or Optional) for dependencies that are required for correct operation. | We strictly ban building suboptimal paths that users must opt out of.
  • 06. No Conditional Validation: Run required validation unconditionally; a missing component is itself a failure. [tags: validation, reliability, startup] Quick ref: Run required validation unconditionally; a missing component is itself a failure. | We strictly ban validation checks that skip based on component availability.
  • 07. No "If Available" Capability Checks: Validate required capabilities at startup instead of probing for them at runtime. [tags: validation, dependency, startup] Quick ref: Validate required capabilities at startup instead of probing for them at runtime. | We strictly ban runtime capability checks that create silent degradation paths.
  • 08. Validation at the Gate: Validate configuration, schema, and extensions during bootstrap rather than on first use. [tags: validation, configuration, startup] Quick ref: Validate configuration, schema, and extensions during bootstrap rather than on first use. | Configuration, schema, and extension availability are validated immediately upon container initialization.
  • 09. No Inline CLI Environment Variables: Route configuration through validated bootstrap paths instead of inline shell environment variables. [tags: configuration, workflow, tooling] Quick ref: Route configuration through validated bootstrap paths instead of inline shell environment variables. | We strictly ban setting environment variables inline on CLI commands.
  • 10. Robustness in Motion (Runtime): Treat startup misconfiguration and runtime transient failures as different classes of problems. [tags: runtime, reliability, resilience] Quick ref: Treat startup misconfiguration and runtime transient failures as different classes of problems. | While we are ruthless during startup, the opposite pattern applies once the system is running. | These two failure modes require opposite responses:
  • 11. Radical Visibility: Log important decisions with context and instrument the system with metrics. [tags: observability, logging, metrics] Quick ref: Log important decisions with context and instrument the system with metrics. | We believe that if an event wasn't logged, it didn't happen. | Everything is Logged: Ingestion steps, query rewrites, cache hits/misses, and decision branches must emit logs.
  • 12. Protocol-First Design: Define and verify interfaces before writing or referencing implementations. [tags: architecture, interfaces, typing] Quick ref: Define and verify interfaces before writing or referencing implementations. | Implementations are ephemeral; Protocols are forever. | Before referencing any Protocol, type, or interface, verify it exists in the codebase.
  • 13. Universal Responsibility: Own every error or warning you touch and verify claims with evidence. [tags: ownership, quality, verification] Quick ref: Own every error or warning you touch and verify claims with evidence. | Every bug and every lint warning is everyone's responsibility. | We do not accept excuses based on the origin of a problem.
  • 14. Linting as Code Quality Enforcement: Resolve lint findings with structural fixes; suppress only with documented necessity. [tags: linting, quality, refactor] Quick ref: Resolve lint findings with structural fixes; suppress only with documented necessity. | Linters are not suggestions; they are automated code reviewers enforcing our standards. | Do not weaken hooks or broaden suppressions just to get green faster.
  • 15. Feedback as a First-Class Citizen: Retrieve and address all review feedback proactively. [tags: collaboration, feedback, review] Quick ref: Retrieve and address all review feedback proactively. | Pull request feedback is not bureaucratic overhead; it is a critical quality gate. | We do not wait for feedback to find us.
  • 16. No Self-Promotion: Let the work speak and omit self-congratulatory commentary. [tags: communication, collaboration] Quick ref: Let the work speak and omit self-congratulatory commentary. | The work speaks for itself. | Commit messages describe what changed and why.
  • 17. Functional Idioms: Use Python's functional tools when they make code clearer and more local. [tags: python, style, simplicity] Quick ref: Use Python's functional tools when they make code clearer and more local. | Python's itertools and functools modules exist for a reason. | If a function is pure (same inputs → same outputs) and expensive, cache it.
  • 18. Documentation as Contract: Keep public behavior documented as part of the interface contract. [tags: documentation, api, quality] Quick ref: Keep public behavior documented as part of the interface contract. | An undocumented public function is a bug. | Every public function must have a Google-style docstring with:
  • 19. One Path for Critical Operations: Keep one explicit, validated path for critical operations. [tags: workflow, validation, reliability] Quick ref: Keep one explicit, validated path for critical operations. | When there are multiple ways to accomplish a critical operation, bugs hide in the less-traveled path. | We strictly ban boolean parameters that fundamentally change what a function does.
  • 20. Forward Motion Only: Fix the current state instead of blaming history or prior authors. [tags: ownership, workflow, collaboration] Quick ref: Fix the current state instead of blaming history or prior authors. | We look forward, not backward. | We strictly ban switching to main or other branches to verify whether errors "existed before."
  • 21. No Rationalized Shortcuts: Do not discard work or bypass safety checks in the name of pragmatism. [tags: workflow, safety, git] Quick ref: Do not discard work or bypass safety checks in the name of pragmatism. | We strictly ban any action that discards, bypasses, or destroys work under the rationalization of "pragmatism," "efficiency," or "complexity." | The following thought patterns are explicitly banned.
  • 22. Testing as Specification: Treat tests as executable behavioral contracts and update them with code changes. [tags: testing, quality, specification] Quick ref: Treat tests as executable behavioral contracts and update them with code changes. | Tests are not afterthoughts—they are the executable specification of system behavior. | There is no such thing as an "acceptable" test failure or a "known flaky" test.
  • 23. Exception Hierarchy and Error Messages: Use precise exception types and actionable, context-rich error messages. [tags: errors, debugging, api] Quick ref: Use precise exception types and actionable, context-rich error messages. | Exceptions are not just error handling—they are communication. | All application exceptions inherit from a base exception that carries structured context:
  • 24. Security by Design: Design for least privilege, validation, and safe defaults from the start. [tags: security, validation, defaults] Quick ref: Design for least privilege, validation, and safe defaults from the start. | Security is not a feature to be added later—it is a property of the design. | Secrets, credentials, and API keys must never appear in source code, configuration files, or commit history.
  • 25. Sub-Agent Delegation and Context Isolation: Use specialized agents with scoped context instead of overloading one thread. [tags: delegation, context, workflow] Quick ref: Use specialized agents with scoped context instead of overloading one thread. | We mandate extensive use of sub-agents, plugins, and skills for complex operations—especially git commits and pushes that must pass quality gates. | Borrowing from Go's concurrency philosophy: "Share memory by communicating, don't communicate by sharing memory." For discrete tasks with clear inputs and outputs, spawn a fresh sub-agent with its own context and pass only the specific inst
  • 26. Evidence-Based Engineering and Decision Quality: Understand, plan, execute, and validate with evidence; measure before optimizing and make trade-offs explicit. [tags: evidence, planning, risk, quality] Quick ref: Evidence > assumptions; runnable behavior and measurements outrank speculation. | Understand -> plan -> execute -> validate, using batching and context awareness when they reduce waste. | Evaluate decisions across quality, reversibility, risk, and human impact.
  • 28. Functional Testing Is the Proof: Prove critical behavior with real functional workflows before relying on unit tests or mocks. [tags: testing, verification, quality, workflow] Quick ref: Real workflow tests are the primary evidence that core behavior works. | Unit tests are useful but low-value compared with tests that exercise the actual user path. | Mocking distorts reality; use it only as a last resort for narrow, explicitly bounded cases.
  • 900. Generated Files Are Derived Artifacts: Edit the source ethos or renderer code first, then regenerate the checked-in agent files. [tags: documentation, workflow, testing] Quick ref: Treat coding_ethos.yml and repo_ethos.yml as the source inputs for checked-in agent docs. | Regenerate AGENTS.md, CLAUDE.md, GEMINI.md, ETHOS.md, and supporting docs after changing ethos inputs or renderers. | Review generated diffs instead of hand-editing derived markdown files.

Detail Docs

  • Deep reference notes live in .agents/ethos/README.md and the linked per-principle docs.

Codex Notes

  • Keep the root file concise, operational, and repo-specific.
  • Put durable project rules in AGENTS.md and link to deep docs instead of pasting long prose.
  • Prefer changing the narrow module that owns the behavior instead of spreading logic across cli.py and multiple helpers.
  • After changing coding_ethos.yml, repo_ethos.yml, or renderer behavior, regenerate this repo's checked-in agent files before finishing.
  • Treat generated markdown files as derived artifacts; hand-edit them only when the task is explicitly about the generated output itself.
  • On each branch, look for one related shell or Python implementation path that can be moved into Go, and either migrate it or record the concrete blocker.
  • For source-aware policy, use docs/AST_CEL_SARIF_ARCHITECTURE.md first: Go collects AST facts, CEL decides configurable policy, and SARIF reports stable findings.
  • After fixing hook, policy, lint-capture, runtime, generated-config, or parent integration behavior, run make build; otherwise parent-repo agents may still execute stale binaries or configs.