kyro-ai 3.3.1 → 3.3.2

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

@@ -1,987 +0,0 @@
-# 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.