Skip to content

Home

Jump to bottom
github-actions[bot] edited this page Oct 26, 2026 · 17 revisions

Home

Eric's Engineering Constitution is a reusable framework for AI-assisted software development standards. It gives teams a single source of truth for how humans and AI agents should work across repositories, then ships the scripts and templates needed to roll that standard into existing Git projects.

What you get

When a project adopts this constitution, it gains:

  • Shared engineering principles in CONSTITUTION.md
  • A required agent workflow in AI_WORKFLOW.md
  • Standards for testing, documentation, security, operations, architecture, releases, and roadmap hygiene
  • Bootstrap templates for governance files like README.md, TODO.md, CHANGELOG.md, AGENTS.md, CLAUDE.md, and ADRs
  • CI-ready governance tooling such as traceability and compliance checks
  • A standardized Eric's Engineering Constitution adoption badge for project READMEs

Repository map

  • Core standards: CONSTITUTION.md, AI_WORKFLOW.md, TESTING.md, DOCUMENTATION.md, SECURITY.md, OPERATIONS.md, ARCHITECTURE.md, RELEASES.md, TODO_GUIDELINES.md, INTEGRATION.md
  • Templates: templates/ contains the files copied into adopting repositories, including documentation stubs, agent-instruction bridges, workflows, and ADR scaffolding
  • Automation: scripts/ contains the bootstrap installer plus governance checkers and their test scripts
  • Examples: examples/sample-project/ shows the expected project shape after adoption, and examples/OPERATIONS.example.md is a worked operations runbook
  • MCP integration: mcp-server/ contains a small Node.js MCP server exposing constitution resources and a project-structure validation tool

Typical workflow

  1. Publish or clone this repository somewhere your projects can access.
  2. Run ./scripts/bootstrap.sh /path/to/project <repository-url> from this repo.
  3. Review .constitution-bootstrap/adoption-report.md in the target project.
  4. Merge any skipped template content into existing project files.
  5. Commit the constitution submodule plus the generated governance files.

Key scripts

scripts/bootstrap.sh

Initializes an existing Git repository with the constitution submodule and local governance files. It:

  • Adds constitution/ as a fixed-path Git submodule
  • Copies templates such as AGENTS.md, HELP.md, SECURITY.md, VERSION, and docs under docs/
  • Installs automation like .github/dependabot.yml, .github/pull_request_template.md, .github/CODEOWNERS, .github/workflows/constitution-version.yml, and .github/workflows/constitution-compliance.yml
  • Preserves existing files by default, writing merge-ready copies to .constitution-bootstrap/templates/
  • Injects or refreshes the standardized README adoption badge
  • Generates .constitution-bootstrap/adoption-report.md

scripts/check_traceability.sh

Validates that every bold requirement ID declared in docs/PRODUCT_REQUIREMENTS.md has an exact-match row with a non-gap verifying-test entry in docs/REQUIREMENTS_TRACEABILITY.md. It is designed to avoid substring collisions like FR-007 versus BB-FR-007.

scripts/check_compliance.sh

Checks whether an adopting repository includes the governance files the constitution expects. It reports:

  • Required files such as README.md, HELP.md, CHANGELOG.md, TODO.md, SECURITY.md, AGENTS.md, CLAUDE.md, VERSION, and the constitution/ submodule
  • Recommended files such as docs/SETUP.md, docs/COMMAND_REFERENCE.md, docs/TROUBLESHOOTING.md, docs/OPERATIONS.md, docs/TEST_PLAN.md, and docs/OTS_SOFTWARE.md
  • Product-facing files such as docs/PRODUCT_REQUIREMENTS.md and docs/REQUIREMENTS_TRACEABILITY.md

scripts/check_ots_inventory.sh

