claudiomaradonna/agent-foundry
claudiomaradonna/agent-foundry
Template
1
0
Fork 0
Code Issues Pull requests Activity
A lean Git repository template for disciplined AI-agent development with Claude Code, Codex, Superpowers workflows, and optional LocalRecall memory.
123 commits 1 branch 0 tags 986 KiB
  • Shell 100%
Find a file Use this template
Exact
Claudio Maradonna 71a80ade3c
 docs(git): create worktrees with relative paths 
Worktree links held absolute paths, so a checkout shared between a
container and its host broke on whichever side mounts it elsewhere.
Require git worktree add --relative-paths (Git 2.48+) and name the
repair command that converts existing worktrees.
2026-09-30 19:35:03 +02:00
.agents/skills docs: name new validator checks and preflight migration 2026-09-30 19:17:49 +02:00
.claude chore(claude): disable unused plugins and skills 2026-09-30 10:40:16 +02:00
.codex/agents
docs docs(memory): stale by content, add superseded 2026-09-30 19:16:18 +02:00
scripts feat(validator): check memory adapters and preflight 2026-09-30 19:17:35 +02:00
tests feat(validator): check memory adapters and preflight 2026-09-30 19:17:35 +02:00
.gitignore
AGENTS.md docs(git): create worktrees with relative paths 2026-09-30 19:35:03 +02:00
LICENSE
README.md docs: name new validator checks and preflight migration 2026-09-30 19:17:49 +02:00

README.md

Agent Foundry

Agent Foundry seeds a repository with the policy that coding agents such as Claude Code and Codex follow: how to scale process to a task, verify work, deliver it, and, when a team wants it, keep verified project memory in LocalRecall. You copy it once and initialize or adopt it deliberately; from then on the repository owns that policy and evolves it like any other part of the project. Product, stack, hosting, and memory deployment stay the project's own choices.

How it works

AGENTS.md holds the shared, tracked policy together with the project's identity: its name, purpose, architecture, commands, and whether the repository supports memory. Each contributor extends it with a git-ignored AGENTS.local.md for personal preferences and for the memory profile of their workstation, so one project can run different memory setups on different machines while sharing the same rules. Codex and Claude Code read AGENTS.md natively and follow it to the local file; the instruction-files section of AGENTS.md describes the CLAUDE files that would hide it from Claude Code.

Four skills in .agents/skills/ carry the working process: brainstorm for shaping an idea into an approved design, write-plan for a resumable plan, diagnose for finding a root cause before fixing, and foundry-upgrade for bringing in a newer Agent Foundry source. Codex reads them there, and Claude Code through the links in .claude/skills/. Designs and plans stay local in .plans/. A project adds its own skills the same way, as a directory with a SKILL.md and a matching link.

A validator in this repository checks a target statically: placeholder tokens, field formats, the local memory selection and preflight date, the files that memory support brings, CLAUDE files that would hide AGENTS.md, skills and their links, and the curator adapters' tools and servers.

Initialize a new repository

  1. Copy the tracked files, leaving out scripts/ and tests/ (delete them after a forge's template copy), and start a fresh agent session.
  2. Read AGENTS.md, the existing code, and any project or CI evidence.
  3. Resolve the name, purpose, architecture, and the Setup, Test, and Verify commands from evidence or explicit user decisions, in the forms AGENTS.md states.
  4. Choose memory support with the user: localrecall, or none, which is the choice whenever the user has made no explicit decision. With localrecall the repository keeps docs/LOCALRECALL.md and both curator adapters; with none it drops them along with the Project memory section of AGENTS.md. A user who enables memory on their workstation writes the profile, collection, and operator to their own AGENTS.local.md, as AGENTS.md describes.
  5. Keep the skills and their links and .claude/settings.json, which leaves commits and pull requests free of tool attribution and turns off the built-in telemetry plugin and the claude.ai skills that development repositories don't use; extend .gitignore for the stack, and keep LICENSE.
  6. Remove the Template state field and the Template lifecycle section from AGENTS.md, which apply to the source only, fill the Record of the foundry-upgrade skill with this source's location and the copied commit, and replace this README with the project's own.
  7. Run the source validator against the repository, then the configured commands (see Verify).

A blank repository may gain a minimal skeleton the user approves, and feature work starts once initialization validates.

Adopt into an existing repository

Adoption follows the same steps while preserving what the repository already has. Inspect the source read-only, and read the target's instructions (root and nested), README, ignore rules, build files, and CI first. Merge AGENTS.md so project-specific and nested rules carry over, and move any CLAUDE.md or .claude/CLAUDE.md instructions into it, then remove those files. Merge .gitignore entries, including AGENTS.local.md, keep the repository's own README, and keep the MIT notice with any substantial copy. Endpoints, credentials, and deployment configuration live in the operator's systems. Report any conflict you cannot reconcile.

Memory

External memory is optional. A repository opts in with Memory support: localrecall, and each workstation then works with none, localrecall-read-only, or localrecall-automatic, as its own AGENTS.local.md selects. The Project memory section of AGENTS.md holds the selection and the rules every agent follows under every profile, and docs/LOCALRECALL.md holds the contract for agents with memory enabled, the curator, and the operator.

Re-adopt a newer source

An initialized repository upgrades with its foundry-upgrade skill, which merges the source's changes since the commit its Record names and carries the migrations for older layouts. A repository adopted before the skill existed copies it and its .claude/skills/ link from the source first, fills the Record with the commit its README credits or its history shows, and then runs it.

Verify

The validator stays in this repository and checks the target given as its argument, or the current directory. It needs Git, Bash, and POSIX text utilities. It covers static consistency; the operator preflight in docs/LOCALRECALL.md establishes runtime memory readiness.

bash tests/verify-agent-config.sh              # source maintenance
<agent-foundry>/scripts/verify-agent-config.sh [<target>]
git diff --check

An initialized repository then runs its Setup, Test, and Verify commands, skipping not-applicable fields, and reviews the complete diff.

References