Repository navigation
v1.4.0 - Elephant-Goldfish context contracts, drift auditing, and Paraphrase-First review gates
Latestv1.4.0 - Elephant-Goldfish context contracts, drift auditing, and Paraphrase-First review gates
This release integrates core mechanisms from Google's Elephant-Goldfish Model (EGM) natively into the template across Claude Code, OpenAI Codex, Google Gemini / Antigravity, and Cline, while keeping zero external plugin dependencies and preserving the sub-9,500-character FAST_INIT startup ceiling.
Highlights
- Bottom-up module context contracts (
docs/peanuts-and-hay.md,workflows/bootstrap-context.md):- Generate leaf component contracts (Peanuts:
Overview,Interface,Invariants,Side Effects,Verification) and subsystem blueprints (Hay) under the Re-Implementation Standard so fresh sessions can navigate module boundaries in 1-2 file reads without loading raw source code into startup context. - Supports both
README.md(default) andCONTEXT.mdmode (when existing human-facingREADME.mdfiles must remain untouched), with incremental BFS discovery and a mandatory> 15directory confirmation gate.
- Generate leaf component contracts (Peanuts:
- Spec & contract drift auditing (
workflows/drift-report.md):- Read-only, sequential document-to-code audit that compares specs,
Peanuts & Haycontracts, and Memory Bank architecture docs against the working tree across four categories: Missing Features, Incomplete Models, Logic Shortcuts, and Architectural Divergence. - Verified in a two-model blind simulation (Claude Stage 1 + Codex Stage 2) that caught 100% of seeded discrepancies across all four categories with zero false positives.
- Read-only, sequential document-to-code audit that compares specs,
- Paraphrase-First, Zoom-Out, Zero-Decision, and Contradiction gates:
docs/reviewer-role.mdandworkflows/critic-review.mdrequire aparaphrase:comprehension summary before emitting findings and enforce aZoom-Outcodebase reuse check.workflows/spec-driven-development.mdandworkflows/plan-task.mdenforce the Zero-Decision Rule so specifications and plans resolve file paths, interfaces, defaults, and failure behavior up front..agents/rules/30-cognitive-harness.mdadds a Contradiction Gate that halts before file edits when user instructions conflict with checked-in specs or module contracts.
- 24,000-byte skill load ceiling & full
scripts/README.mdPeanuts contract:scripts/check-template.pyenforcesSKILL_MAX_BYTES = 24_000across all 24 canonical and mirrored skills and validates theparaphrase:reviewer contract marker.scripts/README.mdis now a verifiedPeanutsmodule contract covering every script'sargparseinterface, exit codes, hook denial payloads, state paths, invariants, and side effects.
How to start a new project
python scripts/new-project.py ../my-project --name "My Project"
cd ../my-project
python scripts/init-fast.pyOpen ../my-project in your coding agent and start with:
FAST_INIT (default mode per AGENTS.md).
How to quickly upgrade an existing project from GitHub
1. First-time upgrade (or installing into an existing repo)
Open your existing project in Claude Code, Codex, or Antigravity and paste:
Upgrade this project's AI framework from
https://github.com/rumotion/ai-agent-project-template using its latest upgrade
workflow. Preserve application code, tests, settings, custom rules, skills and
project memory. Preview changes, resolve conflicts and run the project's checks.
Do not push or deploy.
2. Subsequent upgrades (one sentence)
After the first remote upgrade, the project remembers the template source and
file hashes in .template-upstream.json. Next time, simply ask your agent:
Update this project from its saved AI template source and verify the result locally.
3. Direct CLI preview and apply (local or directly from GitHub)
# From a local checkout of this template:
python scripts/upgrade-target.py --target ../existing-project --dry-run
python scripts/upgrade-target.py --target ../existing-project --apply-safe
# Or directly from GitHub pinned to v1.4.0:
python scripts/upgrade-target.py --target ../existing-project \
--source https://github.com/rumotion/ai-agent-project-template \
--ref v1.4.0 --dry-runVerification and limits
Full validation (python scripts/check-template.py) covers 206 required files,
10 instruction adapters, 17 context budgets, 24 skills across 3 discovery trees,
and 15 hardening/recovery suites (23 upgrade preservation tests in scripts/verify-upgrade.py).