Part 15. Agent Replaceability

Agent replaceability is the ability to continue the process with another agent or in another IDE without losing project memory. In SDD, this is a natural goal: if intent is recorded in Markdown files, and the process is structured as skills and commands, the specific agent becomes a replaceable execution environment.

Today you are using Qwen Code CLI. Tomorrow, part of the team may use Codex, Claude Code, Gemini CLI, Cursor, Kiro, or GitHub Spec Kit. The fewer decisions live only in the interface of a single tool, the more resilient the process.

What should be independent of the agent

README.md
QWEN.md / AGENTS.md
specs/
  mission.md
  tech-stack.md
  roadmap.md
  YYYY-MM-DD-feature/
    requirements.md
    plan.md
    validation.md
CHANGELOG.md
tests/
package.json scripts

If these files are clear, another agent will be able to continue the work.

QWEN.md and AGENTS.md

Qwen Code uses QWEN.md, but can also read AGENTS.md. If you want portability, create AGENTS.md as a common contract, and make QWEN.md a thin pointer.

AGENTS.md:

# Agent Instructions

This repository uses SDD.

- Do not implement product features without a feature specification.
- Before planning, read specs/mission.md, specs/tech-stack.md, and specs/roadmap.md.
- Each feature branch must contain specs/YYYY-MM-DD-feature-name/.
- Keep changes within the boundaries of the active specification.
- Before merging, run npm test and npm run typecheck.
- Do not store secrets in the repository.

QWEN.md:

First read @AGENTS.md.
Notes for Qwen Code:
- Use /clear between planning, implementation, and verification.
- Reference specifications via @file.
- Use commands via ! for local verification.

Skill Portability

Qwen Code skills use SKILL.md. This format is similar to a common convention for agent skills: Markdown instructions plus optional scripts and templates. Even if another agent stores skills elsewhere, the content can be migrated.

When migrating:

.qwen/skills/feature-spec/SKILL.md

can be copied to another agent's skills directory and only the tooling details adjusted. The essence of the process remains the same: find the phase in the roadmap, ask for boundaries, decisions, and context, create requirements.md, plan.md, and validation.md.

MCP as an External Tool Layer

MCP allows connecting external tools and data sources. In Qwen Code, MCP is configured in settings.json or via qwen mcp add.

Example of a local MCP via stdio:

{
  "mcpServers": {
    "projectTools": {
      "command": "node",
      "args": ["./tools/mcp-server.js"],
      "timeout": 15000
    }
  }
}

Example command:

qwen mcp add --transport http docs http://localhost:3000/mcp
qwen mcp

Security rule: do not connect MCP "just in case." Each tool expands the agent's action surface.

ACP and IDE

Agent Client Protocol (ACP) is needed so that the agent and client/IDE can interact in a standard way. Qwen Code can work with JetBrains in ACP mode:

{
  "agent_servers": {
    "qwen": {
      "command": "/path/to/qwen",
      "args": ["--acp"],
      "env": {}
    }
  }
}

Even if you use CLI, it is useful to understand the direction: the process should live in the repository, and the interface should be replaceable.

Historical note: in early 2026, JetBrains 2025.3+ switched to ACP v2 (prompt.turn), while Qwen Code supported only v1 for some time, which broke the integration (issue QwenLM/qwen-code#1502). Compatibility was restored in PR #1521 later in 2026. If the JetBrains integration suddenly stops working, the first thing to check is the Qwen Code version and the IDE version: they must speak the same version of ACP.

GitHub Spec Kit as an External SDD Framework

GitHub Spec Kit offers a more formal process: describe intent, plan, break down into tasks, implement. It is not tied to a specific agent and can work with different agents that write code. It is not mandatory to adopt in AgentClinic, but it is useful to know that your manual SDD cycle aligns with the general direction:

intent → specification → plan → tasks → implementation → verification

If the team wants more standardization, you can compare your .qwen/skills/feature-spec with Spec Kit and decide whether a separate framework is needed.

Replaceability Check

Run an experiment:

/clear
Imagine you are a new agent with no chat history.

Read @AGENTS.md, @QWEN.md, @specs/mission.md, @specs/tech-stack.md, and @specs/roadmap.md.
Tell me what the next safe action in the project is.
Do not modify files.

If the answer is correct, the project memory works.

Practice

1. Create AGENTS.md.
2. Make QWEN.md a short file only for Qwen Code.
3. Check that the feature specification skill does not contain unnecessary details tied to Qwen Code.
4. Describe MCP only for tools that are truly needed.
5. Run the "new agent" check.

Review Questions

1. Which artifacts make the process portable?
2. Why is it better not to tie skills to a single interface?
3. When is MCP useful, and when does it only add risk?