Skip to content

About

Foundation for building deterministic architecture and code for AI agents

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

1 watching

Forks

Latest commit

 

History

481 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Engineering Foundation

Versioned engineering policy, tooling, and conformance for multi-repository projects.

The Foundation glossary defines the core language used by this repository. In particular, authority is claim-specific, evidence is bounded to an observation, and qualification must name its subject.

This repository contains reusable development tooling only. Product runtime code must not import it. Its core capabilities are meant to be architecture-neutral, and checks for an architecture-specific standard ship only as opt-in packages (see Architecture neutrality, which also records the remaining exception). Each consumer remains authoritative for its own domain model, package catalog, dependency permissions, security classifications, and ADRs.

The current integration implements the accepted new-only, independently versioned portable package boundary. Exact-head artifact qualification, protected publication, and consumer rollout remain separate gates. ADR-0043 is the single authority for the dependency DAG, and the delivery contract records the evidence still required before release. No compatibility facade or legacy alias is part of that target.

Consumer-specific document types, schemas, owners, templates, reachability, and semantic validators remain strict data-only authority in each repository. Exact public installation and optional MCP pairing have one canonical authority: the open-source Docs Protocol workflow.

Scope

  • strict data-only consumer configuration and versioned schemas;
  • executable workspace declaration and source dependency policies;
  • governed inline suppressions and released public API compatibility;
  • static executable-specification and consumer-gate connectivity;
  • repository workflow, SBOM, provenance, and package-content security policy;
  • portable agent instructions and changed-file preflight routing;
  • opt-in deterministic composition of existing package-script quality gates;
  • shared Oxlint and TypeScript 7 baseline presets;
  • explicit registry and local-link modes;
  • deterministic attach, status, detach, and registry assertions;
  • closed deterministic Intent -> Plan -> Apply -> Receipt scaffolding;
  • governed document catalog, deterministic non-reserving planning, create-only publication, and exact-version recovery commands;
  • isolated package-content and consumer verification;
  • release automation for immutable public npm versions.

Shared concerns are built here library-first, for many consumers; each new capability ships with parity fixtures and a conformance test in each adopting consumer (see the extraction admission invariant). workspace.dependency-declarations is active. architecture.source-dependencies is active and dogfooded with its accepted Oxc adapter. This monorepo uses schema v2 with the explicit packages package root, while the published v1 contract remains loadable for existing consumers. See Executable capabilities and the parser spike. The additive v3 root-package and overlapping-selection contract is pending combined validation and package qualification; consumer activation remains an explicit, separately qualified policy change. Suppression governance, released public API compatibility, and the publishing- repository security baseline are accepted, implemented, released, and dogfooded. Consumers still enable each capability explicitly and must satisfy their consumer-owned adoption gates; installing a package version does not activate policy.

The repository explicitly adopts the Feature Module Standard. Its fail-closed guard exposes remaining ownership migrations.

Commands

bun tools/dev.mts install
bun tools/dev.mts check:changed
bun tools/dev.mts check:fast
bun tools/dev.mts security:workflows
node tools/dev.mts --profile node install
node tools/dev.mts --profile node verify

Bun 1.4.3 is the default repository manager and ordinary tool runtime. The explicit rollback profile uses a clean, separate pnpm installation with its recorded workflow policy projected to pnpm:

node tools/dev.mts --profile node install
node tools/dev.mts --profile node check:changed
node tools/dev.mts --profile node check:fast

Node remains explicit for mandatory Node tests, raw V8 coverage, c8, npm/pnpm qualification, signing and release operations. Published Node 24/26 support is unchanged.

Consumers use:

pnpm foundation:check
pnpm foundation:attach -- /absolute/path/to/engineering-foundation
pnpm foundation:status
pnpm foundation:detach
pnpm foundation:assert-dev-only
pnpm foundation:assert-registry

Foundation CLI options end at --; later values are positional arguments even when spelled --json or --format. Failure output follows the options admitted before that separator. Invalid arguments preserve the first parse error and produce one JSON error only when a real JSON output option was requested.

Any repository can preview a portable documentation setup without mutation:

docs-protocol init --project-id example/widgets \
  --owner documentation/team --dry-run --json

After applying the reviewed digest, docs.config.yaml is discovered automatically. Search and bounded context remain disposable projections:

docs-protocol find "tenant isolation" --fuzzy
docs-protocol context "tenant isolation" --fuzzy --max-documents 12
docs-protocol check

Governed document authoring uses the installed Docs Protocol CLI. owner and summary are explicit Intent authority and never receive Foundation defaults:

agent-teams-docs find "tenant isolation"
agent-teams-docs new --type adr --id ADR-0083 \
  --title "Tenant isolation" --owner architecture/tooling \
  --summary "Defines the tenant-isolation boundary and its verification evidence." \
  --dry-run
agent-teams-docs doctor
agent-teams-docs recover
agent-teams-docs-managed upgrade --to docs-YYYY-MM-DD-N --target-generation 2 --json

After reviewing a dry run, repeat agent-teams-docs new with --apply, follow its exact reachability instruction, and run the consumer's standard repository check. See the document authoring protocol for the complete CLI and JSON contract.

foundation:check emits one deterministic aggregate report and enforces every declared capability. See consumer adoption. This repository makes its source lifecycle explicit as foundation:bootstrap, foundation:dogfood, and foundation:qualification; see quality gates. The optional repository.agent-workflow capability keeps AGENTS.md canonical across coding agents and routes check:changed through the shared Foundation implementation; required CI still runs the complete verify evidence as independent fail-closed lanes. Its read-only agent-workflow instructions command explains the effective AGENTS.md chain for a selected repository file.

foundation:assert-dev-only rejects runtime dependency placement. foundation:assert-registry inspects the exact declared registry selection. For pnpm 11, root and installed virtual-store lockfile provenance must match. For stable Bun 1, the active text lock must match a contained isolated store coordinate and installed manifest identity. Bun has no installed lock mirror; this cooperative selection check does not authenticate expanded archive bytes or detect every stale in-place package. Local attach and detach remain pnpm-only; see the manager-specific evidence and limits.

The scaffolding kernel exposes strict schemas and a journaled filesystem adapter. It includes a testing-only conformance fixture and one generic private Node TypeScript library-boundary recipe. The latter creates only the package envelope; consumer business packages, roles, owner documents, and feature slices remain consumer-owned. See the recipe reference and scaffolding protocol.

See ownership, consistency evidence gate, governance capability acceptance review, local development, and release procedure. The complete documentation index is docs/README.md.

About

Foundation for building deterministic architecture and code for AI agents

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages