kyro-ai 3.2.3 → 3.3.1

package/docs/kyro-adapter-architecture-redesign.md

@@ -0,0 +1,987 @@
+# Kyro AI Adapter Architecture Redesign
+
+> Technical baseline, target architecture, and implementation roadmap for Kyro AI's multi-agent adapter system.
+
+Document status: **working technical source of truth for adapter redesign planning**.
+
+Last updated: 2026-06-18.
+
+---
+
+## 1. Purpose
+
+Kyro AI is a portable, markdown-first sprint workflow harness for AI coding agents. Its current CLI already installs a managed runtime, projects command skills, validates package/workspace health, audits artifact integrity, repairs JSON summaries from Markdown evidence, and manages Kyro scopes.
+
+The adapter layer is the weak point. Today it can project a small command-skill surface for Standard, OpenCode, and Codex, but it does not yet model agent detection, native config paths, capabilities, MCP configuration, rollback, or platform-aware installation.
+
+This document defines the technical baseline and target architecture we will use to create implementation plans.
+
+---
+
+## 2. Source Analysis Status
+
+### Verified Against Kyro Source
+
+The Kyro analysis in this document is verified against the local source tree:
+
+- `src/cli/app.ts`
+- `src/cli/options.ts`
+- `src/cli/types.ts`
+- `src/cli/fs.ts`
+- `src/cli/install-plan.ts`
+- `src/cli/state.ts`
+- `src/cli/adapters/*`
+- `src/cli/commands/*`
+- `src/cli/artifacts/*`
+- `README.md`
+- `docs/agent-adapters.md`
+- `docs/cli.md`
+- `package.json`
+
+`npm run build` passes as of this analysis.
+
+### Verified Against Gentle AI Source
+
+Gentle AI was verified locally at:
+
+```text
+/home/joisephdev/rjperaza/externals/ai-projects/gentle-ai
+```
+
+The Gentle AI analysis in this document is verified against:
+
+- `internal/agents/interface.go`
+- `internal/agents/factory.go`
+- `internal/agents/registry.go`
+- `internal/agents/discovery.go`
+- `internal/model/types.go`
+- `internal/pipeline/*`
+- `internal/state/state.go`
+- `internal/system/detect.go`
+- `internal/installcmd/resolver.go`
+- `internal/backup/*`
+- `internal/agents/claude/adapter.go`
+- `internal/agents/opencode/adapter.go`
+- `internal/agents/codex/adapter.go`
+
+Gentle AI currently has 16 adapter implementations under `internal/agents/*/adapter.go`.
+
+---
+
+## 3. Current Kyro Architecture
+
+### Product Shape
+
+Kyro currently ships as an npm package with two bins:
+
+```bash
+kyro
+kyro-ai
+```
+
+Core CLI commands:
+
+| Command | Current behavior |
+|---------|------------------|
+| `kyro` / `kyro tui` | Basic interactive installer menu |
+| `kyro install` | Installs managed runtime and selected adapter projections |
+| `kyro sync` | Refreshes installed adapters from project state, or explicit `--agent` |
+| `kyro doctor` | Validates package versions, assets, project state, runtime, adapters |
+| `kyro doctor --tokens` | Runs progressive-disclosure token budget checks |
+| `kyro doctor --artifacts` | Validates scope state, indexes, summaries, markdown references |
+| `kyro repair` | Rebuilds JSON scope summaries from Markdown evidence |
+| `kyro scope list` | Lists known Kyro scopes |
+| `kyro scope inspect <scope>` | Shows scope state and artifact checks |
+| `kyro scope set-active <scope>` | Updates active scope in project state |
+| `kyro uninstall` | Removes managed adapter blocks and clears installed adapters |
+
+### Runtime Layout
+
+Global runtime:
+
+```text
+~/.agents/
+├── kyro/
+│   ├── versions/{version}/
+│   │   ├── core/
+│   │   │   ├── agents/
+│   │   │   ├── config.json
+│   │   │   └── WORKFLOW.yaml
+│   │   ├── commands/
+│   │   ├── skills/
+│   │   ├── KYRO.md
+│   │   └── manifest.json
+│   └── current -> versions/{version}
+└── skills/
+    ├── kyro-forge/SKILL.md
+    ├── kyro-status/SKILL.md
+    └── kyro-wrap-up/SKILL.md
+```
+
+Project state and artifacts:
+
+```text
+<workspace>/
+└── .agents/
+    └── kyro/
+        ├── kyro.json
+        └── scopes/{scope}/
+            ├── state.json
+            ├── index.json
+            ├── ROADMAP.md
+            ├── ROADMAP.summary.json
+            ├── DEBT.summary.json
+            └── phases/
+```
+
+### Current State Model
+
+`KyroProjectState`:
+
+```typescript
+interface KyroProjectState {
+  schemaVersion: 1;
+  artifactRoot: string;
+  scopes: string[];
+  activeScope: string | null;
+  runtimeVersion: string;
+  runtimePath: string;
+  installedAdapters: KyroInstalledAdapter[];
+}
+```
+
+`KyroManifest`:
+
+```typescript
+interface KyroManifest {
+  schemaVersion: 1;
+  packageName: string;
+  packageVersion: string;
+  installedAt: string;
+  installScope: InstallScope;
+  managedFiles: string[];
+  managedBlocks: string[];
+  adapters: KyroInstalledAdapter[];
+}
+```
+
+Important correction: `mergeProjectState()` does **not** fully clobber installed adapters. It preserves existing adapters by agent and replaces only adapters explicitly passed to the install/sync plan.
+
+---
+
+## 4. Current Adapter System
+
+### Current Agents
+
+| Agent | Current status | Current behavior |
+|-------|----------------|------------------|
+| `standard` | Implemented | Writes global Kyro command skills under `~/.agents/skills/kyro-*` |
+| `opencode` | Implemented | Same projection as `standard`; no OpenCode-native config |
+| `codex` | Implemented | Same command skills plus managed Kyro block in workspace `AGENTS.md` |
+| `claude` | Planned | Stub adapter; CLI install is blocked, plugin packaging remains first-class |
+| `cursor` | Planned | Stub adapter; CLI install is blocked |
+
+Current implementation count: **3 implemented, 2 planned**.
+
+### Current Adapter Contract
+
+```typescript
+interface AdapterDefinition {
+  agent: Agent;
+  displayName: string;
+  status: 'implemented' | 'planned';
+  buildProjection(plan: OperationPlan[]): void;
+  buildManagedFiles(): string[];
+  buildManagedBlocks(): string[];
+  buildInstalledAdapter(scope: InstallScope, installedAt: string): KyroInstalledAdapter;
+  doctor(manifest: KyroManifest | null): CheckResult;
+}
+```
+
+### Current Operation Plan
+
+```typescript
+interface OperationPlan {
+  action: 'write' | 'copy' | 'mkdir' | 'remove' | 'upsert-block' | 'remove-block' | 'symlink';
+  path: string;
+  source?: string;
+  content?: string;
+  blockName?: string;
+}
+```
+
+`applyPlan()` executes operations sequentially with no prepare/apply stages, no backup, no rollback, and no progress callback.
+
+### Current Managed Block Format
+
+Kyro's implemented markers are:
+
+```text
+<!-- kyro-ai:{blockName}:start -->
+...
+<!-- kyro-ai:{blockName}:end -->
+```
+
+The redesign must preserve this marker namespace unless a migration is explicitly planned.
+
+---
+
+## 5. Strengths To Preserve
+
+These are architectural assets, not accidental details:
+
+| Strength | Why it matters |
+|----------|----------------|
+| Markdown-first evidence | Humans and agents can inspect durable workflow state without custom tooling |
+| Progressive disclosure | Agents load command routers, modes, helpers, and templates only as needed |
+| Global runtime plus project state | Runtime can be versioned globally while workspace artifacts remain local |
+| Command-skill projection | Agents get short entrypoints instead of large copied prompts |
+| Managed blocks | Workspace instruction files can be updated idempotently without deleting user content |
+| Token budget audits | Prevents workflow assets from growing beyond practical agent context budgets |
+| Artifact doctor and repair | JSON routing state can be validated and rebuilt from Markdown evidence |
+| Scope lifecycle commands | Operators can inspect and switch active work scopes deterministically |
+| Claude plugin packaging | Claude remains first-class even before a CLI-native Claude adapter exists |
+
+The redesign must not weaken these properties.
+
+---
+
+## 6. What Is Missing
+
+### Adapter Architecture Gaps
+
+| Gap | Current state | Required target |
+|-----|---------------|-----------------|
+| Capability discovery | Only `status: implemented/planned` | Query capabilities like `skills`, `system-prompt`, `mcp`, `commands`, `sub-agents` |
+| Agent detection | User must pass `--agent`, default is `standard` | Filesystem detection by adapter config roots |
+| Native config paths | Not modeled | Each adapter owns config dirs, prompt paths, skills paths, MCP paths |
+| Injection strategy | Hardcoded in `buildProjection()` | Reusable injectors selected by strategy |
+| OpenCode support | Same as Standard | OpenCode-native config support |
+| Codex support | Workspace `AGENTS.md` only | Decide whether to keep workspace block, add `~/.codex`, or support both by scope |
+| Claude CLI adapter | Stub only | CLI-native adapter that complements `.claude-plugin/` |
+| Cursor adapter | Stub only | Cursor-native rules/config adapter |
+| MCP | Not modeled | Strategy-based MCP config writers |
+| Platform install | Not modeled | Optional install command resolution per adapter |
+| Rollback | None | Backup and restore for modified files |
+| Progress reporting | None | Step-level events for CLI/TUI |
+| Adapter tests | None found | Table-driven tests for contract, paths, projections, doctor |
+
+### Operational Gaps
+
+| Gap | Impact |
+|-----|--------|
+| No backup before writing global or workspace config | Failed installs can leave partial state |
+| State writes happen inside same flat plan as file writes | Manifest/project state can be written before later failures |
+| `uninstall` preserves global runtime and command skills | Intentional today, but future uninstall modes must be explicit |
+| `--scope global` is parsed but rejected | Global install semantics need a design before enabling |
+| `doctor` has no adapter inventory mode | Hard to plan or verify adapter migration progress |
+| No integration fixtures for install plans | Refactors can accidentally change installed outputs |
+
+---
+
+## 7. Verified Gentle AI Architecture
+
+Gentle AI's adapter system is a mature reference implementation. Kyro should borrow the architectural patterns, not the product model.
+
+### Adapter Contract
+
+Gentle AI's `agents.Adapter` contains these groups:
+
+| Group | Methods |
+|-------|---------|
+| Identity | `Agent()`, `Tier()` |
+| Detection | `Detect(ctx, homeDir)` |
+| Installation | `SupportsAutoInstall()`, `InstallCommand(profile)` |
+| Config paths | `GlobalConfigDir`, `SystemPromptDir`, `SystemPromptFile`, `SkillsDir`, `SettingsPath`, `MCPConfigPath` |
+| Strategies | `SystemPromptStrategy()`, `MCPStrategy()` |
+| Optional capabilities | output styles, slash commands, sub-agents, skills, system prompt, MCP |
+
+This is the core design rule Kyro should copy: components call adapter methods instead of hardcoding agent-specific behavior in install/sync/doctor.
+
+### Supported Agents
+
+Gentle AI registers 16 adapters:
+
+```text
+claude-code, opencode, kilocode, gemini-cli, cursor, vscode-copilot,
+codex, antigravity, windsurf, kimi, qwen-code, kiro-ide, openclaw,
+pi, trae-ide, hermes
+```
+
+`NewDefaultRegistry()` creates all 16. `NewMVPRegistry()` keeps backward-compatible Claude Code + OpenCode support.
+
+### Strategies
+
+Gentle AI's `SystemPromptStrategy` values:
+
+| Strategy | Purpose |
+|----------|---------|
+| `StrategyMarkdownSections` | Managed marker sections inside an existing file |
+| `StrategyFileReplace` | Own/replace entire prompt file |
+| `StrategyAppendToFile` | Append to existing file |
+| `StrategyInstructionsFile` | Dedicated instruction file |
+| `StrategyJinjaModules` | Kimi-style module files included by a template |
+| `StrategySteeringFile` | Kiro steering file with always-included frontmatter |
+
+Gentle AI's `MCPStrategy` values:
+
+| Strategy | Purpose |
+|----------|---------|
+| `StrategySeparateMCPFiles` | One JSON file per MCP server |
+| `StrategyMergeIntoSettings` | Merge MCP servers into settings JSON |
+| `StrategyMCPConfigFile` | Dedicated `mcp.json` |
+| `StrategyTOMLFile` | TOML config, used by Codex |
+| `StrategyMergeIntoYAML` | YAML merge, used by Hermes |
+
+### Discovery and Backup Roots
+
+`DiscoverInstalled(reg, homeDir)` performs a pure filesystem check over `adapter.GlobalConfigDir(homeDir)`.
+
+`ConfigRootsForBackup(reg, homeDir)` deduplicates discovered config roots. This is directly useful for Kyro's future rollback work: backup target selection should come from adapter paths, not from duplicated install code.
+
+### Pipeline
+
+Gentle AI's pipeline has:
+
+- `StagePrepare`
+- `StageApply`
+- `StageRollback`
+- `Runner`
+- `RollbackPolicy`
+- `ProgressFunc`
+- `StepResult` timestamps and status
+- reverse-order rollback of succeeded apply steps implementing `RollbackStep`
+
+Kyro should copy this shape closely, translated to TypeScript.
+
+### State
+
+Gentle AI persists global state at `~/.gentle-ai/state.json`. Its state preserves:
+
+- installed agents
+- model assignments
+- persona
+- update check timestamp
+- pending sync
+
+`MergeAgents()` deduplicates incremental installs while preserving all other fields. Kyro's project state already preserves adapters similarly, but Kyro still lacks global state for detected agents, pending sync, or persisted global preferences.
+
+### Platform and Install Commands
+
+Gentle AI's `PlatformProfile` includes:
+
+- OS
+- Linux distro
+- package manager
+- npm writability
+- Go availability
+- supported flag
+
+`installcmd.Resolver` centralizes install command resolution for several agents/components. It also performs preflight validation for npm-based agents. Kyro should use a similar resolver module instead of putting platform command logic inside every adapter.
+
+### Concrete Adapter Examples
+
+| Agent | Gentle AI paths/strategies |
+|-------|----------------------------|
+| Claude Code | `~/.claude`, `CLAUDE.md`, skills, commands, agents, output styles, `StrategyMarkdownSections`, `StrategySeparateMCPFiles` |
+| OpenCode | `~/.config/opencode`, `AGENTS.md`, `opencode.json`, commands, skills, `StrategyFileReplace`, `StrategyMergeIntoSettings` |
+| Codex | `~/.codex`, `AGENTS.md`, `config.toml`, skills, `StrategyFileReplace`, `StrategyTOMLFile` |
+
+### Patterns To Adopt
+
+The useful patterns are:
+
+1. **Adapters encapsulate agent-specific knowledge**
+   - Identity
+   - Detection
+   - Config paths
+   - Injection strategies
+   - Capabilities
+   - Optional install commands
+
+2. **Components query adapters rather than switching on agent ID**
+   - This reduces core changes when adding new agents.
+
+3. **Strategies separate "where" from "how"**
+   - Adapter returns paths and strategy identifiers.
+   - Injectors implement marker upsert, file replace, append, JSON merge, TOML merge, etc.
+
+4. **Install execution is staged**
+   - Prepare validates and backs up.
+   - Apply writes changes.
+   - Rollback restores on failure when needed.
+
+5. **Discovery is filesystem-driven**
+   - Registry can detect installed agents by checking known config roots.
+
+6. **State is persistent and mergeable**
+   - Incremental adapter installs should preserve previous selections and user choices.
+
+### What Kyro Should Not Copy Blindly
+
+- Do not replace Kyro's markdown-first workflow model.
+- Do not remove project-local artifacts.
+- Do not make auto-install a prerequisite for adapter support.
+- Do not write into native agent home directories before backup/rollback exists.
+- Do not move Kyro state to `~/.gentle-ai`; Kyro should keep its own `~/.agents/kyro` runtime convention unless we intentionally introduce a separate namespace.
+- Do not copy all 16 agents as an immediate goal; Kyro should first stabilize Standard, OpenCode, Codex, Claude, and Cursor.
+
+---
+
+## 8. Target Adapter Architecture
+
+### Design Principles
+
+1. **Backward-compatible first**
+   - Existing `standard`, `opencode`, and `codex` install output must remain stable until a migration phase explicitly changes it.
+
+2. **Adapters own agent knowledge**
+   - Core install/sync code must not need `if agent === 'codex'` logic for paths or strategies.
+
+3. **Capabilities drive behavior**
+   - A component asks whether an adapter supports a feature before acting.
+
+4. **Strategies perform writes**
+   - Adapters select strategies; injectors implement them.
+
+5. **Plan before apply**
+   - Build a structured plan, print/dry-run it, then execute with rollback once global/native config writes are introduced.
+
+6. **Native config writes require rollback**
+   - Any writes to `~/.codex`, `~/.claude`, `~/.config/opencode`, `~/.cursor`, etc. must be protected by backup.
+
+### Target Types
+
+```typescript
+export type AdapterCapability =
+  | 'command-skills'
+  | 'system-prompt'
+  | 'mcp'
+  | 'slash-commands'
+  | 'sub-agents'
+  | 'output-styles'
+  | 'filesystem-detect'
+  | 'auto-install';
+
+export type SystemPromptStrategy =
+  | 'managed-block'
+  | 'file-replace'
+  | 'append'
+  | 'instructions-file'
+  | 'none';
+
+export type MCPStrategy =
+  | 'separate-files'
+  | 'merge-json-settings'
+  | 'mcp-json-file'
+  | 'toml-file'
+  | 'yaml-merge'
+  | 'none';
+
+export interface DetectionContext {
+  homeDir: string;
+  envPath: string | undefined;
+  platform?: PlatformProfile;
+}
+
+export interface DetectionResult {
+  agent: Agent;
+  installed: boolean;
+  binaryPath: string | null;
+  configFound: boolean;
+  configPath: string | null;
+  detail: string;
+}
+
+export interface AdapterPaths {
+  globalConfigDir?: string;
+  systemPromptPath?: string;
+  skillsDir?: string;
+  commandsDir?: string;
+  settingsPath?: string;
+  mcpConfigPath?: string;
+  subAgentsDir?: string;
+  outputStylesDir?: string;
+}
+
+export interface PlatformProfile {
+  os: 'darwin' | 'linux' | 'windows' | string;
+  linuxDistro?: 'ubuntu' | 'debian' | 'arch' | 'fedora' | 'unknown' | string;
+  packageManager?: 'brew' | 'apt' | 'pacman' | 'dnf' | 'winget' | 'npm' | string;
+  npmWritable: boolean;
+  supported: boolean;
+}
+```
+
+### Target Adapter Interface
+
+```typescript
+export interface Adapter {
+  readonly agent: Agent;
+  readonly displayName: string;
+  readonly status: 'implemented' | 'planned' | 'experimental';
+
+  capabilities(): ReadonlySet<AdapterCapability>;
+  supports(capability: AdapterCapability): boolean;
+
+  paths(homeDir: string): AdapterPaths;
+  detect(context: DetectionContext): DetectionResult;
+
+  systemPromptStrategy(): SystemPromptStrategy;
+  mcpStrategy(): MCPStrategy;
+
+  buildInstallPlan(context: AdapterPlanContext): OperationPlan[];
+  buildUninstallPlan(context: AdapterPlanContext): OperationPlan[];
+  buildInstalledAdapter(scope: InstallScope, installedAt: string): KyroInstalledAdapter;
+
+  doctor(context: AdapterDoctorContext): CheckResult;
+}
+```
+
+Compatibility note: this interface should be introduced alongside the current `AdapterDefinition`, then migrated adapter by adapter. Do not remove the current contract until baseline tests prove output parity.
+
+Implementation note: Gentle AI uses many explicit `SupportsX()` methods. Kyro can use a `capabilities()` set for compactness, but implementation plans should evaluate whether explicit methods are clearer for TypeScript call sites.
+
+### Registry
+
+```typescript
+export class AdapterRegistry {
+  register(adapter: Adapter): void;
+  get(agent: Agent): Adapter;
+  getAll(): Adapter[];
+  getInstallable(): Adapter[];
+  discoverInstalled(context: DetectionContext): DetectionResult[];
+  configRootsForBackup(context: DetectionContext): string[];
+}
+```
+
+Registry requirements:
+
+- Reject duplicate agents.
+- Preserve stable ordering for deterministic plans.
+- Include planned adapters in inventory.
+- Return only implemented/experimental adapters from `getInstallable()`.
+- Deduplicate backup roots from discovered adapter config directories.
+
+---
+
+## 9. Target Injection Strategies
+
+### System Prompt Injectors
+
+| Strategy | Behavior |
+|----------|----------|
+| `managed-block` | Upsert/remove `<!-- kyro-ai:{id}:start -->` blocks while preserving user content |
+| `file-replace` | Own the whole target file; only use when Kyro is meant to control it |
+| `append` | Append a marked section if absent; update if present |
+| `instructions-file` | Write a dedicated instruction/rules file |
+| `none` | Adapter does not manage system prompt |
+
+`managed-block` must use the current `kyro-ai` marker namespace.
+
+### MCP Injectors
+
+| Strategy | Behavior |
+|----------|----------|
+| `separate-files` | One JSON file per MCP server |
+| `merge-json-settings` | Merge into a JSON settings file without deleting unrelated keys |
+| `mcp-json-file` | Manage one dedicated MCP JSON file |
+| `toml-file` | Merge into TOML config |
+| `yaml-merge` | Merge into YAML while preserving unrelated user config |
+| `none` | Adapter does not manage MCP |
+
+MCP should not be implemented before tests exist for JSON/TOML preservation behavior.
+
+YAML merge is not needed for Kyro's near-term target agents, but keeping it in the enum avoids a later contract break if Hermes-like agents are added.
+
+---
+
+## 10. Target Pipeline
+
+### Current Problem
+
+`applyPlan()` writes sequentially. A failure midway can leave:
+
+- project state updated but runtime incomplete
+- symlink changed but files missing
+- managed block written but manifest not matching
+- future native config files partially modified
+
+### Target Execution Model
+
+```typescript
+export type Stage = 'prepare' | 'apply' | 'rollback';
+export type StepStatus = 'pending' | 'running' | 'succeeded' | 'failed';
+
+export interface Step {
+  readonly id: string;
+  readonly description: string;
+  run(): Promise<void>;
+  rollback?(): Promise<void>;
+}
+
+export interface StagePlan {
+  prepare: Step[];
+  apply: Step[];
+}
+
+export interface ProgressEvent {
+  stage: Stage;
+  stepId: string;
+  status: StepStatus;
+  error?: Error;
+}
+```
+
+Pipeline requirements:
+
+- Validate duplicate step IDs before execution.
+- Run all prepare steps before any apply step.
+- Backup every existing file that may be modified.
+- Roll back apply steps in reverse order when configured.
+- Emit progress events for CLI/TUI.
+- Return structured results rather than throwing unstructured partial failures.
+
+Initial migration can keep `OperationPlan` as the planning data model and convert operations into pipeline steps.
+
+---
+
+## 11. Target State Model
+
+### Keep Project State
+
+`KyroProjectState` remains the workspace source of truth for:
+
+- runtime version/path
+- installed adapters for that workspace
+- known scopes
+- active scope
+
+Add only when needed:
+
+```typescript
+lastAdapterSyncAt?: string;
+```
+
+### Add Global State Later
+
+Global state should not be introduced until adapter detection and native config writes exist.
+
+Target:
+
+```typescript
+interface KyroGlobalState {
+  schemaVersion: 1;
+  detectedAgents: Agent[];
+  lastDetectAt?: string;
+  lastSyncAt?: string;
+  pendingSync?: boolean;
+  modelAssignments?: Record<string, unknown>;
+}
+```
+
+Global state location:
+
+```text
+~/.agents/kyro/state.json
+```
+
+Rationale: Kyro already uses `~/.agents/kyro` as its global runtime root, so this avoids introducing a second `~/.kyro` home namespace unless there is a strong reason.
+
+### Add Install Command Resolver Later
+
+Do not spread platform-specific install command logic across adapters. When Kyro adds optional auto-install, add a resolver equivalent to Gentle AI's `installcmd.Resolver`:
+
+```typescript
+interface InstallCommandResolver {
+  resolveAgentInstall(profile: PlatformProfile, agent: Agent): string[][];
+}
+```
+
+Adapters should declare support and identity; the resolver should own package-manager command selection and preflight validation.
+
+---
+
+## 12. Adapter-Specific Target Decisions
+
+### Standard
+
+Purpose: compatibility adapter for agents that can discover `~/.agents/skills`.
+
+Target:
+
+- Keep command-skill projection.
+- No binary detection required.
+- No native system prompt.
+- No MCP.
+- Not auto-installable.
+
+### OpenCode
+
+Current: identical to Standard.
+
+Target:
+
+- Preserve existing command-skill projection for backward compatibility.
+- Add detection for `~/.config/opencode`.
+- Add native config support only after backup/rollback exists.
+- Model OpenCode paths separately from Standard.
+
+Open decision:
+
+- Whether OpenCode should consume Kyro through `~/.agents/skills`, OpenCode-native commands, `AGENTS.md`, or a combination.
+
+### Codex
+
+Current: command skills plus workspace `AGENTS.md` managed block.
+
+Target:
+
+- Preserve workspace `AGENTS.md` behavior initially.
+- Add detection for `~/.codex`.
+- Add optional Codex-native config only in a later migration.
+
+Open decision:
+
+- Should Codex-native support write `~/.codex/AGENTS.md`, `~/.codex/config.toml`, or only workspace `AGENTS.md`?
+- If both are supported, scope semantics must be explicit:
+  - `workspace`: workspace `AGENTS.md`
+  - future `global`: `~/.codex/*`
+
+### Claude
+
+Current: planned CLI adapter, first-class `.claude-plugin/` packaging.
+
+Target:
+
+- Do not treat plugin support as legacy.
+- CLI adapter should complement the plugin, not replace it.
+- Native writes to `~/.claude` require rollback first.
+
+### Cursor
+
+Current: planned stub.
+
+Target:
+
+- Detect Cursor config root.
+- Use an `instructions-file` strategy for rules/instructions if supported.
+- Avoid pretending Cursor is auto-installable unless installation behavior is verified.
+
+---
+
+## 13. Roadmap
+
+### Phase 0: Baseline and Document Alignment
+
+Goal: freeze current behavior and make architecture documentation trustworthy.
+
+Deliverables:
+
+- Update this document as source of truth.
+- Add install-plan regression fixtures for:
+  - `standard`
+  - `opencode`
+  - `codex`
+  - `standard,opencode,codex`
+- Add tests for managed block upsert/remove idempotency.
+- Document current `OperationPlan` behavior.
+- Confirm `npm run build` and `npm run check` expectations.
+
+Verification:
+
+- Build passes.
+- Regression fixtures prove current output shape.
+- No adapter behavior changes.
+
+### Phase 1: Adapter Inventory and Doctor
+
+Goal: expose adapter status without changing install behavior.
+
+Deliverables:
+
+- Add `kyro doctor --adapters`.
+- Report:
+  - agent
+  - display name
+  - status
+  - capabilities known today
+  - managed files
+  - managed blocks
+  - native paths if known
+  - test fixture coverage
+- Add adapter inventory unit tests.
+
+Verification:
+
+- Reports 5 adapters: 3 implemented, 2 planned.
+- Does not require Kyro to be installed in the workspace.
+- Existing `kyro doctor` behavior remains compatible.
+
+### Phase 2: Adapter Contract V2 Behind Compatibility Layer
+
+Goal: introduce the new adapter model without removing the old one.
+
+Deliverables:
+
+- Add `Adapter`, `AdapterRegistry`, capability types, strategy types, path types.
+- Add `configRootsForBackup()` to the registry, modeled after Gentle AI.
+- Implement V2 wrappers for Standard, OpenCode, Codex.
+- Keep current `AdapterDefinition` exports or provide a compatibility adapter.
+- Add duplicate-registration and missing-adapter tests.
+
+Verification:
+
+- Existing install/sync/uninstall outputs remain unchanged.
+- Core code can query capabilities without switching on agent ID.
+
+### Phase 3: Strategy Extraction
+
+Goal: move write semantics out of adapters and into tested injectors.
+
+Deliverables:
+
+- Implement `ManagedBlockInjector` using current `kyro-ai` markers.
+- Implement `FileWriteInjector`.
+- Route existing Codex `AGENTS.md` block through injector logic.
+- Keep command-skill projection as a shared projection module.
+
+Verification:
+
+- Codex output is byte-for-byte compatible with baseline except timestamps where expected.
+- Managed block tests cover create, update, preserve user content, remove, missing block.
+
+### Phase 4: Pipeline and Backup
+
+Goal: make install/sync safe enough for native agent config writes.
+
+Deliverables:
+
+- Convert `OperationPlan` operations into pipeline steps.
+- Add prepare/apply/rollback execution.
+- Add backup store under `~/.agents/kyro/backups/{timestamp}/`.
+- Select backup roots from adapter paths and registry `configRootsForBackup()`.
+- Add progress callback support.
+- Keep dry-run plan output.
+
+Verification:
+
+- Forced apply failure restores modified files.
+- Existing install/sync still pass baseline fixtures.
+- CLI reports useful failure summaries.
+
+### Phase 5: Filesystem Detection
+
+Goal: detect installed agents without requiring `--agent`.
+
+Deliverables:
+
+- Implement detection context and adapter `detect()`.
+- Add `kyro detect`.
+- Add registry discovery tests using temp home directories.
+- Decide no-flag install behavior:
+  - Option A: keep default `standard` for compatibility.
+  - Option B: detect installed agents when config roots exist, fallback to `standard`.
+
+Recommendation: choose Option B only after `kyro detect` has shipped and proven stable.
+
+Verification:
+
+- Detection is pure filesystem/PATH inspection.
+- No subprocess install commands are executed.
+- Nonexistent config dirs return clean "not found" diagnostics.
+
+### Phase 6: Native Adapter Support
+
+Goal: add real native config support per agent.
+
+Order:
+
+1. Codex native support, if global Codex behavior is decided.
+2. OpenCode native support.
+3. Claude CLI adapter while preserving `.claude-plugin/`.
+4. Cursor adapter.
+5. Gemini/Kilo/Windsurf only after the first four establish stable patterns.
+
+Verification:
+
+- Each native adapter has path tests, doctor tests, detection tests, install-plan tests.
+- Native writes are protected by rollback.
+- Existing workspace behavior remains available or has a documented migration.
+
+### Phase 7: MCP and Optional Auto-Install
+
+Goal: add advanced integration after adapter basics are stable.
+
+Deliverables:
+
+- MCP server config model.
+- JSON merge injector.
+- TOML injector only with preservation tests.
+- Optional platform profile detection.
+- Optional install command resolver.
+- Preflight validation for command dependencies such as npm.
+
+Verification:
+
+- MCP add/remove is idempotent.
+- User config keys are preserved.
+- Auto-install commands are printed for confirmation; they are not run implicitly.
+
+---
+
+## 14. Development Planning Template
+
+Every implementation plan derived from this document should include:
+
+1. **Scope**
+   - Exact phase and feature.
+
+2. **Current behavior to preserve**
+   - Reference baseline fixture or command output.
+
+3. **Files expected to change**
+   - Source files.
+   - Docs.
+   - Tests.
+
+4. **Migration risk**
+   - Workspace files touched.
+   - Home-directory files touched.
+   - Whether rollback is required.
+
+5. **Verification**
+   - Unit tests.
+   - Integration/dry-run command.
+   - `npm run build`.
+   - Any doctor/check command.
+
+6. **Rollback story**
+   - For code changes.
+   - For user files modified by the feature.
+
+---
+
+## 15. Non-Negotiable Constraints
+
+- Do not remove `.claude-plugin/` support.
+- Do not remove `standard` until a better compatibility adapter exists.
+- Do not change managed block marker namespace without migration.
+- Do not write native agent home config before backup/rollback exists.
+- Do not introduce MCP writes without preservation tests.
+- Do not make `kyro install` run package-manager install commands implicitly.
+- Do not collapse Markdown artifacts into JSON-only state.
+- Do not break `kyro repair`'s rule: rebuild JSON summaries from Markdown evidence without rewriting Markdown.
+
+---
+
+## 16. Immediate Next PR Recommendation
+
+The next development PR should be **Phase 0 + Phase 1 only**:
+
+1. Add baseline tests/fixtures for current install plans.
+2. Add managed block idempotency tests.
+3. Add `kyro doctor --adapters`.
+4. Keep install/sync/uninstall behavior unchanged.
+
+This creates a stable base for the larger adapter refactor without risking existing users.