Amphimixis-AI harness¶

Amphimixis-AI is an LLM-powered assistant that automates the migration-readiness analysis pipeline. This document describes the agent system in general, independently of the concrete LLM-agent implementation. The Opencode implementation of this system — the file layout, tools, plugins, and the inspecting method — is described in opencode/opencode-implementation.md.

Concept¶

A system of agents and tools implements this methodology. These agents must be regenerated by AI after a methodology update to stay in sync. They are generated artifacts; service agents exist for this purpose. The tools must be written by a human, AI can only suggest changes to the toolset.

Agents reference¶

Agent	File	Role	Delegates to / Uses
`amphimixis` (orchestrator)	`agents/amphimixis.md`	Coordinates the full pipeline; compiles final report	All subagents
`amphimixis-analyzer`	`agents/amphimixis-analyzer.md`	Clone repo, scan macros/intrinsics, assess deps	`amphimixis-analyze` tool
`amphimixis-configurator`	`agents/amphimixis-configurator.md`	Create `input.yml` (platforms → recipes → builds)	configure-* tools, validate tool
`amphimixis-builder`	`agents/amphimixis-builder.md`	Build on reference + target, run tests	`amphimixis-build` tool
`amphimixis-profiler`	`agents/amphimixis-profiler.md`	Profile executables, cross-table comparison	`amphimixis-profile`, `amphimixis-analyze-vectorization`
`amphimixis-optimizer`	`agents/amphimixis-optimizer.md`	Analyse bottlenecks, suggest optimisations	`amphimixis-analyze-vectorization`

Regeneration pipeline¶

Service agents¶

agents-regenerator — knows how to regenerate agents
migration-expert — assesses the agent session and report from the generated agent (to improve generated agents)

Pipeline¶

Regeneration is triggered manually by calling the agents-regenerator agent:

Step 1: Detect the methodology update¶

Methodology has been updated (e.g. a new step added, an existing procedure changed, the report template modified).

Step 2: Decide the regeneration scope¶

agents-regenerator is called with prompt “Methodology has been updated — regenerate agents?”. It reads methodology + current agents, compares, decides scope of regeneration and answers:

Question	How to answer
Did a NEW step get added?	Compare step count in methodology vs agent structure
Did an EXISTING step change?	Check if tool calls, flags, or order changed
Did the report format change?	Compare `docs/methodologies/report-template.md` against each agent’s reporting section
Did the frontmatter requirements change?	Check if the LLM-agent implementation updated its agent schema

Output is one of:

DECISION: Full — regenerate all agents
DECISION: Partial: <agent list> — regenerate specific agents only
DECISION: None — no changes needed

After that it regenerates selected agents.

Step 3: Run the new agents on a project¶

amphimixis (new orchestrator with new subagents) is called with prompt “Analyze TinyXML2 project for migration to RISC-V readiness”. It produces a migration-readiness report on a concrete project.

Step 4: Expert assessment¶

migration-expert is called with prompt “Assess these session and report: read <path to session> and <path to report>”. It evaluates the agent session and report from Step 3 against methodology: quality, completeness, correctness, experimental rigour, tool correctness.

are the tools falling?
are the tasks delegating?
are the data hallucinating?
whether LLM counts numbers or causes a tool to count improvement
is there unnecessary duplication of information?
do all agents CORRECTLY understand the main purpose and do all steps correctly?
Is there unnecessary duplication?
Is the analysis too superficial?
Is the experiment pure and reproducible?
Does the methodology experiment work as designed?
Does the report match the template?
Is the result useful for professional migration decisions?

Step 5: Feedback loop¶

agents-regenerator is called again with prompt “Improvements from expert: <assessment>”. It incorporates expert feedback from Step 4, refines agent definitions, re-runs self-checks.

The regenerator rewrites the agents after a methodology update -> the new agents explore any project -> the migration-expert gives feedback on the report -> the regenerator updates agent definitions corresponding to the assessment <— it is a feedback loop with double self-checks after every action of the regenerator.

The agent regeneration process must include at least one feedback loop.

When to regenerate¶

Trigger	Required action
New step added to methodology	FULL regeneration
Existing step procedure changed	PARTIAL — regenerate affected agents
Report template updated	PARTIAL — regenerate agents that produce reports
Tool interface changed (rare)	PARTIAL — regenerate agents that use the tool
Editorial changes only (wording, clarifications)	NONE — skip regeneration

Versioning¶

Three components carry a SemVer-like three-part version <major>.<minor>.<patch>:

Methodology — marked by the > **Version**: <major>.<minor>.<patch> line at the top of docs/methodologies/migration-readiness-exploring-methodology.md.
Regeneration pipeline — one shared version for all regeneration agents (agents-regenerator and migration-expert), marked by the regeneration-pipeline version: <major>.<minor>.<patch> frontmatter field in each of their definitions.

Segment semantics (like SemVer):

Segment	Meaning
`major`	structural change of the document, reorganization, full (re)generation
`minor`	a new feature / update
`patch`	a small change, bug fix, correction, or hand-made change

Produced agents¶

Every generated agent definition carries an amphimixis-ai version frontmatter field with three dash-separated segments:

<methodology ver.>-<regeneration-pipeline ver.>-<regen count>.<hand-made patch>

Segments 1–2 record the fixed versions of the generating sources (methodology and regeneration pipeline) used to produce the agent.
Segment 3 is the concrete agent’s own version, working like SemVer Major.Patch: the first slot (regen count) bumps on each regeneration by the pipeline; the second slot (hand-made patch) bumps on direct manual edits outside regeneration.

Reset rule: if segment 1 (methodology) or segment 2 (regeneration pipeline) changes, segment 3 resets to 1.0.

Current values: methodology 0.1.0, regeneration pipeline 0.1.0, so a freshly generated agent with no hand-made patches is amphimixis-ai version: 0.1.0-0.1.0-1.0.