You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by "Kaap10 (via GitHub)" <gi...@apache.org> on 2026/09/19 00:54:15 UTC
[PR] feat(adapter/aider): Aider agent harness runtime guide [magpie]
Kaap10 opened a new pull request, #1286:
URL: https://github.com/apache/magpie/pull/1286
<!-- SPDX-License-Identifier: Apache-2.0
https://www.apache.org/licenses/LICENSE-2.0 -->
## Summary
- Adds `docs/adapters/aider.md` operating guide for Aider terminal pair programming agent harness per RFC-AI-0004 Principle 3 (Vendor Neutrality).
- Documents progressive skill ingestion via on-demand `/read .agents/skills/magpie-*/SKILL.md` (and `--read`) to avoid context window flooding across 70+ workflows.
- Prescribes strict Human-in-the-loop (HITL) confirmation by enforcing `--no-auto-commits` / `--no-dirty-commits` (and `auto-commits: false` in `.aider.conf.yml`) to prevent unreviewed autonomous git mutations.
- Documents repository instruction ingestion via `AGENTS.md`, `.aiderignore` for private token/override protection, `--architect` multi-model tiering, and `agent-iso aider` Layer 0 isolation.
- Updates adapter registry (`docs/adapters/registry.md` with `guide only` qualifier), contributor guide (`CONTRIBUTING.md`), prerequisites (`docs/quick-start/prerequisites.md`), and vendor-neutrality matrix (`docs/vendor-neutrality.md`).
## Type of change
- [ ] Skill change (`.claude/skills/<name>/`) — eval fixtures updated below
- [ ] Tool / bridge contract (`tools/<system>/*.md`)
- [ ] Python package (`tools/*/` with `pyproject.toml`)
- [ ] Groovy reference impl
- [x] Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
- [x] Documentation (`docs/`, `README.md`, `CONTRIBUTING.md`)
- [ ] Project template (`projects/_template/`)
- [ ] CI / dev loop (`prek`, workflows, validators)
- [ ] Other:
## Test plan
- [x] `prek run doctoc --all-files` passed with 0 modifications
- [x] `prek run markdownlint-cli2 --all-files` passed with 0 violations
- [x] `uv run --project tools/symlink-lint symlink-lint` passed with 0 defects
- [x] `uv run --project tools/vendor-neutrality-score vendor-neutrality-score` passed 100% (10/10 capability contracts, 24/24 substrate tools)
- [x] `git diff --check` passed with 0 whitespace/formatting errors
## RFC-AI-0004 compliance
- [x] **HITL** — any new mutation is gated on explicit user confirmation (`--no-auto-commits` / `--no-dirty-commits`)
- [x] **Sandbox** — clean-environment isolation via `agent-iso aider`
- [x] **Vendor neutrality** — placeholders (`<PROJECT>`, `<tracker>`, `<upstream>`, `<framework>`) used in all prose
- [ ] **Conversational + correctable** — agentic-override path documented if behaviour is adopter-tunable
- [ ] **Write-access discipline** — no autonomous outbound messages; drafts only, sent on confirmation
- [x] **Privacy LLM** — private content does not reach a non-approved LLM; local offline inference via Ollama/vLLM documented
## Linked issues
Closes #317
## Notes for reviewers (optional)
Follows the established agent harness adapter structure from `docs/adapters/cursor.md`, `docs/adapters/local-llm.md`, and `docs/adapters/goose.md`. Adopts the standard `## Harness contract` terminology and marks the registry entry as `guide only` per the incremental landing pattern in `add-a-harness.md`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat(adapter/aider): Aider agent harness runtime guide [magpie]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk commented on code in PR #1286:
URL: https://github.com/apache/magpie/pull/1286#discussion_r4052796287
##########
docs/adapters/aider.md:
##########
@@ -0,0 +1,236 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Aider agent harness](#aider-agent-harness)
+ - [Harness contract](#harness-contract)
+ - [Invoke a Magpie skill](#invoke-a-magpie-skill)
+ - [Interactive terminal session](#interactive-terminal-session)
+ - [Progressive skill disclosure](#progressive-skill-disclosure)
+ - [Headless or automated execution](#headless-or-automated-execution)
+ - [Configuration and repository instructions](#configuration-and-repository-instructions)
+ - [Repository configuration (`.aider.conf.yml`)](#repository-configuration-aiderconfyml)
+ - [Protecting private and local state (`.aiderignore`)](#protecting-private-and-local-state-aiderignore)
+ - [Tool bridges and subshell execution](#tool-bridges-and-subshell-execution)
+ - [Human-in-the-loop and git confirmation](#human-in-the-loop-and-git-confirmation)
+ - [Multi-model routing and model floors](#multi-model-routing-and-model-floors)
+ - [Architect and editor model split](#architect-and-editor-model-split)
+ - [Local LLM connectivity (Ollama / vLLM)](#local-llm-connectivity-ollama--vllm)
+ - [Clean-environment wrapper and isolation](#clean-environment-wrapper-and-isolation)
+ - [Verify](#verify)
+ - [See also](#see-also)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Aider agent harness
+
+**Capability:** capability:platform
+
+**Harness:** Aider (aider.chat)
+
+[Aider](https://aider.chat/) is an open-source (Apache 2.0 licensed), model-agnostic terminal pair programming agent harness.
+This guide documents how Aider operates as an agent harness for Apache Magpie for [#317](https://github.com/apache/magpie/issues/317).
+Grounding is established by [RFC-AI-0004 Principle 3 (Vendor Neutrality)](../rfcs/RFC-AI-0004.md), which guarantees that Magpie adopters can drive all framework workflows using fully open-source, non-proprietary agent harnesses.
+
+Aider provides an open-source execution stack with:
+1. **Model independence:** Native connectivity to Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and local open-weight inference runners (Ollama, llama.cpp, vLLM).
+2. **Git-native pairing:** Tight integration with git working trees and incremental file editing.
+3. **Multi-model tiering:** Built-in `--architect` mode splitting reasoning and code-editing responsibilities across specialized model tiers.
+
+## Harness contract
+
+| Magpie requirement | Aider implementation |
+|---|---|
+| Skill discovery | Aider ingests canonical `.agents/skills/magpie-*/SKILL.md` workflows on demand via `/read` or `--read` (Progressive Disclosure). |
+| Repository instructions | Aider ingests repository instructions from `.aider.conf.yml` or `CONVENTIONS.md` (referencing `AGENTS.md` and adopter instructions from `<project-config>/`). |
+| Tool execution | Aider executes Magpie's language-agnostic `tools/*` CLI bridges via in-session `/run <cmd>` or subshell execution with operator confirmation. |
+| Model Context Protocol (MCP) | Aider does not natively host MCP client servers; deterministic tools execute as language-agnostic CLI scripts under `tools/`. |
+| Human-in-the-loop (HITL) | Prescribed `--no-auto-commits` and `--no-dirty-commits` enforces strict proposal-then-confirm discipline before mutating git state. |
+| Credential & environment isolation | `agent-iso aider` launches the agent through the clean-environment wrapper (Layer 0 isolation, stripping ambient tokens while passing `SSH_AUTH_SOCK`). |
+
+## Invoke a Magpie skill
+
+After running `/magpie-setup` to adopt the repository, the canonical `.agents/skills/` links are active in your working tree.
+Aider discovers and loads these skills directly from the workspace.
+
+### Interactive terminal session
+
+Start an interactive session within the adopted repository:
+
+```bash
+# Launch Aider with filtered environment variables and disabled auto-commits
+source <framework>/tools/agent-isolation/agent-iso.sh
+agent-iso aider --model <model> --no-auto-commits --no-dirty-commits
+```
+
+### Progressive skill disclosure
+
+To prevent context-window exhaustion across Magpie's 70+ workflows, load only the specific skill required for the current task:
+
+```text
+/read .agents/skills/magpie-security-issue-triage/SKILL.md
+```
+
+Inside the session, prompt Aider to execute the workflow:
+
+```text
+Follow the procedure in the loaded SKILL.md to triage inbound report #<issue-number>.
+Adhere strictly to proposal-then-confirm discipline before applying any tracker mutations.
+```
+
+Aider reads the loaded `SKILL.md`, checks prerequisites, and presents proposed diagnostic steps before taking action.
+
+### Headless or automated execution
+
+For non-interactive triage passes, automated sweeps, or headless scripting:
+
+```bash
+# Headless run using an explicit instruction text (-m) and target skill file
+aider --model <model> \
+ --read .agents/skills/magpie-list-skills/SKILL.md \
+ --message "Execute the loaded list-skills procedure and summarize available workflows." \
+ --no-auto-commits \
+ --exit
+```
+
+## Configuration and repository instructions
+
+### Repository configuration (`.aider.conf.yml`)
+
+Configure repository defaults in `.aider.conf.yml` at the repository root to ensure all team members operate under Magpie's safety baseline:
+
+```yaml
+# .aider.conf.yml
+# 1. Enforce Human-in-the-loop confirmation
+auto-commits: false
+dirty-commits: false
+
+# 2. Ingest repository safety instructions
+read:
+ - AGENTS.md
+
+# 3. Model parameters (optional adopter defaults)
+# model: anthropic/claude-3-7-sonnet-20250219
+# edit-format: diff
+```
+
+### Protecting private and local state (`.aiderignore`)
+
+Aider automatically constructs a repository map (repomap) to track codebase structure.
+To prevent Aider from reading private adopter tokens, test fixtures, or local overrides into the prompt context, configure `.aiderignore` at the repository root:
+
+```text
+# .aiderignore
+.apache-magpie-local/
+.env*
+*.key
+*.pem
+.git/
+tools/agent-isolation/tmp/
+```
+
+## Tool bridges and subshell execution
+
+Magpie skills execute deterministic operations via language-agnostic scripts under `tools/` (e.g. `tools/cve-tool-vulnogram/`, `tools/github/`, `tools/privacy-llm/`).
+
+When a skill requires running a tool command:
+- The operator or model proposes the subshell command (e.g. `uv run --project tools/github gh-issue-view ...`).
Review Comment:
`uv run --project tools/github gh-issue-view ...` does not exist: `tools/github/` is a documentation-only adapter with no `pyproject.toml`, so `uv` errors on it. Please use a real command from `tools/github/operations.md`, e.g. `gh issue view <N> --repo <tracker>`.
##########
docs/adapters/aider.md:
##########
@@ -0,0 +1,236 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Aider agent harness](#aider-agent-harness)
+ - [Harness contract](#harness-contract)
+ - [Invoke a Magpie skill](#invoke-a-magpie-skill)
+ - [Interactive terminal session](#interactive-terminal-session)
+ - [Progressive skill disclosure](#progressive-skill-disclosure)
+ - [Headless or automated execution](#headless-or-automated-execution)
+ - [Configuration and repository instructions](#configuration-and-repository-instructions)
+ - [Repository configuration (`.aider.conf.yml`)](#repository-configuration-aiderconfyml)
+ - [Protecting private and local state (`.aiderignore`)](#protecting-private-and-local-state-aiderignore)
+ - [Tool bridges and subshell execution](#tool-bridges-and-subshell-execution)
+ - [Human-in-the-loop and git confirmation](#human-in-the-loop-and-git-confirmation)
+ - [Multi-model routing and model floors](#multi-model-routing-and-model-floors)
+ - [Architect and editor model split](#architect-and-editor-model-split)
+ - [Local LLM connectivity (Ollama / vLLM)](#local-llm-connectivity-ollama--vllm)
+ - [Clean-environment wrapper and isolation](#clean-environment-wrapper-and-isolation)
+ - [Verify](#verify)
+ - [See also](#see-also)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Aider agent harness
+
+**Capability:** capability:platform
+
+**Harness:** Aider (aider.chat)
+
+[Aider](https://aider.chat/) is an open-source (Apache 2.0 licensed), model-agnostic terminal pair programming agent harness.
+This guide documents how Aider operates as an agent harness for Apache Magpie for [#317](https://github.com/apache/magpie/issues/317).
+Grounding is established by [RFC-AI-0004 Principle 3 (Vendor Neutrality)](../rfcs/RFC-AI-0004.md), which guarantees that Magpie adopters can drive all framework workflows using fully open-source, non-proprietary agent harnesses.
+
+Aider provides an open-source execution stack with:
+1. **Model independence:** Native connectivity to Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and local open-weight inference runners (Ollama, llama.cpp, vLLM).
+2. **Git-native pairing:** Tight integration with git working trees and incremental file editing.
+3. **Multi-model tiering:** Built-in `--architect` mode splitting reasoning and code-editing responsibilities across specialized model tiers.
+
+## Harness contract
+
+| Magpie requirement | Aider implementation |
+|---|---|
+| Skill discovery | Aider ingests canonical `.agents/skills/magpie-*/SKILL.md` workflows on demand via `/read` or `--read` (Progressive Disclosure). |
+| Repository instructions | Aider ingests repository instructions from `.aider.conf.yml` or `CONVENTIONS.md` (referencing `AGENTS.md` and adopter instructions from `<project-config>/`). |
+| Tool execution | Aider executes Magpie's language-agnostic `tools/*` CLI bridges via in-session `/run <cmd>` or subshell execution with operator confirmation. |
+| Model Context Protocol (MCP) | Aider does not natively host MCP client servers; deterministic tools execute as language-agnostic CLI scripts under `tools/`. |
+| Human-in-the-loop (HITL) | Prescribed `--no-auto-commits` and `--no-dirty-commits` enforces strict proposal-then-confirm discipline before mutating git state. |
+| Credential & environment isolation | `agent-iso aider` launches the agent through the clean-environment wrapper (Layer 0 isolation, stripping ambient tokens while passing `SSH_AUTH_SOCK`). |
+
+## Invoke a Magpie skill
+
+After running `/magpie-setup` to adopt the repository, the canonical `.agents/skills/` links are active in your working tree.
+Aider discovers and loads these skills directly from the workspace.
+
+### Interactive terminal session
+
+Start an interactive session within the adopted repository:
+
+```bash
+# Launch Aider with filtered environment variables and disabled auto-commits
+source <framework>/tools/agent-isolation/agent-iso.sh
+agent-iso aider --model <model> --no-auto-commits --no-dirty-commits
+```
+
+### Progressive skill disclosure
+
+To prevent context-window exhaustion across Magpie's 70+ workflows, load only the specific skill required for the current task:
+
+```text
+/read .agents/skills/magpie-security-issue-triage/SKILL.md
+```
+
+Inside the session, prompt Aider to execute the workflow:
+
+```text
+Follow the procedure in the loaded SKILL.md to triage inbound report #<issue-number>.
+Adhere strictly to proposal-then-confirm discipline before applying any tracker mutations.
+```
+
+Aider reads the loaded `SKILL.md`, checks prerequisites, and presents proposed diagnostic steps before taking action.
+
+### Headless or automated execution
+
+For non-interactive triage passes, automated sweeps, or headless scripting:
+
+```bash
+# Headless run using an explicit instruction text (-m) and target skill file
+aider --model <model> \
+ --read .agents/skills/magpie-list-skills/SKILL.md \
+ --message "Execute the loaded list-skills procedure and summarize available workflows." \
+ --no-auto-commits \
+ --exit
+```
+
+## Configuration and repository instructions
+
+### Repository configuration (`.aider.conf.yml`)
+
+Configure repository defaults in `.aider.conf.yml` at the repository root to ensure all team members operate under Magpie's safety baseline:
+
+```yaml
+# .aider.conf.yml
+# 1. Enforce Human-in-the-loop confirmation
+auto-commits: false
+dirty-commits: false
+
+# 2. Ingest repository safety instructions
+read:
+ - AGENTS.md
+
+# 3. Model parameters (optional adopter defaults)
+# model: anthropic/claude-3-7-sonnet-20250219
+# edit-format: diff
+```
+
+### Protecting private and local state (`.aiderignore`)
+
+Aider automatically constructs a repository map (repomap) to track codebase structure.
+To prevent Aider from reading private adopter tokens, test fixtures, or local overrides into the prompt context, configure `.aiderignore` at the repository root:
+
+```text
+# .aiderignore
+.apache-magpie-local/
+.env*
+*.key
+*.pem
+.git/
+tools/agent-isolation/tmp/
Review Comment:
`tools/agent-isolation/tmp/` does not exist in the tree. `.git/` and `.apache-magpie-local/` are already excluded because Aider honours `.gitignore`; the `.env*` / key patterns are the useful part of this list.
##########
docs/adapters/aider.md:
##########
@@ -0,0 +1,236 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Aider agent harness](#aider-agent-harness)
+ - [Harness contract](#harness-contract)
+ - [Invoke a Magpie skill](#invoke-a-magpie-skill)
+ - [Interactive terminal session](#interactive-terminal-session)
+ - [Progressive skill disclosure](#progressive-skill-disclosure)
+ - [Headless or automated execution](#headless-or-automated-execution)
+ - [Configuration and repository instructions](#configuration-and-repository-instructions)
+ - [Repository configuration (`.aider.conf.yml`)](#repository-configuration-aiderconfyml)
+ - [Protecting private and local state (`.aiderignore`)](#protecting-private-and-local-state-aiderignore)
+ - [Tool bridges and subshell execution](#tool-bridges-and-subshell-execution)
+ - [Human-in-the-loop and git confirmation](#human-in-the-loop-and-git-confirmation)
+ - [Multi-model routing and model floors](#multi-model-routing-and-model-floors)
+ - [Architect and editor model split](#architect-and-editor-model-split)
+ - [Local LLM connectivity (Ollama / vLLM)](#local-llm-connectivity-ollama--vllm)
+ - [Clean-environment wrapper and isolation](#clean-environment-wrapper-and-isolation)
+ - [Verify](#verify)
+ - [See also](#see-also)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Aider agent harness
+
+**Capability:** capability:platform
+
+**Harness:** Aider (aider.chat)
+
+[Aider](https://aider.chat/) is an open-source (Apache 2.0 licensed), model-agnostic terminal pair programming agent harness.
+This guide documents how Aider operates as an agent harness for Apache Magpie for [#317](https://github.com/apache/magpie/issues/317).
+Grounding is established by [RFC-AI-0004 Principle 3 (Vendor Neutrality)](../rfcs/RFC-AI-0004.md), which guarantees that Magpie adopters can drive all framework workflows using fully open-source, non-proprietary agent harnesses.
+
+Aider provides an open-source execution stack with:
+1. **Model independence:** Native connectivity to Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and local open-weight inference runners (Ollama, llama.cpp, vLLM).
+2. **Git-native pairing:** Tight integration with git working trees and incremental file editing.
+3. **Multi-model tiering:** Built-in `--architect` mode splitting reasoning and code-editing responsibilities across specialized model tiers.
+
+## Harness contract
+
+| Magpie requirement | Aider implementation |
+|---|---|
+| Skill discovery | Aider ingests canonical `.agents/skills/magpie-*/SKILL.md` workflows on demand via `/read` or `--read` (Progressive Disclosure). |
+| Repository instructions | Aider ingests repository instructions from `.aider.conf.yml` or `CONVENTIONS.md` (referencing `AGENTS.md` and adopter instructions from `<project-config>/`). |
+| Tool execution | Aider executes Magpie's language-agnostic `tools/*` CLI bridges via in-session `/run <cmd>` or subshell execution with operator confirmation. |
+| Model Context Protocol (MCP) | Aider does not natively host MCP client servers; deterministic tools execute as language-agnostic CLI scripts under `tools/`. |
Review Comment:
"does not natively host MCP client servers" reads oddly. Aider has no MCP client at all (nothing in its options reference); say that plainly.
##########
docs/adapters/aider.md:
##########
@@ -0,0 +1,236 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Aider agent harness](#aider-agent-harness)
+ - [Harness contract](#harness-contract)
+ - [Invoke a Magpie skill](#invoke-a-magpie-skill)
+ - [Interactive terminal session](#interactive-terminal-session)
+ - [Progressive skill disclosure](#progressive-skill-disclosure)
+ - [Headless or automated execution](#headless-or-automated-execution)
+ - [Configuration and repository instructions](#configuration-and-repository-instructions)
+ - [Repository configuration (`.aider.conf.yml`)](#repository-configuration-aiderconfyml)
+ - [Protecting private and local state (`.aiderignore`)](#protecting-private-and-local-state-aiderignore)
+ - [Tool bridges and subshell execution](#tool-bridges-and-subshell-execution)
+ - [Human-in-the-loop and git confirmation](#human-in-the-loop-and-git-confirmation)
+ - [Multi-model routing and model floors](#multi-model-routing-and-model-floors)
+ - [Architect and editor model split](#architect-and-editor-model-split)
+ - [Local LLM connectivity (Ollama / vLLM)](#local-llm-connectivity-ollama--vllm)
+ - [Clean-environment wrapper and isolation](#clean-environment-wrapper-and-isolation)
+ - [Verify](#verify)
+ - [See also](#see-also)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Aider agent harness
+
+**Capability:** capability:platform
+
+**Harness:** Aider (aider.chat)
+
+[Aider](https://aider.chat/) is an open-source (Apache 2.0 licensed), model-agnostic terminal pair programming agent harness.
+This guide documents how Aider operates as an agent harness for Apache Magpie for [#317](https://github.com/apache/magpie/issues/317).
+Grounding is established by [RFC-AI-0004 Principle 3 (Vendor Neutrality)](../rfcs/RFC-AI-0004.md), which guarantees that Magpie adopters can drive all framework workflows using fully open-source, non-proprietary agent harnesses.
+
+Aider provides an open-source execution stack with:
+1. **Model independence:** Native connectivity to Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and local open-weight inference runners (Ollama, llama.cpp, vLLM).
+2. **Git-native pairing:** Tight integration with git working trees and incremental file editing.
+3. **Multi-model tiering:** Built-in `--architect` mode splitting reasoning and code-editing responsibilities across specialized model tiers.
+
+## Harness contract
+
+| Magpie requirement | Aider implementation |
+|---|---|
+| Skill discovery | Aider ingests canonical `.agents/skills/magpie-*/SKILL.md` workflows on demand via `/read` or `--read` (Progressive Disclosure). |
+| Repository instructions | Aider ingests repository instructions from `.aider.conf.yml` or `CONVENTIONS.md` (referencing `AGENTS.md` and adopter instructions from `<project-config>/`). |
+| Tool execution | Aider executes Magpie's language-agnostic `tools/*` CLI bridges via in-session `/run <cmd>` or subshell execution with operator confirmation. |
+| Model Context Protocol (MCP) | Aider does not natively host MCP client servers; deterministic tools execute as language-agnostic CLI scripts under `tools/`. |
+| Human-in-the-loop (HITL) | Prescribed `--no-auto-commits` and `--no-dirty-commits` enforces strict proposal-then-confirm discipline before mutating git state. |
+| Credential & environment isolation | `agent-iso aider` launches the agent through the clean-environment wrapper (Layer 0 isolation, stripping ambient tokens while passing `SSH_AUTH_SOCK`). |
+
+## Invoke a Magpie skill
+
+After running `/magpie-setup` to adopt the repository, the canonical `.agents/skills/` links are active in your working tree.
+Aider discovers and loads these skills directly from the workspace.
+
+### Interactive terminal session
+
+Start an interactive session within the adopted repository:
+
+```bash
+# Launch Aider with filtered environment variables and disabled auto-commits
+source <framework>/tools/agent-isolation/agent-iso.sh
+agent-iso aider --model <model> --no-auto-commits --no-dirty-commits
+```
+
+### Progressive skill disclosure
+
+To prevent context-window exhaustion across Magpie's 70+ workflows, load only the specific skill required for the current task:
+
+```text
+/read .agents/skills/magpie-security-issue-triage/SKILL.md
+```
+
+Inside the session, prompt Aider to execute the workflow:
+
+```text
+Follow the procedure in the loaded SKILL.md to triage inbound report #<issue-number>.
+Adhere strictly to proposal-then-confirm discipline before applying any tracker mutations.
+```
+
+Aider reads the loaded `SKILL.md`, checks prerequisites, and presents proposed diagnostic steps before taking action.
+
+### Headless or automated execution
+
+For non-interactive triage passes, automated sweeps, or headless scripting:
+
+```bash
+# Headless run using an explicit instruction text (-m) and target skill file
+aider --model <model> \
+ --read .agents/skills/magpie-list-skills/SKILL.md \
+ --message "Execute the loaded list-skills procedure and summarize available workflows." \
+ --no-auto-commits \
+ --exit
+```
+
+## Configuration and repository instructions
+
+### Repository configuration (`.aider.conf.yml`)
+
+Configure repository defaults in `.aider.conf.yml` at the repository root to ensure all team members operate under Magpie's safety baseline:
+
+```yaml
+# .aider.conf.yml
+# 1. Enforce Human-in-the-loop confirmation
+auto-commits: false
+dirty-commits: false
+
+# 2. Ingest repository safety instructions
+read:
+ - AGENTS.md
+
+# 3. Model parameters (optional adopter defaults)
+# model: anthropic/claude-3-7-sonnet-20250219
+# edit-format: diff
+```
+
+### Protecting private and local state (`.aiderignore`)
+
+Aider automatically constructs a repository map (repomap) to track codebase structure.
+To prevent Aider from reading private adopter tokens, test fixtures, or local overrides into the prompt context, configure `.aiderignore` at the repository root:
+
+```text
+# .aiderignore
+.apache-magpie-local/
+.env*
+*.key
+*.pem
+.git/
+tools/agent-isolation/tmp/
+```
+
+## Tool bridges and subshell execution
+
+Magpie skills execute deterministic operations via language-agnostic scripts under `tools/` (e.g. `tools/cve-tool-vulnogram/`, `tools/github/`, `tools/privacy-llm/`).
+
+When a skill requires running a tool command:
+- The operator or model proposes the subshell command (e.g. `uv run --project tools/github gh-issue-view ...`).
+- In an interactive session, execute the command directly via `/run <cmd>` or `!<cmd>`.
+- Actions execute in the local project environment following standard subshell semantics.
+
+## Human-in-the-loop and git confirmation
+
+Magpie enforces strict [Human-in-the-Loop principles](../rfcs/RFC-AI-0004.md): no destructive action or git state mutation occurs without explicit human approval.
+
+> [!IMPORTANT]
+> **Aider auto-commit policy:** By default, Aider automatically commits every code modification to git.
+>
+> In Magpie adopted repositories, adopters **must disable auto-commits** either via CLI flags:
+> ```bash
+> aider --no-auto-commits --no-dirty-commits
+> ```
+> or via `.aider.conf.yml`:
+> ```yaml
+> auto-commits: false
+> dirty-commits: false
+> ```
+
+When operating with auto-commits disabled:
+- **Diff review:** Review proposed file changes using `git diff` or in-session `/diff` before staging.
+- **Explicit commit gating:** Use `/commit` only after confirming the change satisfies review criteria.
+- **Write-access discipline:** Outbound communications, issue state changes (`gh issue close`), and remote pushes (`git push`) must always remain gated on explicit human confirmation.
+
+## Multi-model routing and model floors
+
+Aider supports multi-provider model routing, allowing adopters to calibrate model power against task complexity per [docs/mode-economics.md](../mode-economics.md).
+
+### Architect and editor model split
+
+For complex triage and vulnerability assessment, use Aider's `--architect` mode to separate high-level reasoning from code editing:
+
+```bash
+# Reasoning model handles analysis; fast editor applies diffs
+aider --architect \
+ --model anthropic/claude-3-7-sonnet-20250219 \
Review Comment:
Hard-coded vendor model ids in a vendor-neutrality guide, and both are stale already. The rest of the page uses `<model>`; suggest `<reasoning-model>` / `<editor-model>` placeholders here so the snippet does not rot.
##########
docs/adapters/aider.md:
##########
@@ -0,0 +1,236 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Aider agent harness](#aider-agent-harness)
+ - [Harness contract](#harness-contract)
+ - [Invoke a Magpie skill](#invoke-a-magpie-skill)
+ - [Interactive terminal session](#interactive-terminal-session)
+ - [Progressive skill disclosure](#progressive-skill-disclosure)
+ - [Headless or automated execution](#headless-or-automated-execution)
+ - [Configuration and repository instructions](#configuration-and-repository-instructions)
+ - [Repository configuration (`.aider.conf.yml`)](#repository-configuration-aiderconfyml)
+ - [Protecting private and local state (`.aiderignore`)](#protecting-private-and-local-state-aiderignore)
+ - [Tool bridges and subshell execution](#tool-bridges-and-subshell-execution)
+ - [Human-in-the-loop and git confirmation](#human-in-the-loop-and-git-confirmation)
+ - [Multi-model routing and model floors](#multi-model-routing-and-model-floors)
+ - [Architect and editor model split](#architect-and-editor-model-split)
+ - [Local LLM connectivity (Ollama / vLLM)](#local-llm-connectivity-ollama--vllm)
+ - [Clean-environment wrapper and isolation](#clean-environment-wrapper-and-isolation)
+ - [Verify](#verify)
+ - [See also](#see-also)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Aider agent harness
+
+**Capability:** capability:platform
+
+**Harness:** Aider (aider.chat)
+
+[Aider](https://aider.chat/) is an open-source (Apache 2.0 licensed), model-agnostic terminal pair programming agent harness.
+This guide documents how Aider operates as an agent harness for Apache Magpie for [#317](https://github.com/apache/magpie/issues/317).
+Grounding is established by [RFC-AI-0004 Principle 3 (Vendor Neutrality)](../rfcs/RFC-AI-0004.md), which guarantees that Magpie adopters can drive all framework workflows using fully open-source, non-proprietary agent harnesses.
+
+Aider provides an open-source execution stack with:
+1. **Model independence:** Native connectivity to Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and local open-weight inference runners (Ollama, llama.cpp, vLLM).
+2. **Git-native pairing:** Tight integration with git working trees and incremental file editing.
+3. **Multi-model tiering:** Built-in `--architect` mode splitting reasoning and code-editing responsibilities across specialized model tiers.
+
+## Harness contract
+
+| Magpie requirement | Aider implementation |
+|---|---|
+| Skill discovery | Aider ingests canonical `.agents/skills/magpie-*/SKILL.md` workflows on demand via `/read` or `--read` (Progressive Disclosure). |
+| Repository instructions | Aider ingests repository instructions from `.aider.conf.yml` or `CONVENTIONS.md` (referencing `AGENTS.md` and adopter instructions from `<project-config>/`). |
+| Tool execution | Aider executes Magpie's language-agnostic `tools/*` CLI bridges via in-session `/run <cmd>` or subshell execution with operator confirmation. |
+| Model Context Protocol (MCP) | Aider does not natively host MCP client servers; deterministic tools execute as language-agnostic CLI scripts under `tools/`. |
+| Human-in-the-loop (HITL) | Prescribed `--no-auto-commits` and `--no-dirty-commits` enforces strict proposal-then-confirm discipline before mutating git state. |
+| Credential & environment isolation | `agent-iso aider` launches the agent through the clean-environment wrapper (Layer 0 isolation, stripping ambient tokens while passing `SSH_AUTH_SOCK`). |
+
+## Invoke a Magpie skill
+
+After running `/magpie-setup` to adopt the repository, the canonical `.agents/skills/` links are active in your working tree.
+Aider discovers and loads these skills directly from the workspace.
+
+### Interactive terminal session
+
+Start an interactive session within the adopted repository:
+
+```bash
+# Launch Aider with filtered environment variables and disabled auto-commits
+source <framework>/tools/agent-isolation/agent-iso.sh
+agent-iso aider --model <model> --no-auto-commits --no-dirty-commits
+```
+
+### Progressive skill disclosure
+
+To prevent context-window exhaustion across Magpie's 70+ workflows, load only the specific skill required for the current task:
+
+```text
+/read .agents/skills/magpie-security-issue-triage/SKILL.md
+```
+
+Inside the session, prompt Aider to execute the workflow:
+
+```text
+Follow the procedure in the loaded SKILL.md to triage inbound report #<issue-number>.
+Adhere strictly to proposal-then-confirm discipline before applying any tracker mutations.
+```
+
+Aider reads the loaded `SKILL.md`, checks prerequisites, and presents proposed diagnostic steps before taking action.
+
+### Headless or automated execution
+
+For non-interactive triage passes, automated sweeps, or headless scripting:
+
+```bash
+# Headless run using an explicit instruction text (-m) and target skill file
+aider --model <model> \
+ --read .agents/skills/magpie-list-skills/SKILL.md \
+ --message "Execute the loaded list-skills procedure and summarize available workflows." \
+ --no-auto-commits \
+ --exit
Review Comment:
`--message` already exits after processing the reply, so `--exit` is redundant here.
##########
docs/adapters/aider.md:
##########
@@ -0,0 +1,236 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Aider agent harness](#aider-agent-harness)
+ - [Harness contract](#harness-contract)
+ - [Invoke a Magpie skill](#invoke-a-magpie-skill)
+ - [Interactive terminal session](#interactive-terminal-session)
+ - [Progressive skill disclosure](#progressive-skill-disclosure)
+ - [Headless or automated execution](#headless-or-automated-execution)
+ - [Configuration and repository instructions](#configuration-and-repository-instructions)
+ - [Repository configuration (`.aider.conf.yml`)](#repository-configuration-aiderconfyml)
+ - [Protecting private and local state (`.aiderignore`)](#protecting-private-and-local-state-aiderignore)
+ - [Tool bridges and subshell execution](#tool-bridges-and-subshell-execution)
+ - [Human-in-the-loop and git confirmation](#human-in-the-loop-and-git-confirmation)
+ - [Multi-model routing and model floors](#multi-model-routing-and-model-floors)
+ - [Architect and editor model split](#architect-and-editor-model-split)
+ - [Local LLM connectivity (Ollama / vLLM)](#local-llm-connectivity-ollama--vllm)
+ - [Clean-environment wrapper and isolation](#clean-environment-wrapper-and-isolation)
+ - [Verify](#verify)
+ - [See also](#see-also)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Aider agent harness
+
+**Capability:** capability:platform
+
+**Harness:** Aider (aider.chat)
+
+[Aider](https://aider.chat/) is an open-source (Apache 2.0 licensed), model-agnostic terminal pair programming agent harness.
+This guide documents how Aider operates as an agent harness for Apache Magpie for [#317](https://github.com/apache/magpie/issues/317).
+Grounding is established by [RFC-AI-0004 Principle 3 (Vendor Neutrality)](../rfcs/RFC-AI-0004.md), which guarantees that Magpie adopters can drive all framework workflows using fully open-source, non-proprietary agent harnesses.
+
+Aider provides an open-source execution stack with:
+1. **Model independence:** Native connectivity to Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and local open-weight inference runners (Ollama, llama.cpp, vLLM).
+2. **Git-native pairing:** Tight integration with git working trees and incremental file editing.
+3. **Multi-model tiering:** Built-in `--architect` mode splitting reasoning and code-editing responsibilities across specialized model tiers.
+
+## Harness contract
+
+| Magpie requirement | Aider implementation |
+|---|---|
+| Skill discovery | Aider ingests canonical `.agents/skills/magpie-*/SKILL.md` workflows on demand via `/read` or `--read` (Progressive Disclosure). |
+| Repository instructions | Aider ingests repository instructions from `.aider.conf.yml` or `CONVENTIONS.md` (referencing `AGENTS.md` and adopter instructions from `<project-config>/`). |
+| Tool execution | Aider executes Magpie's language-agnostic `tools/*` CLI bridges via in-session `/run <cmd>` or subshell execution with operator confirmation. |
+| Model Context Protocol (MCP) | Aider does not natively host MCP client servers; deterministic tools execute as language-agnostic CLI scripts under `tools/`. |
+| Human-in-the-loop (HITL) | Prescribed `--no-auto-commits` and `--no-dirty-commits` enforces strict proposal-then-confirm discipline before mutating git state. |
+| Credential & environment isolation | `agent-iso aider` launches the agent through the clean-environment wrapper (Layer 0 isolation, stripping ambient tokens while passing `SSH_AUTH_SOCK`). |
+
+## Invoke a Magpie skill
+
+After running `/magpie-setup` to adopt the repository, the canonical `.agents/skills/` links are active in your working tree.
+Aider discovers and loads these skills directly from the workspace.
+
+### Interactive terminal session
+
+Start an interactive session within the adopted repository:
+
+```bash
+# Launch Aider with filtered environment variables and disabled auto-commits
+source <framework>/tools/agent-isolation/agent-iso.sh
+agent-iso aider --model <model> --no-auto-commits --no-dirty-commits
+```
+
+### Progressive skill disclosure
+
+To prevent context-window exhaustion across Magpie's 70+ workflows, load only the specific skill required for the current task:
+
+```text
+/read .agents/skills/magpie-security-issue-triage/SKILL.md
+```
+
+Inside the session, prompt Aider to execute the workflow:
+
+```text
+Follow the procedure in the loaded SKILL.md to triage inbound report #<issue-number>.
+Adhere strictly to proposal-then-confirm discipline before applying any tracker mutations.
+```
+
+Aider reads the loaded `SKILL.md`, checks prerequisites, and presents proposed diagnostic steps before taking action.
+
+### Headless or automated execution
+
+For non-interactive triage passes, automated sweeps, or headless scripting:
+
+```bash
+# Headless run using an explicit instruction text (-m) and target skill file
+aider --model <model> \
+ --read .agents/skills/magpie-list-skills/SKILL.md \
+ --message "Execute the loaded list-skills procedure and summarize available workflows." \
+ --no-auto-commits \
+ --exit
+```
+
+## Configuration and repository instructions
+
+### Repository configuration (`.aider.conf.yml`)
+
+Configure repository defaults in `.aider.conf.yml` at the repository root to ensure all team members operate under Magpie's safety baseline:
+
+```yaml
+# .aider.conf.yml
+# 1. Enforce Human-in-the-loop confirmation
+auto-commits: false
+dirty-commits: false
+
+# 2. Ingest repository safety instructions
+read:
+ - AGENTS.md
+
+# 3. Model parameters (optional adopter defaults)
+# model: anthropic/claude-3-7-sonnet-20250219
Review Comment:
Same as below: a pinned, already-stale vendor model id. A `<model>` placeholder keeps the sample vendor-neutral.
##########
docs/adapters/aider.md:
##########
@@ -0,0 +1,236 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Aider agent harness](#aider-agent-harness)
+ - [Harness contract](#harness-contract)
+ - [Invoke a Magpie skill](#invoke-a-magpie-skill)
+ - [Interactive terminal session](#interactive-terminal-session)
+ - [Progressive skill disclosure](#progressive-skill-disclosure)
+ - [Headless or automated execution](#headless-or-automated-execution)
+ - [Configuration and repository instructions](#configuration-and-repository-instructions)
+ - [Repository configuration (`.aider.conf.yml`)](#repository-configuration-aiderconfyml)
+ - [Protecting private and local state (`.aiderignore`)](#protecting-private-and-local-state-aiderignore)
+ - [Tool bridges and subshell execution](#tool-bridges-and-subshell-execution)
+ - [Human-in-the-loop and git confirmation](#human-in-the-loop-and-git-confirmation)
+ - [Multi-model routing and model floors](#multi-model-routing-and-model-floors)
+ - [Architect and editor model split](#architect-and-editor-model-split)
+ - [Local LLM connectivity (Ollama / vLLM)](#local-llm-connectivity-ollama--vllm)
+ - [Clean-environment wrapper and isolation](#clean-environment-wrapper-and-isolation)
+ - [Verify](#verify)
+ - [See also](#see-also)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Aider agent harness
+
+**Capability:** capability:platform
+
+**Harness:** Aider (aider.chat)
+
+[Aider](https://aider.chat/) is an open-source (Apache 2.0 licensed), model-agnostic terminal pair programming agent harness.
+This guide documents how Aider operates as an agent harness for Apache Magpie for [#317](https://github.com/apache/magpie/issues/317).
+Grounding is established by [RFC-AI-0004 Principle 3 (Vendor Neutrality)](../rfcs/RFC-AI-0004.md), which guarantees that Magpie adopters can drive all framework workflows using fully open-source, non-proprietary agent harnesses.
+
+Aider provides an open-source execution stack with:
+1. **Model independence:** Native connectivity to Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and local open-weight inference runners (Ollama, llama.cpp, vLLM).
+2. **Git-native pairing:** Tight integration with git working trees and incremental file editing.
+3. **Multi-model tiering:** Built-in `--architect` mode splitting reasoning and code-editing responsibilities across specialized model tiers.
+
+## Harness contract
+
+| Magpie requirement | Aider implementation |
+|---|---|
+| Skill discovery | Aider ingests canonical `.agents/skills/magpie-*/SKILL.md` workflows on demand via `/read` or `--read` (Progressive Disclosure). |
+| Repository instructions | Aider ingests repository instructions from `.aider.conf.yml` or `CONVENTIONS.md` (referencing `AGENTS.md` and adopter instructions from `<project-config>/`). |
+| Tool execution | Aider executes Magpie's language-agnostic `tools/*` CLI bridges via in-session `/run <cmd>` or subshell execution with operator confirmation. |
+| Model Context Protocol (MCP) | Aider does not natively host MCP client servers; deterministic tools execute as language-agnostic CLI scripts under `tools/`. |
+| Human-in-the-loop (HITL) | Prescribed `--no-auto-commits` and `--no-dirty-commits` enforces strict proposal-then-confirm discipline before mutating git state. |
+| Credential & environment isolation | `agent-iso aider` launches the agent through the clean-environment wrapper (Layer 0 isolation, stripping ambient tokens while passing `SSH_AUTH_SOCK`). |
+
+## Invoke a Magpie skill
+
+After running `/magpie-setup` to adopt the repository, the canonical `.agents/skills/` links are active in your working tree.
+Aider discovers and loads these skills directly from the workspace.
+
+### Interactive terminal session
+
+Start an interactive session within the adopted repository:
+
+```bash
+# Launch Aider with filtered environment variables and disabled auto-commits
+source <framework>/tools/agent-isolation/agent-iso.sh
+agent-iso aider --model <model> --no-auto-commits --no-dirty-commits
+```
+
+### Progressive skill disclosure
+
+To prevent context-window exhaustion across Magpie's 70+ workflows, load only the specific skill required for the current task:
+
+```text
+/read .agents/skills/magpie-security-issue-triage/SKILL.md
+```
+
+Inside the session, prompt Aider to execute the workflow:
+
+```text
+Follow the procedure in the loaded SKILL.md to triage inbound report #<issue-number>.
+Adhere strictly to proposal-then-confirm discipline before applying any tracker mutations.
+```
+
+Aider reads the loaded `SKILL.md`, checks prerequisites, and presents proposed diagnostic steps before taking action.
+
+### Headless or automated execution
+
+For non-interactive triage passes, automated sweeps, or headless scripting:
+
+```bash
+# Headless run using an explicit instruction text (-m) and target skill file
+aider --model <model> \
+ --read .agents/skills/magpie-list-skills/SKILL.md \
+ --message "Execute the loaded list-skills procedure and summarize available workflows." \
+ --no-auto-commits \
+ --exit
+```
+
+## Configuration and repository instructions
+
+### Repository configuration (`.aider.conf.yml`)
+
+Configure repository defaults in `.aider.conf.yml` at the repository root to ensure all team members operate under Magpie's safety baseline:
+
+```yaml
+# .aider.conf.yml
+# 1. Enforce Human-in-the-loop confirmation
+auto-commits: false
+dirty-commits: false
+
+# 2. Ingest repository safety instructions
+read:
+ - AGENTS.md
+
+# 3. Model parameters (optional adopter defaults)
+# model: anthropic/claude-3-7-sonnet-20250219
+# edit-format: diff
+```
+
+### Protecting private and local state (`.aiderignore`)
+
+Aider automatically constructs a repository map (repomap) to track codebase structure.
+To prevent Aider from reading private adopter tokens, test fixtures, or local overrides into the prompt context, configure `.aiderignore` at the repository root:
+
+```text
+# .aiderignore
+.apache-magpie-local/
+.env*
+*.key
+*.pem
+.git/
+tools/agent-isolation/tmp/
+```
+
+## Tool bridges and subshell execution
+
+Magpie skills execute deterministic operations via language-agnostic scripts under `tools/` (e.g. `tools/cve-tool-vulnogram/`, `tools/github/`, `tools/privacy-llm/`).
+
+When a skill requires running a tool command:
+- The operator or model proposes the subshell command (e.g. `uv run --project tools/github gh-issue-view ...`).
+- In an interactive session, execute the command directly via `/run <cmd>` or `!<cmd>`.
+- Actions execute in the local project environment following standard subshell semantics.
+
+## Human-in-the-loop and git confirmation
+
+Magpie enforces strict [Human-in-the-Loop principles](../rfcs/RFC-AI-0004.md): no destructive action or git state mutation occurs without explicit human approval.
+
+> [!IMPORTANT]
+> **Aider auto-commit policy:** By default, Aider automatically commits every code modification to git.
+>
+> In Magpie adopted repositories, adopters **must disable auto-commits** either via CLI flags:
+> ```bash
+> aider --no-auto-commits --no-dirty-commits
+> ```
+> or via `.aider.conf.yml`:
+> ```yaml
+> auto-commits: false
+> dirty-commits: false
+> ```
+
+When operating with auto-commits disabled:
+- **Diff review:** Review proposed file changes using `git diff` or in-session `/diff` before staging.
+- **Explicit commit gating:** Use `/commit` only after confirming the change satisfies review criteria.
+- **Write-access discipline:** Outbound communications, issue state changes (`gh issue close`), and remote pushes (`git push`) must always remain gated on explicit human confirmation.
+
+## Multi-model routing and model floors
+
+Aider supports multi-provider model routing, allowing adopters to calibrate model power against task complexity per [docs/mode-economics.md](../mode-economics.md).
+
+### Architect and editor model split
+
+For complex triage and vulnerability assessment, use Aider's `--architect` mode to separate high-level reasoning from code editing:
+
+```bash
+# Reasoning model handles analysis; fast editor applies diffs
+aider --architect \
+ --model anthropic/claude-3-7-sonnet-20250219 \
+ --editor-model anthropic/claude-3-5-haiku-20241022 \
+ --no-auto-commits
+```
+
+### Local LLM connectivity (Ollama / vLLM)
+
+For sovereign or air-gapped deployments where data cannot leave the local host (see [docs/adapters/local-llm.md](local-llm.md)):
+
+```bash
+# Connect Aider to a local Ollama instance
+aider --model ollama/deepseek-r1:70b \
+ --openai-api-base http://localhost:11434/v1 \
Review Comment:
`--openai-api-base` configures the OpenAI provider and has no effect on an `ollama/` model. Aider's Ollama docs use `OLLAMA_API_BASE` and recommend the `ollama_chat/` prefix over `ollama/`:
```suggestion
export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/deepseek-r1:70b \
```
(drop the `--openai-api-base` line below)
##########
docs/adapters/aider.md:
##########
@@ -0,0 +1,236 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Aider agent harness](#aider-agent-harness)
+ - [Harness contract](#harness-contract)
+ - [Invoke a Magpie skill](#invoke-a-magpie-skill)
+ - [Interactive terminal session](#interactive-terminal-session)
+ - [Progressive skill disclosure](#progressive-skill-disclosure)
+ - [Headless or automated execution](#headless-or-automated-execution)
+ - [Configuration and repository instructions](#configuration-and-repository-instructions)
+ - [Repository configuration (`.aider.conf.yml`)](#repository-configuration-aiderconfyml)
+ - [Protecting private and local state (`.aiderignore`)](#protecting-private-and-local-state-aiderignore)
+ - [Tool bridges and subshell execution](#tool-bridges-and-subshell-execution)
+ - [Human-in-the-loop and git confirmation](#human-in-the-loop-and-git-confirmation)
+ - [Multi-model routing and model floors](#multi-model-routing-and-model-floors)
+ - [Architect and editor model split](#architect-and-editor-model-split)
+ - [Local LLM connectivity (Ollama / vLLM)](#local-llm-connectivity-ollama--vllm)
+ - [Clean-environment wrapper and isolation](#clean-environment-wrapper-and-isolation)
+ - [Verify](#verify)
+ - [See also](#see-also)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Aider agent harness
+
+**Capability:** capability:platform
+
+**Harness:** Aider (aider.chat)
+
+[Aider](https://aider.chat/) is an open-source (Apache 2.0 licensed), model-agnostic terminal pair programming agent harness.
+This guide documents how Aider operates as an agent harness for Apache Magpie for [#317](https://github.com/apache/magpie/issues/317).
+Grounding is established by [RFC-AI-0004 Principle 3 (Vendor Neutrality)](../rfcs/RFC-AI-0004.md), which guarantees that Magpie adopters can drive all framework workflows using fully open-source, non-proprietary agent harnesses.
+
+Aider provides an open-source execution stack with:
+1. **Model independence:** Native connectivity to Anthropic Claude, OpenAI GPT, DeepSeek, Google Gemini, OpenRouter, and local open-weight inference runners (Ollama, llama.cpp, vLLM).
+2. **Git-native pairing:** Tight integration with git working trees and incremental file editing.
+3. **Multi-model tiering:** Built-in `--architect` mode splitting reasoning and code-editing responsibilities across specialized model tiers.
+
+## Harness contract
+
+| Magpie requirement | Aider implementation |
+|---|---|
+| Skill discovery | Aider ingests canonical `.agents/skills/magpie-*/SKILL.md` workflows on demand via `/read` or `--read` (Progressive Disclosure). |
+| Repository instructions | Aider ingests repository instructions from `.aider.conf.yml` or `CONVENTIONS.md` (referencing `AGENTS.md` and adopter instructions from `<project-config>/`). |
+| Tool execution | Aider executes Magpie's language-agnostic `tools/*` CLI bridges via in-session `/run <cmd>` or subshell execution with operator confirmation. |
+| Model Context Protocol (MCP) | Aider does not natively host MCP client servers; deterministic tools execute as language-agnostic CLI scripts under `tools/`. |
+| Human-in-the-loop (HITL) | Prescribed `--no-auto-commits` and `--no-dirty-commits` enforces strict proposal-then-confirm discipline before mutating git state. |
+| Credential & environment isolation | `agent-iso aider` launches the agent through the clean-environment wrapper (Layer 0 isolation, stripping ambient tokens while passing `SSH_AUTH_SOCK`). |
+
+## Invoke a Magpie skill
+
+After running `/magpie-setup` to adopt the repository, the canonical `.agents/skills/` links are active in your working tree.
+Aider discovers and loads these skills directly from the workspace.
Review Comment:
This contradicts the on-demand `/read` model two paragraphs down. Aider has no skill discovery; suggest: "Aider does not discover skills on its own; load the one you need with `/read` (see below)."
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat(adapter/aider): Aider agent harness runtime guide [magpie]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk merged PR #1286:
URL: https://github.com/apache/magpie/pull/1286
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat(adapter/aider): Aider agent harness runtime guide [magpie]
Posted by "Kaap10 (via GitHub)" <gi...@apache.org>.
Kaap10 commented on PR #1286:
URL: https://github.com/apache/magpie/pull/1286#issuecomment-5740972899
Thanks for the detailed and constructive review! I've addressed all the requested changes in commit `e6a8c81`:
1. **Tool Invocation**: Replaced the non-existent `uv run --project tools/github...` command with a real CLI invocation (`gh issue view <issue-number> --repo <tracker>`).
2. **Ollama Configuration**: Dropped `--openai-api-base` and configured `export OLLAMA_API_BASE=http://127.0.0.1:11434` with `aider --model ollama_chat/<model> --no-auto-commits`.
3. **Vendor-Neutral Placeholders**: Replaced hardcoded vendor model strings with `<reasoning-model>`, `<editor-model>`, and `<model>`.
4. **Skill Loading Clarity**: Updated skill invocation copy to clearly explain that Aider loads skills on-demand via `/read` or `--read`.
5. **`.aiderignore`**: Removed non-existent `tools/agent-isolation/tmp/` and redundant `.git/`/`.apache-magpie-local/` paths, keeping explicit secret/token patterns.
6. **MCP Client Statement**: Stated plainly that Aider does not include an MCP client.
7. **Redundant Flag**: Dropped `--exit` from the headless `--message` snippet.
8. **Overview Doc (`docs/adapters/README.md`)**: Added Aider and Goose to the harnesses list and the isolation table.
Ready for another look when you have a chance!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org