← Writing
AI Agent

Agent Foundry: A Repository Contract for Agentic Development

Publication Date: 30 September 2026
Author: Ailven LIU 刘翔
All Rights Reserved

An agent can follow a detailed instruction in one conversation and lose it in the next. It can also describe a quality gate accurately while never running it. The useful unit of agentic development is therefore the repository: a place where the procedure is discoverable, the project state is explicit and the checks still work after the conversation has ended. I built Agent Foundry around that boundary and have kept using it as my own skill hub for agentic development.

I keep procedures in .agents/skills/ and obligations in .agents/constraints/. The project profile selects the relevant rules; wrappers and hooks check conditions an agent might otherwise skip. When a build goes wrong, I can trace the failure to a procedure, a policy decision or an executable check instead of trying to reconstruct what the agent was told.

A procedure needs a durable home

A recurring task gets a canonical procedure at .agents/skills/<name>/SKILL.md. The collection covers session initialisation, dependency changes, builds, pre-commit validation and code navigation, alongside longer workflows such as roadmaps and deployment. The pre-commit skill, for example, directs the agent to agent-precommit. That command selects tools for the project profile and explicitly collects tests from both the application and the agent infrastructure. Its exit status carries more weight than the agent’s account of what it intended to check.

Policy sits beside the procedures in .agents/constraints/. Common files govern the session and Git workflow; language files cover matters such as Python dependencies and C++ memory safety. The hybrid profile assigns native build ownership to CMake. That rule applies whether the agent arrived through build, dependency or a request to add a binding. Keeping it outside any one procedure lets the same constraint govern all three.

A policy change should have one source edit. Codex reads the skill body under .agents/skills/; Claude Code discovers a short delegate under .claude/skills/ that points back to it. The two agents enter through AGENTS.md and CLAUDE.md respectively, then reach the same .agents/bin/agent-* commands. Tests verify the delegate links and reject skills placed in the obsolete .codex/skills/ location. Without those checks, two apparently equivalent platform copies could diverge quietly as the foundry evolves.

The adapters cannot erase platform differences. Hooks are registered separately, and repository instructions remain subject to each platform’s tool and permission requirements. An earlier version of Agent Foundry made this boundary painfully clear: its instruction wording interfered with normal Claude Code sessions. The fix scoped precedence to repository-controlled guidance and made initialisation print a bounded list of constraint paths. The rules remained enforceable without asking the agent to treat a local file as higher authority than its platform.

Session state is a checkable precondition

The init procedure resolves a project profile, audits declared capabilities and prints a manifest of relevant constraint paths. It records the result in .agents/session_state.json, with a compatibility copy for Claude Code. The manifest is deliberately bounded. It selects common constraints and the language rules needed for the current profile and files, leaving the agent to read the listed bodies before the relevant work. Filling the context window with every policy file would make initialisation expensive while giving little evidence that the right rule was applied.

The capability list lives in .agents/capabilities.yml. It declares shared skills and repository commands, then adds platform requirements where they differ. A Python project requires the Python environment procedure; a CUDA-targeted project needs the GPU CI surface. The audit turns a missing wrapper or skill into a reported failure. The session hook then uses the recorded result as a gate for mutation. In the Claude path, the pre-tool hook blocks writes before initialisation and blocks mutation after a failed capability audit. The Codex adapter is registered separately, with shared policy logic underneath. This does not prove that an agent understood every instruction; it makes an important prerequisite observable.

In a hybrid repository, an agent editing packaging configuration can accidentally move compiler policy out of CMake. The project profile identifies both languages, so initialisation selects the C++ and hybrid constraints before the edit. The pre-tool hook can stop work that begins without initialisation. The native targets, tests, benchmarks, compile options and ABI-sensitive settings remain CMake’s responsibility; scikit-build-core only bridges them into a wheel. A later constraint check can catch some forbidden patterns. None of these checks establishes that the agent read every selected file or understood the build graph, so the changed targets still need review.

For longer work, agent-roadmap records phase and task dependencies under agent_roadmaps/. The active phase and current task are explicit, and the workflow can create a handoff for another session. These files are temporary execution state, not permanent product documentation. Once the roadmap is complete, the workspace is cleared back to its placeholder. This avoids treating a stale session note as if it were a durable rule. It also gives an agent resuming work a narrower question than ‘What were we doing?’: which dependency-ready task is active, and which invariants govern it?

The project profile travels with the code

