Coding Ethos Docs

coding-ethos is policy as code for AI coding agents. It turns a repository’s engineering principles into generated agent instructions, CEL policy checks, Git hooks, MCP tools, SARIF output, runtime sandbox evidence, and CI gates.

Start Here

• README: project overview, quick start, supported agents, and common workflows.
• Repository analysis: source-of-truth boundaries, generated artifacts, and verification model.
• Strategic roadmap: major platform directions for MCP, CEL, SARIF, sandboxing, and agent remediation loops.
• Trust signals: OpenSSF Scorecard, Best Practices badge, security posture, and publication checklist.
• Supply-chain attestations: Scorecard publishing, GitHub artifact provenance, SBOMs, PyPI Trusted Publishing, checksums, and verification commands.
• Threat model: protected assets, actors, trust boundaries, risks, and out-of-scope claims.
• Release process: versioning, artifact, checklist, and release note expectations.
• Discussions plan: recommended GitHub Discussions categories and issue/discussion boundaries.
• Demo: verified MCP, command-block, lint-check, and SARIF excerpts plus a recording plan.
• Comparison: how coding-ethos relates to pre-commit, CodeQL, Semgrep, OPA, branch protection, and plain agent instructions.
• Integrations: Codex, Claude Code, Gemini CLI, MCP, GitHub Actions, GitLab CI, SARIF consumers, and managed static analysis.

AI Agent Policy Enforcement

coding-ethos is built for agentic development workflows where Codex, Claude Code, Gemini CLI, and human contributors need the same enforceable rules.

• MCP server: stdio MCP tools for policy checks, lint advice, SARIF remediation, risk summaries, and capability inspection.
• Integrations: setup notes for Codex, Claude Code, Gemini CLI, MCP clients, GitHub Actions, GitLab CI, SARIF consumers, and managed tools.
• Runtime sandboxing: Bubblewrap, cgroups, seccomp, network isolation, and least-privilege tool capabilities.
• Red-team suite: adversarial coverage for hook bypass, shell parsing, protected paths, MCP framing, SARIF, and sandbox behavior.

CEL Policy Language

CEL lets repos express narrow custom policies without adding a new Go evaluator for every rule. Principle-owned CEL policies live with the ETHOS principle they enforce.

• Policy language strategy: CEL inputs, helper functions, staged migration path, and limits.
• MCP server: policy explanation and policy check tools that expose compiled CEL behavior to agents.

SARIF And Code Scanning

SARIF turns local policy and static-analysis evidence into code-scanning, artifact, trend, and remediation workflows.

• CI/CD SARIF: generated GitHub Actions and GitLab CI gates.
• SARIF uses: remediation advice, risk summaries, trend analysis, editor loops, and policy feedback.
• SARIF editor integration: local workflows for developers and agents.

Hook And Tool Runtime

• Hook runtime bootstrap: checkout-local runtime artifacts, repair behavior, and consumer hook shims.
• Runtime publication: PyPI generator boundaries and the release-asset model for future compiled Go runtime distribution.
• Lint capture Go flow: managed lint capture through compiled Go request, target resolution, config validation, and normalized output.
• Source docs index: full document list for maintainers.