Adamant Agent Skills

Skills for AI-assisted development with the Adamant embedded software framework. Every pattern validated by compilation against a real GNAT/GNATprove toolchain.

This is the vendor-neutral agent instructions file (agents.md convention): the working instructions for any coding agent or tool operating in this repo. It is functionally equivalent to CLAUDE.md (the Claude Code entry point) -- read either; they carry the same build rules and skill inventory.

Project Precedence

These skills describe the Adamant framework generically. When you are working in a project that provides its own instructions or skills — a project CLAUDE.md/AGENTS.md, an agents/ skill directory, or any project-local guidance — those take precedence over anything here. Use the project's guidance for every task it covers, and do not fall back to a generic skill the project has superseded. These generic skills remain the authority only for framework tasks the project does not cover.

Agent Configuration Files

This repo contains three agent instruction files; copy the ones your tooling uses to your project root:

• AGENTS.md (this file) -- vendor-neutral agent instructions: build rules, skill inventory, critical patterns. Read by any agents.md-aware tool.
• CLAUDE.md -- the Claude Code entry point: the same instructions plus Claude-specific load-order notes. Functionally the Claude Code counterpart to this file.
• SUBAGENT_CONTRACT.md -- handoff contract for an orchestrated/headless build subagent: a scoped posture (no questions, no git, output filtering, quality gates) layered on top of these shared instructions. Read it only when you are a spawned build subagent, not the primary agent.

Running Commands in the Adamant Environment

Use admt (The Adamant Multitool) as the primary entry point for all Adamant work. admt wraps redo, docker compose, and env activation behind one CLI. Run it from the host, on or below a registered project root; it forwards into the container automatically.