Agent Foundry also generates repositories. Its create-project script copies the shared .agents/, .claude/, .codex/, .github/ and roadmap structure, then overlays one of three profiles: Python, C++/CUDA or hybrid. The overlay provides that project’s AGENTS.md, CLAUDE.md, CONTRIBUTING.md and .agents/project.yml. The generated profile is an input to later constraint selection and validation, not merely a label attached to the template.

The distinction is clearest in the hybrid profile. CMake is responsible for the native build graph and CPM for lightweight C++ dependency acquisition. Poetry manages the Python environment; scikit-build-core is a packaging bridge. Those choices appear in the generated layout and rules, so an agent has an answer when it encounters a Python package with CUDA code. The Python profile, by contrast, does not inherit C++-specific build obligations. Capability audits filter their requirements by profile as well. A copied template that demanded every possible skill in every project would soon teach agents to ignore failed audits.

The generator intentionally omits template-only material and historical roadmap state, then creates an initial Git commit. That gives a new project the current operating contract without inheriting the foundry’s own temporary work. It also sets a maintenance cost: generated repositories are copies, and later foundry changes do not propagate automatically. The compatibility guide describes a migration process that preserves project-specific customisations, updates the copied instruction surfaces and checks a freshly generated project. Cross-project reuse here works by deliberate distribution; the copied rules have to be maintained.

Two scales of engineering work

An empty repository offers little context for the first build decision. Agent Foundry supplies the project profile, initial directory layout and entrypoints, then routes Python dependencies through Poetry and native ones through pinned CPM declarations. In a hybrid project, the build wrapper runs direct CMake configuration, compilation and CTest before the Python packaging step. A roadmap records dependencies and current focus when the work spans sessions. Those files give the next agent a branch, a task and a build command to inspect; the application’s domain architecture still has to be designed for the system at hand.

Adding a small feature to an established codebase poses a different problem. The requested change may be ten lines, while its effect crosses a public interface, a build target and several call sites. The navigate skill offers definition, reference, dependency and call-graph searches for Python and C++, with rg as the fallback when an agent lacks the native skill. Python analysis uses the AST; C++ lookup combines regex and clang-based tools and is more reliable when compile_commands.json is present. Dynamic imports and metaprogramming can escape that analysis. The output is a map for review, with completeness still requiring an engineer’s judgement.

The next step is to establish the existing repository’s authority before changing a module. An agent reads its entrypoint, resolves its project profile and checks the active roadmap, if there is one. It can then identify the smallest edit surface and the governing build and dependency rules. A new C++ component in a hybrid repository belongs in the CMake target graph; a Python binding may expose it, but must not silently replace the native test or installation path. After the change, the build and pre-commit procedures exercise the affected languages, while constraint checks inspect prohibited patterns. A small module can be treated as a local edit without pretending the surrounding engineering system is small.

Agent Foundry does not automatically retrofit every existing repository. Its generator was built for new projects, and its compatibility guide treats downstream migration as a review of local customisations and copied files. In an established codebase, adopting the hub means reconciling its contract with the repository’s current build graph and policies. That friction is useful information. If a skill’s preferred command cannot be run without overriding the host project’s design, the mismatch should be resolved explicitly before the feature is merged into it.

Validation must reach the workflow, not just the prose

agent-check-constraints runs structural, instruction-safety and forbidden-pattern checks. The agent-commit wrapper takes explicit file paths, rejects some sensitive path shapes and calls the pre-commit and branch-policy gates before staging. For Python, pre-commit selects Ruff, mypy and pytest; C++ projects use the native toolchain. A failed command leaves an exit code and a finding for the next session to inspect.

The tests create projects with the actual template function, add source files and invoke the wrappers copied into those projects. They inspect exit codes and findings after seeding known violations. A scanner unit test alone would not catch a broken wrapper path or a skill missing from the generated tree.

For example, a generated Python fixture contains a hard-coded secret, a mutable default argument, a bare except, an eval call and a shell-based pip install. The scenario suite checks which of those violations the distributed tooling reports. Its results describe detection of those fixtures, not the frequency of mistakes in ordinary agent work. I still read the resulting diff and run validation for the code that actually changed.

The Git history starts in January 2026. Later changes addressed release promotion, instruction compatibility and downstream hardening; the Claude Code failure, in particular, changed both the authority wording and the output of init. Those revisions came from using the hub and finding where its contract broke. A skill count would not show them.

Deployment choices and code review still demand judgement. After a session change, though, I can inspect .agents/project.yml, run agent-init, read the selected constraints and see which gate passed or failed. The next edit begins from those records and the code itself.