AI Maestro Programmer Agent (AMPA)

August 22, 2026 · View on GitHub

A general-purpose, multi-language programmer agent for Claude Code that implements, tests, fixes, and documents code across Python, JavaScript/TypeScript, Rust, Go, and other toolchains — either standalone or orchestrated within the AI Maestro ecosystem. The current version is recorded in .claude-plugin/plugin.json (the single source of truth).

Overview

The AI Maestro Programmer Agent is a general-purpose programmer that executes implementation tasks assigned by the Orchestrator. It handles the actual coding work across multiple programming languages and toolchains.

Standalone or Orchestrated: This plugin works in two modes. In standalone mode, the agent receives tasks directly from the user and reports back in conversation. In orchestrated mode (within the AI Maestro ecosystem), it receives tasks from the Orchestrator (AMOA) via messaging. No additional setup is needed for standalone mode.

Implementer Agents

In the AI Maestro ecosystem, implementers are agents that produce artifacts. The Programmer Agent (AMPA) is one subtype of implementer — it produces code, tests, and pull requests. Other implementer subtypes include artists (visual assets), SFX experts (audio assets), and more. All implementers share the same role (implementer) in team registries but use subtype-specific plugins and naming (e.g., svgbbox-programmer-001).

Prefix: ampa- = AI Maestro Programmer Agent

Core Responsibilities

Code Implementation: Write and modify source code according to specifications
Test Writing: Create comprehensive test suites
Code Fixing: Resolve bugs and linting/type errors
Documentation: Write inline documentation and docstrings
Multi-Language Support: Work across Python, JavaScript, Rust, Go, and compiled languages

Components

Agent (1)

Agent	File	Description
`ai-maestro-programmer-agent-main-agent`	`agents/ai-maestro-programmer-agent-main-agent.md`	Main general-purpose programmer agent

Skills (6)

Skill	Description
`ampa-task-execution`	Execute programming tasks per requirements
`ampa-orchestrator-communication`	Communication with the Orchestrator (AMOA) agent
`ampa-github-operations`	Git and GitHub operations (clone, branch, commit, PR)
`ampa-project-setup`	Initialize project configuration and install tooling
`ampa-handoff-management`	Create and receive handoff documents and bug reports
`ampa-prrd-trdd-kanban`	The MEMBER (programmer) role POLICY over the granular ama-* pillar skills — op-set, self-mandate rule, missing-derived-TRDD duty

Memory (global, janitor-hosted)

This plugin uses the global AI-Maestro markdown memory system — it ships no per-plugin memory skills or rules/ mirror. Recall / write / update go through the global janitor-memory-recall / -write / -update skills; the protocol + recall law live in ~/.claude/rules/markdown-memory-recall.md; the project's memory contract + scope routing live in CLAUDE.md. The git-tracked PROJECT-scope wiki is .claude/project/memory/ (stood up once via /janitor-memory-bootstrap). The memgrep binary (from ai-maestro-janitor) powers recall and degrades to grep when absent — recall degrades, never breaks.

Hooks

None. The hooks/hooks.json is empty -- AMPA uses globally installed hooks.

Scripts

The scripts/ directory contains 4 project utility scripts. Plugin validation runs through the CPV remote launcher (uvx … cpv-remote-validate), fetched on demand from Emasoft/claude-plugins-validation — the previously vendored CPV validator scripts were retired (CI and publish.py both call the remote validator, so local copies only drifted behind upstream).

Script	Description
`publish.py`	Strict release pipeline — test, lint, validate, bump, tag (`v{version}` + the `{name}--v{version}` dependency-resolution tag), atomic push
`pre-push-hook.py`	Git pre-push hook — runs cpv-remote-validate before each push
`test_order_pipeline.py`	Manual integration test for the order-processing-pipeline example (companion to `op-notify-completion.md`)
`smart_exec.py`	Cross-platform script executor with timeout support

Token-Efficient Reporting

Project scripts support file-based reporting to minimize terminal output:

Script	Flag	Description
`test_order_pipeline.py`	`--report-file PATH`	Write full test report to file; terminal gets concise summary
`pre-push-hook.py`	`AMPA_REPORT_FILE=PATH` (env var)	Write validation output to file; terminal gets concise summary