Your first admt action is selecting a project. Before any build/test/env command, pin your session -- admt env use <project> (admt env list shows the registered names); see Selecting your project. A tty-less session that has never selected a project has nothing to resolve: commands are refused (or, if a global default exists elsewhere, may target the wrong container's mounts), so select first, then build.

admt what               # List buildable targets in the current dir
admt build              # redo all
admt test               # redo test (add --all for test_all)
admt style              # redo style
admt templates          # redo templates + optional stub copy
admt env start          # Start the container
admt env exec "<cmd>"   # Arbitrary command inside the container

Prefer admt everywhere. The adamant_env.sh exec form remains as a fallback for operations admt has not yet absorbed (MVP is complete; post-MVP will keep closing the gap):

# Fallback only -- when admt does not cover the case.
bash docker/adamant_env.sh exec "cd /home/user/<project>/path/to/dir && <command>"

admt what is what you run first in any directory -- once your project is selected -- to discover what can be built. It replaces redo what.

admt is self-describing. admt --help lists every command and global flag; admt <command> --help shows command-specific options (e.g. admt env --help, or admt templates --help, which reveals --undo). The tables below are a quick reference, not exhaustive -- when you need an advanced or unlisted subcommand or flag, run --help rather than guessing or defaulting to the fallback.

admt is new -- report gaps, don't silently work around them

admt's MVP just landed; post-MVP work is ongoing. Gaps and bugs exist. If admt errors on a case you expected it to handle, or its output is visibly wrong:

1. Fall back to adamant_env.sh exec (or the equivalent inside admt env exec) to unblock the task. Don't get stuck.

2. Surface the gap in your final report. Include:

   • The admt command you tried
   • The error or observed deviation (copy the exact message when possible)
   • The fallback form that worked
   • admt version from admt --version

   The user can then file an issue at https://github.com/Jbsco/admt/issues.

Silent fallback is worse than no fallback -- it hides the signal that admt needs fixing. Verbose fallback keeps admt improving.

redo target -> admt command

Every passthrough command also accepts an optional path argument -- admt build src/components/foo is equivalent to cd src/components/foo && admt build. Resolved against cwd, symlinks canonicalized, must fall under a registered volume mount.

admt env subcommands

NEVER source env/activate or source project/env/activate directly. admt (and the adamant_env.sh exec fallback) handles activation automatically via a cached snapshot.

Selecting your project

Every admt command targets one active project -- the container it forwards into. As an agent, prefer these in order:

1. Pin your session (preferred -- zero configuration): as your first admt action, run admt env use <project> once. Your harness's session id (Claude Code's CLAUDE_CODE_SESSION_ID, Codex's CODEX_THREAD_ID -- injected into every shell) keys the pin, so it holds for every later command even though each runs in a fresh shell that would drop an export. Do not re-export ADMT_ENV per command -- that is the trap the pin exists to fix. On an unrecognized harness, export a stable ADMT_SESSION_KEY once, then env use the same way.
2. Override per command only when needed: ADMT_ENV=<project> admt <cmd> outranks the pin for that one call and persists nothing -- for a one-off command against another project, or orchestrated/hermetic runs where the orchestrator names the project explicitly.

A tty is not usually available inside an agent session, so the terminal path is not yours; for completeness: in an interactive terminal the same admt env use pins that terminal, keyed on its tty.

Behind this: a headless env use pins only your session and never moves the global default, so concurrent agents (one per worktree) don't collide -- and with no tty and no session key, admt refuses with an error naming the fix rather than silently building against the shared global.

Quick Start

Read adamant-skill-selector/SKILL.md first. It routes your task to the right 1-2 skills.

Skill Inventory (22 skills + 4 meta-skills = 26 total, ~26200 lines with refs)

Total: ~26200 lines across all 26 skills (SKILL.md, references, and scripts)

Meta-Skills

Skills about the skill system and about running large tasks, rather than about the Adamant framework itself:

Read task-planning/SKILL.md FIRST for any task with 5+ deliverables or 10+ components. It teaches how to manage time, track progress, and avoid rabbit holes.

Key Principles

• Framework-specific only. Generic Ada/SPARK knowledge excluded.
• Compiler-validated. 30+ rounds of build-test-fix cycles across 100+ components + unit tests. Components compile clean on first try when skills are followed.
• Capability-calibrated. Skills state domain invariants absolutely (build-state corruption, generated-code contracts, buffer limits) and conventions with their rationale. The most capable current models (across providers) should exercise judgment over execution order and verification cadence within those invariants; the explicit statements are what keep mid-tier and non-Anthropic models convergent. Treat degraded output from over-prescription as a skill defect and report it (see adamant-skill-creation Writing Rule 10).
• Selector-driven. Load 1-2 skills per task, not all 26.
• Three-tier prompt strategy: this file -> skill-selector -> deep skills. Load order matters for cache efficiency:
  1. This file -- your working instructions (load it first if your tooling supports a persistent instructions/context file)
  2. adamant-skill-selector/SKILL.md -- always the first skill read
  3. Task-specific skills -- in the order the selector specifies
  4. Task request / user content -- always last
• ~300-500 line SKILL.md target. Dense patterns in SKILL.md, detailed examples in references/.
• Cache-optimized structure. Stable content (skills) forms a cacheable prefix; variant content (task requests) goes last. Under tooling that prompt-caches, a deterministic read order in the skill selector enables cross-call cache hits. See README.md for full analysis.
• No project-specific content. Generic skills contain zero project names or paths. Project-specific guidance lives in the project repo.
• No commits/push instructions. Skills are agent-level -- orchestrators handle git.
• No structural coverage ceiling. All paths are coverable with proper testing techniques.
• All style warnings are fixable. No "template artifacts" -- every warning has a solution.

Validation Results

All results below predate the Claude 5 generation. Earlier campaigns ran Opus-tier orchestrators driving Sonnet-tier cold-start subagents; more recent ones ran Opus- or Fable-tier orchestrators driving Opus-tier subagents. Validation is generation-scoped -- see adamant-skill-campaign -- and a systematic re-validation of the full skill set on 5-generation subagents is pending.

• Style: 221/221 directories, 0 failures
• Coverage: 89%+ aggregate across 100+ components
• Invalid_Command tests: 63/63 components passing
• Cold-start: Fresh agents produce compiling components with 0 errors (stress-tested 2026-02-20)
• Formal verification: SPARK proof chain pattern, ghost lemma discipline, GNATprove integration
• Component lifecycle: New component from YAML to passing tests validated 19+ times
• Convergence: Systematic stress testing across all generative skills -- 0 cold-start errors
• Subassemblies: 10-round iteration, R10 achieved zero errors from cold-start agent

Multi-Phase Workflow Rules

When building as part of a phased pipeline (types -> components -> assembly):

• Read prior-phase artifacts, don't rewrite them. If types and components already exist, use them as-is. Your job is to wire them, not redesign them.
• Respect read-only boundaries. If the task lists directories as read-only, do not modify, rename, or delete files in those directories.
• Delete before creating from scratch. If the task says "create from scratch" but files already exist from a prior iteration, delete them first (only in YOUR phase's directory, never prior phases).
• Don't delete unrelated files. Other scenarios' components in the same repo are not yours to touch.

Critical Build Rules

• admt clean is always safe on any directory (framework or project). If redo state corrupts (STORAGE_ERROR), run admt clean --all on BOTH the project root AND the framework root (see scope note below).
• admt clean --all is per-directory, not workspace-wide. It runs redo clean_all recursively under the cwd's container path only. Other volume mounts in the active project's compose -- the framework at /home/user/adamant, sibling component repos -- are NOT cleaned by the same invocation. To clean another mount, cd into it on the host first; admt's path mapper accepts any host path under the active project's volume mounts. Example: cd ~/cs/adamant && admt clean --all cleans the framework tree when the active project mounts it.
• NEVER manually delete build directories (rm -rf build, rm -rf */build, etc.). Use admt clean or admt clean --all. Bulk-deleting build dirs corrupts redo state and may require container recreation (admt env rm --volumes && admt env start) to recover.
• admt coverage runs from the component's test/ directory. No admt clean needed.
• Do not source env/activate directly. admt handles environment activation via a cached snapshot; adamant_env.sh exec does too for the fallback case.
• Never run concurrent builds in the same container -- corrupts redo state. admt serializes per-invocation; do not spawn multiple admt build / admt test runs at once.