spike(framework): define the portability boundary for agent artifacts

Start by reading #619, #916, #913, and #914 alongside the current CLI capabilities, profiles, translators, flat and marketplace builds, and context generators. Exercise the named clean and existing-repository fixtures for Claude Code + Codex, then generalize across selected hosts and record evidence in a compatibility matrix. Done means the matrix, preserve-first and portable-first policy, unresolved uncertainties, and smallest justified follow-up are documented without altering user-owned artifacts.

Problem

When multiple selected hosts natively support the same artifact surface with compatible discovery, format, and semantics, AIDD does not yet have a general policy for reusing one shared artifact and emitting a host-specific projection only when a selected host requires a different contract.

This matters especially when the same repository is used by one person or team with several AI coding hosts. A repository may be opened alternately with Claude Code, Codex, Kilo, Kimi, Cursor, OpenCode, Copilot, or other supported tools. Without a portability boundary, AIDD can generate several representations of the same logical artifact even when a common host-supported surface would be sufficient.

AIDD currently has a canonical plugin source and host-specific translation profiles. Several hosts now converge on shared surfaces such as:

• AGENTS.md
• Agent Skills / SKILL.md
• .agents/skills/
• .agents/agents/

The community also contains emerging proposals and implementations for .agents/rules/. However, unlike Agent Skills, .agents/rules/ does not currently have a broadly adopted cross-host format or discovery contract. It must therefore be investigated as a candidate shared surface, not treated as an established standard.

The current implementation mostly resolves output paths from the selected host profile. It does not yet provide a general policy for discovering existing logical artifacts, reusing compatible project surfaces, or refusing unnecessary duplicates.

The investigation must not assume that .agents/ is a universal standard.

Scope

• Define a portability policy for project instructions, skills, agents/subagents, rules, commands/workflows, and hooks.
• Evaluate repositories used with multiple selected AI coding hosts, not only one host at a time.
• Distinguish a shared artifact consumed by several hosts, a required host-native projection, independent user-authored artifacts, and an accidental AIDD duplicate.
• Define the existing-project invariant: regenerating AIDD must not introduce a second representation of an existing logical artifact unless another selected host requires a semantically distinct projection.
• Preserve user-owned content outside explicit AIDD-managed blocks.
• Refuse to silently merge, delete, migrate, or choose between conflicting existing artifacts.
• Build a host compatibility matrix covering discovery, precedence, format, semantic parity, reuse eligibility, required projections, and evidence.
• Evaluate .agents/rules/ as an emerging community convention and candidate shared surface, without assuming that community adoption equals host support.
• Determine whether any selected host combination can safely use .agents/rules/ directly, through explicit configuration, or not at all.
• Inspect current AIDD CLI capabilities, profiles, translators, flat builds, marketplace builds, and context generators.
• Inspect project-memory behavior when CLAUDE.md, AGENTS.md, and Copilot instruction files coexist.
• Inspect existing skills and agents under host-specific and shared paths.
• Exercise clean/new and existing-repository fixtures with several selected hosts.
• Recommend the smallest follow-up: documentation, extension of an existing issue, resolver design, or separate implementation issue.

Decision boundary

Because this investigation crosses multiple host-specific issues and may define a framework-wide compatibility policy, its scope and outcome should be confirmed by a Maintainer before implementation begins.

This issue does not prescribe ownership or require a particular implementation path. A Maintainer may accept the spike, redirect it to existing issues, split the scope, or close it if the current work already provides sufficient coverage.

Required multi-host scenario

The spike must evaluate a repository used with multiple AI coding hosts selected at the same time.

The minimum scenario is Claude Code + Codex. The analysis must then generalize the result to any supported combination, including combinations such as:

• Claude Code + Codex + Kilo + Kimi;
• Cursor + OpenCode + Copilot;
• any future hosts that consume the same candidate shared surface.

The scenario must cover:

• a new repository with several hosts selected;
• an existing repository with CLAUDE.md only;
• an existing repository with AGENTS.md only;
• an existing repository with both files;
• an existing skill under .claude/skills/;
• an existing skill under .agents/skills/;
• an existing host-native agent and a candidate portable agent;
• a candidate shared rule tree under .agents/rules/.

For each selected host combination, determine whether a common host-supported surface can serve all selected hosts without generating duplicate logical artifacts.

A common or standard surface must be preferred only when discovery, format, and semantics are compatible for every selected host. The existence of a shared convention alone is not sufficient evidence.

For .agents/rules/, the spike must explicitly distinguish:

1. native discovery by every selected host;
2. explicit, documented configuration wiring for each selected host;
3. community or tool-specific support without cross-host parity;
4. no proven support.

The result must identify, for every artifact:

1. one shared artifact serving several selected hosts;
2. a required host-specific projection;
3. two independent user-owned artifacts;
4. an unnecessary duplicate created by AIDD.

The existence of multiple selected hosts must never justify overwriting, merging, deleting, or migrating user-owned artifacts.

Acceptance criteria

• A host compatibility matrix records discovery, format, semantic parity, reuse eligibility, required projections, and evidence links for all relevant selected-host combinations.
• The matrix includes .agents/rules/ as a candidate surface and records whether support is native, explicitly configured, tool-specific, or unproven.
• The multi-host analysis identifies which artifacts can be shared, which require projections, and which existing files must remain untouched.
• Claude's AGENTS.md versus CLAUDE.md precedence and fallback are documented.
• The #619 ownership boundary is preserved: AIDD manages only its explicit block and does not impose global parity on user-owned content.
• The result states whether the gap is absent, documentary, partially covered, or architectural.
• The result defines a preserve-first policy for existing repositories.
• The result defines a portable-first policy for new artifacts only when discovery, format, and semantics are compatible across all selected hosts.
• The result explicitly rejects automatic migration and duplicate creation without demonstrated host need.
• The result explicitly rejects inventing .agents/rules/ as a universal standard without sufficient host evidence.
• The result recommends the smallest justified follow-up.

Prior art in this repo

• #619 — AGENTS.md / CLAUDE.md ownership and parity checks.
• #916 — portable Markdown agents.
• #914 — Kilo-native generation targets.
• #913 — OpenCode config-backed rules.
• #733 — Kimi Code.
• #511 — Antigravity.
• #300 — Zed.
• #677 — provider-specific model pins.
• #859 — multi-CLI shared installation.
• #585 — portable project-policy boundary.
• #793 — project context architecture and ownership.
• Agent Skills specification.
• Claude Code memory and AGENTS.md documentation.
• Community RFC for .agents/rules/.
• Tarsk .agents/rules/ documentation.
• Chromium .agents/rules/ example.
• AIR vendor-neutral repository convention.

Out of scope

• Moving all artifacts under .agents/.
• Inventing .agents/rules/ as a universal AIDD standard before the spike establishes sufficient host support.
• Automatic migration of CLAUDE.md, skills, agents, or rules.
• Global synchronization of CLAUDE.md and AGENTS.md.
• Deleting or merging user-owned artifacts.
• Replacing #916, #913, or #914.
• Implementing a new CLI abstraction before the spike establishes the contract.

QA

• Verify the matrix against current official host documentation.
• Inspect current main and all related issues and PRs.
• Inspect community evidence for .agents/rules/ and distinguish proposals, implementations, and host-native contracts.
• Exercise clean/new and existing-repository fixtures across multiple selected-host combinations.
• Confirm that no unnecessary logical duplicate is created.
• Confirm that required host-native projections remain available.
• Record evidence, host versions, exact paths, community sources, and unresolved uncertainties.