Workflow

The Programmer Agent owns Steps 14, 15, 17, 19, 21, 22 from the master workflow (the implementer's slice; the intervening Steps 16, 18, 20, 23 are owned by AMOA/AMIA — see docs/FULL_PROJECT_WORKFLOW.md):

Step 14: Request Clarification from Orchestrator
Step 15: Receive Feedback and Design Updates
Step 17: Task Execution (code, lint, test)
Step 19: Pre-PR Gate + PR Creation (after AMOA's green-light)
Step 21: Respond to PR Review Feedback
Step 22: Handle Failed PR (fix and resubmit)

Installation (Production)

Role plugins are installed with --scope local inside the specific agent's working directory (~/agents/<agent-name>/). This ensures the plugin is only available to that agent. Use one of the install commands below, then restart Claude Code — plugin metadata is cached and only picked up on a fresh start.

Installation (from GitHub)

claude plugin install ai-maestro-programmer-agent --url https://github.com/Emasoft/ai-maestro-programmer-agent

Installation (from git subdirectory)

If this plugin lives inside a parent repository, use the git-subdir source type:

claude plugin install ai-maestro-programmer-agent --url https://github.com/Emasoft/EMASOFT-PROGRAMMER-AGENT --subdir ai-maestro-programmer-agent

Once installed, start a session with the main agent:

claude --agent ai-maestro-programmer-agent-main-agent

Recommended Companion Plugins

Plugin	Purpose	Install
`llm-externalizer`	Offload file analysis, scanning, and comparison to cheaper local/remote LLMs — saves orchestrator context tokens	`claude plugin install llm-externalizer`

When llm-externalizer is installed alongside this plugin, the agent automatically uses it for code analysis (code_task), codebase scanning (scan_folder), per-file independent audits (code_task with answer_mode: 0 and max_retries: 3), and post-refactoring validation (check_references, check_imports).

Usage

Install the plugin using the command from the Installation section above.

Launch the agent in your project directory:

cd your-project/
claude --agent ai-maestro-programmer-agent-main-agent

In standalone mode (no orchestrator), describe your task directly in the conversation. The agent will set up the project environment, implement the code, write tests, and commit the changes.
In orchestrated mode (with AI Maestro running), the agent receives tasks automatically from the AMOA orchestrator via inter-agent messaging. See docs/FULL_PROJECT_WORKFLOW.md for the complete multi-agent workflow.

Development Only (--plugin-dir)

--plugin-dir loads a plugin directly from a local directory without marketplace installation. Use only during plugin development.

claude --plugin-dir .

After modifying plugin files, use /reload-plugins in your Claude Code session to activate changes without restarting.

A pre-push git hook (scripts/pre-push-hook.py) runs the validation suite before each push. Install it with:

cp scripts/pre-push-hook.py .git/hooks/pre-push && chmod +x .git/hooks/pre-push

Proxy / TLS Note

If you are behind a corporate proxy (MITM) and gh CLI fails with TLS errors, enable weaker network isolation in your Claude Code settings:

{ "sandbox": { "enableWeakerNetworkIsolation": true } }

Requirements

SERENA MCP (REQUIRED)

The Programmer Agent relies on SERENA MCP for code investigation:

Symbol search
Function/class lookup
Call graph analysis
Import/dependency tracking

SERENA must be available before starting work.

Supported Languages

Language	Toolchain	Linter	Formatter	Type Checker
Python	`uv`	`ruff check`	`ruff format`	`mypy`
JavaScript/TypeScript	`bun`	`eslint`	`prettier`	`tsc`
Rust	`cargo`	`clippy`	`rustfmt`	Built-in
Go	`go`	`staticcheck`	`gofmt`	Built-in
.NET (C#/F#)	`dotnet`	Built-in	Built-in	Built-in
C/C++	`gcc`/`clang`	`clang-tidy`	`clang-format`	Built-in
Objective-C	`clang`	`clang-tidy`	`clang-format`	Built-in
Swift	`swift`	`swiftlint`	`swift-format`	Built-in

Troubleshooting

Plugin Not Loading

Symptom: Commands/agents not available after installation

Cause: Claude Code caches plugin metadata

Solution: Restart Claude Code after installation/updates

SERENA MCP Not Available

Symptom: Code investigation fails with "SERENA not available"

Cause: SERENA MCP server not configured or not running

Solution:

Verify SERENA MCP is configured in Claude Code settings
Check MCP server is running: curl http://localhost:PORT/health
Restart Claude Code to reconnect to MCP servers

Tests Not Running

Symptom: Tests fail with "command not found"

Cause: Language toolchain not installed or not in PATH

Solution:

Install required toolchain (see Supported Languages table)
Verify toolchain is in PATH: which uv / which bun / etc.
Restart terminal/Claude Code to pick up PATH changes

Code Fixer Agent Failing

Symptom: Code fixer reports "Unable to fix errors"

Cause: Linter/formatter errors require manual intervention

Solution:

Review the linter/formatter errors the fixer reported in its output
Manual fix may be required for complex issues
Report blocking issues to Orchestrator

Validation

Validation runs through the CPV remote launcher — the exact command CI's validate.yml uses:

uvx --from git+https://github.com/Emasoft/claude-plugins-validation \
    --with pyyaml \
    cpv-remote-validate plugin . --strict

Exit codes: 0 = PASS; 1-4 (CRITICAL/MAJOR/MINOR/NIT) all block in strict mode. uvx ships with uv.

CI/CD

validate.yml — Runs plugin validation on push to main and PRs
release.yml — Creates GitHub releases on version tags (v*)
notify-marketplace.yml — Dispatches a plugin-updated event to the marketplace repo when plugin files change on main

Compatibility with Recent Claude Code Releases

AMPA is verified against Claude Code v2.1.105–v2.1.240. Most items below describe new platform capabilities that AMPA users can opt into without changing the plugin — but four changes altered how AMPA executes and required fixes: two in the v2.1.184–v2.1.224 range, one in v2.1.232, and one in v2.1.239. Each is marked Breaking in its table.

Main-thread agent capabilities (v2.1.116 / v2.1.117 / v2.1.119)

When AMPA is launched with claude --agent ai-maestro-programmer-agent-main-agent, Claude Code now reads three additional fields from the agent frontmatter:

Field	Effect	Added in
`mcpServers`	MCP servers are pre-loaded for the main-thread session — useful for declaring SERENA/LLM-Externalizer requirements at agent invocation time	v2.1.117
`hooks:`	Agent-level hooks fire on the main-thread session (previously subagent-only)	v2.1.116
`permissionMode`	`--agent` honors the agent's declared permission mode	v2.1.119

AMPA does not ship hard-coded mcpServers entries because SERENA MCP and LLM Externalizer are typically configured globally via the user's .mcp.json or via the llm-externalizer plugin's own server registration. Operators who want SERENA pre-loaded at --agent startup can extend the agent frontmatter in their own fork.

Hook authoring (v2.1.139)

When extending AMPA with hooks (project- or plugin-scope), prefer the exec-form args: string[] field over the shell-form command: string:

{
  "type": "command",
  "args": ["uv", "run", "scripts/pre-push-hook.py", "$CLAUDE_PROJECT_DIR"]
}

Exec form spawns the command directly without a shell, so path placeholders never need quoting and there is no shell-injection surface.

PreCompact hooks (v2.1.105) can block compaction — exit code 2 or {"decision":"block"} from a PreCompact hook keeps the current conversation intact. Useful for long task-execution flows where compaction mid-task would lose state.

Effort and caching (v2.1.108 / v2.1.120 / v2.1.133)

ENABLE_PROMPT_CACHING_1H=1 extends the prompt-cache TTL to 1 hour for API-key / Bedrock / Vertex / Foundry users. Recommended for long programmer sessions where AMPA re-reads the same project files turn after turn.
Skills and hooks now see the active effort level via ${CLAUDE_EFFORT} (skills) and $CLAUDE_EFFORT (Bash tool / hook env). AMPA skills can dial scan depth up/down based on this value when relevant.
xhigh effort level (v2.1.111) is available on the current Opus generation (introduced on Opus 4.7, carried forward to Opus 4.8) for the most thorough analyses; AMPA does not pin an effort level, so users control it via /effort.

New commands and OTel events worth knowing

Surface	What it does	Added in
`/goal`	Set a completion condition; Claude keeps working across turns	v2.1.139
`/ultrareview` / `claude ultrareview`	Parallel multi-agent code review; CI-friendly via the CLI subcommand. Deprecated in v2.1.223 — now an alias for `/code-review ultra`	v2.1.111 / v2.1.120
`/less-permission-prompts`	Scans transcripts for read-only Bash/MCP calls and proposes an allowlist	v2.1.111
`claude project purge`	Wipe all Claude Code state for a project	v2.1.126
`claude_code.skill_activated`	OpenTelemetry event with `invocation_trigger` attribute	v2.1.126
`worktree.bgIsolation: "none"`	Lets background sessions edit the working copy directly	v2.1.143

Plugin manifest changes (v2.1.129 / v2.1.143)

themes and monitors should now live under "experimental": { ... } in plugin.json. AMPA ships neither, so no migration is required.
claude plugin disable now refuses to disable a plugin that another enabled plugin depends on (with a copy-pasteable disable-chain hint). claude plugin enable force-enables transitive dependencies. AMPA declares one dependency (ai-maestro-plugin, the 3-pillars scripts), so claude plugin enable ai-maestro-programmer-agent force-enables it.

Newer releases (v2.1.144 – v2.1.183)

Change	Effect on AMPA	Added in
Subagent nesting	AMPA's spawned sub-agents may spawn their own; sub-agent `disallowedTools` MCP specs (`mcp__server`) are honored. The depth is no longer 5 — see the v2.1.217–v2.1.224 table below for the current cap	v2.1.172
`disallowed-tools` skill/command frontmatter + `/reload-skills`	A skill/command can drop tools while active; skill dirs re-scan without restart	v2.1.152
Plugins declare `.mcp.json` + `defaultEnabled: false`	A plugin may ship MCP servers and ship disabled-by-default; AMPA ships neither	v2.1.154
`Tool(param:value)` permission rules	e.g. `Agent(model:opus)` / `WebFetch(domain:*.example.com)` — finer allow/deny operators can apply to AMPA's tool use	v2.1.176 / v2.1.178
Nested-skills loading	Skills under a nested `.claude/skills/` load when working there; on a name clash they appear as `<dir>:<name>`	v2.1.178
`post-session` hook + `disableBundledSkills`	New end-of-session lifecycle hook; a setting to hide bundled skills from the model	v2.1.169
Dynamic-workflow keyword `workflow` → `ultracode`	The word "workflow" no longer auto-triggers; AMPA prose is unaffected (it never relied on auto-trigger)	v2.1.161
`/simplify` → `/code-review` (`--fix`, `--comment`)	If operators wire AMPA into a review step, use `/code-review`	v2.1.147 / v2.1.152
Lean system prompt default; Opus 4.8	AMPA pins no model/effort, so it inherits the session's — no change needed	v2.1.154
Model-deprecation warning now covers agent frontmatter	The warning fires (on stderr, incl. `-p`) for a deprecated/auto-updated model pinned in an agent's frontmatter. AMPA's agent pins no `model:` (it inherits the session's), so nothing is flagged	v2.1.183
Auto-mode destructive-git guards	The classifier blocks `git reset --hard`, `checkout -- .`, `clean -fd`, `stash drop`, non-agent `commit --amend`, and `terraform`/`pulumi`/`cdk destroy` unless asked. AMPA's `publish.py` git ops (`commit`/`tag`/`push`) are NOT in that set, so the publish pipeline is unaffected	v2.1.183
Scheduled-task / webhook deliveries are task notifications	In auto mode they can no longer approve a pending action or set the session title — safe for orchestrated/headless AMPA runs	v2.1.183
Foreground subagents respect the same nesting depth as background ones	AMPA fan-out stays bounded whichever way a sub-agent is spawned. The depth is no longer 5 — see below	v2.1.181
`/config key=value` from the prompt	Operators can set any setting inline (e.g. `/config effort=high`); no AMPA change — AMPA pins nothing it would override	v2.1.181

None of the above required an AMPA code change. The next table did.

v2.1.184 – v2.1.224 — including two changes AMPA had to act on

Change	Effect on AMPA	Added in
`context: fork` skills run in the BACKGROUND by default	Breaking, and silent. All six `ampa-` skills were `context: fork` with no `background:` key, so from v2.1.218 they returned an agent handle instead of their result — the invoking agent got nothing in the turn it asked, with no error. Fixed by removing `context: fork` entirely* (not by pinning `background: false`): a forked subagent has no AMP identity, so it can neither answer a comprehension handshake nor report a completion. The skills now run inline. Note the reason, not only the rule — v2.1.232 gave forks the full conversation, retiring the "a fork cannot see the context" half of the original argument while leaving the AMP-identity half untouched	v2.1.218
`disable-model-invocation: true` excludes a skill from subagent preload	Breaking, and silent. The agent's `skills:` field listed all six skills, and all six set that key — so the preload was inert and the agent booted without its own procedures. The key was removed from all six; the preload now works	—
Nested subagents: off by default, then default depth 3	`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` sets it. AMPA's own policy is stricter: single-layer delegation — the sub-agents AMPA spawns do not fan out further	v2.1.217 / v2.1.219
Concurrent-subagent cap (default 20)	`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`. AMPA's single-layer policy keeps it far below the cap	v2.1.217
Per-session 200-subagent spawn cap removed	Long AMPA sessions no longer refuse new agents; depth and concurrency limits still apply	v2.1.224 (added v2.1.212)
Agent names may not contain `:`	Reserved for plugin namespacing. AMPA's agent name is compliant; a non-compliant file is not loaded and the error goes only to the debug log	v2.1.218
`/review` is an alias of `/code-review`; `/ultrareview` is deprecated	Use `/code-review <level>` or `/code-review ultra`. With no level it reuses the last one you typed	v2.1.223
Task tool's `mode` parameter deprecated (ignored)	Subagents inherit the parent session's permission mode. AMPA never passed it	v2.1.212
Native cross-session `SendMessage` + `ListAgents`	Claude Code sessions can message each other across machines. AMPA does not adopt it: it carries no AI Maestro AID, so a message has no verifiable author, no R6 routing, and no audit entry. AMP remains AMPA's governed channel. Not unsafe — relayed messages have carried no user authority since v2.1.166 and are classifier-evaluated since v2.1.222 — but ungoverned, and the transport choice is fleet governance, not a plugin's to make	v2.1.224
`DirectoryAdded` hook	Fires on `/add-dir`. AMPA registers no hooks: adding a workspace root does not change `cwd`, and AMPA keys nothing on workspace roots. Deliberate, not an omission	v2.1.219
Frontmatter booleans accept `yes`/`no`/`on`/`off`/`1`/`0`	Alongside `true`/`false`. AMPA uses `true`/`false`	v2.1.222
`archive` plugin source with optional SHA-256 pinning	Install from a zip over HTTPS, no git or npm. A marketplace-entry feature, not a plugin-manifest one — nothing for AMPA to declare	v2.1.224
Plugins accept `"."` as a `skills` path	For single-skill plugins whose `SKILL.md` sits at the root. AMPA uses the `skills/` directory layout	v2.1.221

v2.1.225 – v2.1.232 — including one more change AMPA had to act on

Change	Effect on AMPA	Added in
Non-teammate agent spawns run in the BACKGROUND by default	Breaking, and silent — the v2.1.218 defect class, one layer up. An interactive spawn now returns a handle, not the subagent's output; the result arrives later as a task notification. The agent prompt had promised an in-turn return, so it was rewritten to collect before relaying: never relay a handle as a finding, never report a delegated task complete on the strength of having spawned it. Confirmed first-hand on v2.1.232	v2.1.232
Subagent forking on by default; a fork inherits the full conversation and prompt cache	Does not reopen `context: fork` for the `ampa-*` skills. Three reasons survive, each sufficient on its own: a fork still has no AMP identity; a fork is itself a background spawn; and a fork's state never merges back, while these procedures mutate the main agent's own state. The prompt now records all three, so the constraint cannot be discarded on a reason that has expired	v2.1.232
`@` mentions another session in the prompt; `SendMessage` delivers to a bare name	Makes the native cross-session channel far easier to reach by accident. AMPA's non-adoption stance is unchanged (see the v2.1.224 row): AMP stays the governed channel because it carries an AI Maestro AID. The `@` affordance is a user action in the operator's session, not something the plugin invokes	v2.1.232
Interactive sessions keep unique names on one machine	A session claiming a name another live session holds gets a `name-word-word` variant. AMPA keys nothing on session names — its identity is its AID	v2.1.232
Write tool: newer models may overwrite a file they have not read this session	Now matches the Edit tool's rules; older models still require the read first. AMPA asserted no read-before-write rule, so nothing broke — and none was added, since overwriting unread files is not a habit worth teaching	v2.1.228
`/plugin install plugin@marketplace` refreshes the marketplace first	A newly published AMPA version installs without a manual marketplace refresh. AMPA's documented install uses `--url`, so this reaches marketplace users only	v2.1.232
`/code-review` at high, xhigh, and max runs in a background agent	Now matches the other levels. Operators who wire AMPA into a review step get the result as a notification, not inline	v2.1.232
Marketplace `command` sources; GitLab marketplaces; `additionalMarketplaces` / `allowedMarketplaces` aliases	All marketplace-entry features, not plugin-manifest ones — nothing for AMPA to declare	v2.1.229 / v2.1.232

v2.1.233 – v2.1.240 — including one change AMPA had to act on

Change	What it means for AMPA	Version
UTF-8 BOM in an agent/skill/command `.md` silently ignored (now fixed)	Breaking. Same silent defect class as v2.1.218 and v2.1.232: no error, the artifact simply never loads. AMPA ships none today (verified by byte check over every tracked file, 2026-08-22) and a pytest guard now enforces that	v2.1.239
Todo/task tools (`TaskCreate`/`TaskGet`/`TaskUpdate`/`TaskList`, `TodoWrite`) removed on Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and newer	`CLAUDE_CODE_ENABLE_TODO_TOOLS=1` restores them. AMPA's persona and skills reference none of them (verified by grep), so nothing broke and nothing was added	v2.1.233
Background task notifications between turns now arrive wrapped in `<system-reminder>` tags	Matching mid-turn delivery — this is how a delegated subagent's result reaches AMPA under the v2.1.232 collect-before-relay rule. The persona now records that the envelope is platform-generated context, never user input and never user approval	v2.1.234
"Default teammate model" setting removed; agent-team teammates use the leader's model unless the spawn names one	AMPA pins no `model:` in its frontmatter, so it inherits correctly by default	v2.1.234
An omitted `subagent_type` now returns an error listing available agents	Previously the Agent tool advertised a general-purpose default even where unavailable, so an omission failed silently into the wrong agent. Nothing in AMPA depends on that removed default: the persona's only `subagent_type` rule is the prohibition on `"fork"` for AMP-coupled steps (grep, 2026-08-22). The persona asserts no general naming rule, and none was invented here to make the row read better	v2.1.235
`ANTHROPIC_DEFAULT_MODEL` sets the model new sessions start on	A `/model` pick still overrides it. An operator preference, not a plugin declaration	v2.1.236
`notify_when_idle` on cross-session `SendMessage`	One-shot idle notice, no polling. AMPA's non-adoption stance for the native channel is unchanged (see the v2.1.224 row): AMP stays the governed channel because it carries an AI Maestro AID	v2.1.236
`ListAgents` reports a session its own name and lists live teammates; Windows gains cross-session messaging	Makes the native channel easier to reach, which does not make it governed. Stance unchanged	v2.1.239
Marketplace `headersHelper`; `claude plugin install/update` prompt `[y/N]` (or `-y`)	The prompt appears only where a catalog entry declares a `headersHelper`. AMPA's documented install is `--url` with none, so scripted installs are unaffected; a marketplace that adds one will need `-y` in CI	v2.1.238
`claude plugin validate` now checks a bare `.claude/skills` directory; marketplace `metadata.pluginRoot` fixed	Both marketplace/tooling-side. AMPA uses the `skills/` layout and declares no `pluginRoot`	v2.1.233 / v2.1.239