Cross-checks the runtime dependencies declared in root-level manifests (package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, Gemfile) against the OTS software inventory (docs/OTS_SOFTWARE.md), flagging any dependency with no inventory row. Matches inventory Name cells by exact value (case-insensitive), never substring, and deliberately reads runtime dependencies only (no devDependencies, [dev-dependencies], or // indirect requires). Warns by default, --strict to fail; wired into CI by constitution-ots.yml.

scripts/check_secrets.sh

Sweeps tracked and untracked-but-not-gitignored files for secrets that should never reach a remote:

  • Filenames shaped like credentials — .env, id_rsa, *.pem, *.key, *.p12, credentials.json, service-account JSON, .netrc, terraform.tfstate, and similar
  • Content patterns with high confidence — AWS access keys, GitHub/Slack tokens, PEM private key blocks, Google/Stripe API keys
  • .gitignore coverage of the filename patterns above (warn by default, --strict to fail)

A real hit (filename or content) always fails, with or without --strict. It is a zero-dependency (bash + Git only) baseline, not a replacement for a dedicated scanner like gitleaks or trufflehog on projects with unusually sensitive credentials. scripts/bootstrap.sh wires it in twice: a pre-push-stage pre-commit hook and the constitution-secrets.yml CI workflow.

scripts/run_all_tests.sh and .github/workflows/tests.yml

The framework's own "Full suite" and the workflow that runs it, plus a self-governance job that runs the shipped checkers against this repository on every pull request. scripts/test_checker_contract.sh holds every check_*.sh to the shared checker contract, and every checker emits GitHub Actions annotations so findings surface in the pull request UI.

scripts/check_instruction_templates.sh and scripts/check_skills.sh

The first verifies that every agent instruction file present carries the same guidance (session planning, project memory), so a rule added to one vendor file cannot be silently missing from another; the second validates the 25 skills under skills/. See Governance Checkers.

scripts/bump_adopters.sh

Step 9 of cutting a release: re-pins every adopter's constitution/ submodule to the release commit, one branch and pull request per repository, idempotently. See RELEASES.md.

scripts/setup-machine.sh

One-time, per-machine installer for Bun, gstack, goose, and goosetown. Deliberately not wired into scripts/bootstrap.sh — provisioning a machine's global AI-agent toolchain and bootstrapping a repository's governance files are different concerns with different blast radii; see INTEGRATION.md "Provisioning a Machine in One Step." Idempotent (skips anything already installed), supports --skip-bun/--skip-gstack/--skip-goose/--skip-goosetown, and automatically detects and works around gstack's Playwright browser-install gap on Linux distros newer than Playwright's support matrix.

Test coverage for governance tooling

The repository tests the bootstrap and checker scripts with shell-based regression suites including negative cases:

  • scripts/test_bootstrap.sh
  • scripts/test_check_traceability.sh
  • scripts/test_check_compliance.sh
  • scripts/test_check_ots_inventory.sh
  • scripts/test_check_secrets.sh
  • scripts/test_setup_machine.sh
  • scripts/test_audit_adopters.sh
  • scripts/test_release_docs.sh
  • scripts/test_checker_contract.sh (the contract every checker must honor)
  • scripts/test_run_all_tests.sh, scripts/test_check_instruction_templates.sh, scripts/test_check_skills.sh, scripts/test_check_demo_page.sh, scripts/test_check_next_steps.sh, scripts/test_check_readme.sh, scripts/test_next_steps_hook.sh, scripts/test_mcp_resources.sh, scripts/test_version_analyzer.sh, scripts/test_bump_adopters.sh, scripts/test_workflow_templates.sh (adopter workflow templates call checkers through constitution/)

The full suite is bash scripts/run_all_tests.sh, declared in docs/TEST_PLAN.md and run in CI by .github/workflows/tests.yml.

Templates and examples

Templates

templates/ is the payload that gets installed into adopting repositories. Notable groups include:

  • Agent bridge files such as .agent-instructions.md, .openhands_instructions, .goosehints, .project-rules.md, and SYSTEM_PROMPT.md
  • Project governance files such as AGENTS.md, CLAUDE.md, CONTRIBUTING.md, HELP.md, README.md, SECURITY.md, TODO.md, CHANGELOG.md, and VERSION
  • Documentation scaffolds under templates/docs/, including SETUP.md, COMMAND_REFERENCE.md, TROUBLESHOOTING.md, ARCHITECTURE.md, OPERATIONS.md, TEST_PLAN.md, PRODUCT_REQUIREMENTS.md, REQUIREMENTS_TRACEABILITY.md, OTS_SOFTWARE.md, and MVP_BACKLOG.md
  • GitHub automation under templates/.github/, including Copilot instructions, Dependabot configuration, and workflow templates

Example project

examples/sample-project/ demonstrates the structure a bootstrapped repository is expected to have: top-level governance docs, a constitution/ submodule, docs/, src/, and editor/assistant-specific configuration directories such as .github/ and .cursor/.

MCP server

The mcp-server/ directory is a minimal Node.js module using @modelcontextprotocol/sdk. It exposes:

  • Resources for every root standards document (constitution, AI workflow, integration, testing, documentation, security, operations, architecture, releases, code style, TODO guidelines, knowledge sources) and the style guide registry, reporting the framework's VERSION as the server version
  • A validate_project_structure tool that checks whether a target project contains AGENTS.md, CHANGELOG.md, TODO.md, and VERSION

Versioning and recent direction

The current framework version in README.md and CONSTITUTION.md is 1.54.0. Recent releases have focused on:

  • The Next Steps procedure enforced where it is skipped (1.54.0): a Claude Code Stop hook (scripts/next_steps_hook.sh, shipped in templates/.claude/settings.json) holds a session that made commits until docs/AGENT_HANDOFF.md is updated, its procedure is well-formed, and the final reply ends with it — once, never in a loop

  • READMEs for every platform, read short by default (1.53.0): setup, run, and test instructions cover Windows, macOS, and Linux at minimum, one block per platform written for that platform's shell, and the long parts sit in collapsible <details> sections while the capabilities list, quick start, hero diagram, and headings stay visible (DOCUMENTATION.md, "Every Platform the Project Supports" and "Progressive Disclosure"; templates/README.md and the framework's own README are the worked examples)

  • The demo page kept current (1.52.0): the Required Workflow, every agent instruction file, the Solon reviewer, and both pull request templates tell agents to update demo.html in the same change whenever user-facing behavior changes

  • A Next Steps procedure at the end of every push (1.51.0, ADR-0005): the closing summary, the pull request description, and docs/AGENT_HANDOFF.md end with the same numbered checklist, each step tagged HUMAN, AGENT, or AUTOMATED, with the human steps named up front and described — verified by scripts/check_next_steps.sh

  • The demo page standard checked mechanically (1.50.0): scripts/check_demo_page.sh verifies that demo.html makes no network requests, keeps scripts and styles inline, references no build output or private-network URL, and is linked from README.md — run --strict against the constitution's own page and in warn mode by the adopter compliance workflow

  • The framework holding itself to its own rules (1.48.0): its suites and checkers run in CI on every pull request; the compliance checker's recommended docs exist for this repository; the MCP server cannot drift; instruction files are kept consistent mechanically; every checker honors one tested contract and annotates pull requests; and changes to the Required Files, Required Workflow, checker contract, or compatibility policy require an ADR

  • New standards (1.48.0): untrusted content reaching AI agents and a shipped deny list, CI/CD supply chain (SHA-pinned actions, Dependabot for actions), data classification and synthetic test data, a proportionate fast path for trivial changes (ADR-0004), Conventional Commit messages, a definition of "product-facing", pull request and CODEOWNERS templates, an incident postmortem template, and a License column in the OTS inventory

  • Framework governance (1.48.0): what "breaking" means for a governance framework and the deprecation window (ADR-0003), and the fleet bump as a release step with scripts/bump_adopters.sh

  • A demo page as a product-facing expectation (DOCUMENTATION.md "Demo Page", templates/demo.html, docs/adr/0002-demo-page-requirement.md): one self-contained demo.html that opens from file:// with no build, no backend, and no network, labels anything simulated in the interface itself, and is checked by check_compliance.sh in the same tier as product requirements and traceability — the framework asking adopters for the artifact it already ships itself

  • OTS software tracking (templates/docs/OTS_SOFTWARE.md, check_ots_inventory.sh, constitution-ots.yml): an FDA OTS / IEC 62304 SOUP-informed third-party dependency inventory, with a checker that cross-references actual dependency manifests against it so documentation stays complete as dependencies evolve

  • A Claude Code SessionStart hook (templates/.claude/settings.json, installed by scripts/bootstrap.sh) that runs check_constitution_freshness.sh the instant a session starts in an adopting repository, so an agent knows immediately — before doing anything else — whether the constitution/ submodule is behind the latest release, instead of relying only on Dependabot, the CI version gate, or a periodic fleet audit

  • CONSTITUTION.md Principle 12 (Industry-Standard Code Conventions): code style, comments, docstrings, and diagrams follow the official, canonical style guide for the language/platform in use, backed by a new CODE_STYLE.md and a tracked sources/STYLE_GUIDES.md registry living alongside the book/paper digestion workflow

  • scripts/setup-machine.sh: a one-time, per-machine installer for gstack/goose/goosetown, deliberately kept separate from scripts/bootstrap.sh so repository bootstrapping never gains a side effect of installing global developer tooling

  • Real, concrete install instructions for gstack and goose/goosetown in templates/CLAUDE.md, templates/.goosehints, and INTEGRATION.md — previously these named the tools and skill lists but never said how to actually get them, so an agent following the docs literally had no path to install anything

  • CI enforcement that runs an adopting repository's own declared test suite and flags documentation drift, not just constitution governance-file presence (run_declared_tests.sh, check_doc_freshness.sh, constitution-tests.yml, constitution-doc-freshness.yml)

  • Placeholder-content detection in check_compliance.sh, so a recommended or product-facing doc still holding copied template text is flagged instead of passing as OK

  • A sources/ drop-in location for book/reference sources with change detection and distilled summaries, surfaced to agents via the MCP server (check_source_summaries.sh, KNOWLEDGE_SOURCES.md, mcp-server/index.js)

  • Requiring agents to evaluate whether accumulated work should trigger a release, not just update CHANGELOG.md's Unreleased section indefinitely (AI_WORKFLOW.md, CONSTITUTION.md Principle 10)

  • Required review of other branches, worktrees, and open pull requests before starting work, and merge-before-delete Git cleanup discipline, in AI_WORKFLOW.md

  • A checker that catches stale adopter-facing version references after a submodule bump (check_version_alignment.sh)

  • A zero-dependency secrets sweep, enforced both locally (pre-push hook) and in CI, so a credential-shaped file or high-confidence secret pattern never reaches a remote (check_secrets.sh, constitution-secrets.yml)

  • Compliance checking and CI gates

  • Requirements traceability enforcement

  • Automated constitution version drift detection for adopters

  • Worked operations documentation examples

  • Editor/tooling bootstrap support for Continue.dev, Aider, pre-commit, and devcontainers

  • A per-IDE guide for applying the constitution in Visual Studio, VS Code, and JetBrains, mirrored into every adopting repo's docs/HELP.md (INTEGRATION.md "Using the Constitution in Your IDE")

See also

Eric's Engineering Constitution

Overview

Adoption

Engineering Workflow

Integrations

Clone this wiki locally