fix(kiro-ide): ship only IDE-native agent and settings surfaces (#555)

CHANGELOG.md

@@ -1,6 +1,15 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [2.5.13] - 2026-07-25
+
+The Kiro IDE distribution now ships only surfaces Kiro IDE actually reads. Agents ship as Markdown, with the conductor as `.kiro/agents/aidlc.md` so it appears in the IDE's workspace agent selector; the Kiro CLI's agent-v1 JSON configs and `settings/cli.json` are no longer part of this tree, since the IDE reads neither. Delegated agents carry an IDE-native `permissions.rules` block instead of the CLI-only `disallowedTools` field. **Upgrade:** re-copy `dist/kiro-ide/.kiro/` into your project, then delete the `.kiro/agents/aidlc-*.json`, `.kiro/agents/aidlc.json`, and `.kiro/settings/cli.json` files a previous install left behind — a content-copy leaves them in place, and while the IDE ignores them, `--doctor` keeps checking for `settings/cli.json` as long as `agents/aidlc.json` is still there. Kiro CLI (`dist/kiro/`) is unchanged.
+
+* Kiro IDE agents ship as Markdown only: the 14 personas as `.kiro/agents/aidlc-*-agent.md` and the conductor as `.kiro/agents/aidlc.md` (the entry the IDE's workspace agent selector loads). The 15 agent-v1 JSON files and `settings/cli.json` are dropped from this distribution.
+* Each delegation-target persona now carries a `permissions.rules` block (shell `bun .kiro/tools/aidlc-*`/`date -u *`, filesystem `aidlc/spaces/**`; the composer gets `.kiro/scopes/**` + the scope grid) alongside its existing `tools:` grant, and no longer carries `disallowedTools` — a Claude Code field the IDE does not recognize. The IDE has no `allowedCommands`/`allowedPaths` equivalent, so this capability/effect/match block is where a delegate's scoping lives.
+* `/aidlc --doctor` accepts either `agents/aidlc.json` or `agents/aidlc.md` as the conductor agent's hook + permission wiring, and runs the `settings/cli.json` row only on a CLI install (one where `agents/aidlc.json` is present) — an IDE install no longer fails a check for a CLI-only file it does not ship.
+* Docs updated for the IDE's real surfaces (`docs/guide/harnesses/kiro-ide.md`, `docs/reference/14-claude-features.md`). No command or flag changes; no breaking change for CI or scripts.
+
 ## [2.5.11] - 2026-07-24
 
 Intent Capture now keeps generated intent and stakeholder claims grounded in the user's description, confirmed answers, workflow-selected scope, or explicitly registered memory. Unsupported content is omitted, elicited, or surfaced as a human-owned assumption instead of being presented as fact. **Upgrade:** re-copy your `dist/<harness>/` shell into the project so the updated stage, Product Lead reviewer contract, and `claim-sources` sensor are installed.

README.md

@@ -11,7 +11,7 @@ A native implementation of the **AI-DLC methodology** (AI-Driven Development Lif
 
 The methodology lives once, in a harness-neutral `core/`; each harness adds a thin surface that decides how it shows up on that harness. So you edit the methodology in one place, and every harness distribution is generated from it — no harness gets special treatment. (See [Repository layout](#repository-layout) for how the pieces fit together.)
 
-![version](https://img.shields.io/badge/version-2.5.11-blue)
+![version](https://img.shields.io/badge/version-2.5.13-blue)
 ![license](https://img.shields.io/badge/license-MIT--0-green)
 ![Kiro IDE](https://img.shields.io/badge/harness-Kiro%20IDE-orange)
 ![Kiro CLI](https://img.shields.io/badge/harness-Kiro%20CLI-orange)
@@ -128,7 +128,7 @@ cp dist/kiro-ide/AGENTS.md your-project/AGENTS.md   # merge if you already have
 
 The `aidlc/` shell ships the pre-built `aidlc/spaces/default/memory/` method tree the engine reads; `/aidlc --doctor` fails its "workspace shell ready" check without it.
 
-Open `your-project/` in Kiro IDE. The `/aidlc` command loads the shipped conductor skill (the bundled `.kiro/settings/cli.json` is a Kiro CLI-only compatibility surface — the IDE ignores it and does not select a default agent from it). The install registers the framework hooks in both formats: `.kiro/hooks/aidlc-*.json` (v2 schema for IDE >= 1.0) and `.kiro/hooks/aidlc-*.kiro.hook` (legacy format for pre-1.0 IDEs). In the chat panel, run `/aidlc --doctor` to verify, then `/aidlc <description>` to start.
+Open `your-project/` in Kiro IDE. The `/aidlc` command loads the shipped conductor skill; the IDE activates its agent from the workspace agent selector, so this distribution ships no `settings/cli.json` (that file is the Kiro CLI's default-agent activation surface and stays in `dist/kiro/`). The install registers the framework hooks in both formats: `.kiro/hooks/aidlc-*.json` (v2 schema for IDE >= 1.0) and `.kiro/hooks/aidlc-*.kiro.hook` (legacy format for pre-1.0 IDEs). In the chat panel, run `/aidlc --doctor` to verify, then `/aidlc <description>` to start.
 
 > [!NOTE]
 > AI-DLC on Kiro works best with **Claude Opus 4.8**, which requires a **paid Kiro plan**. On weaker models the conductor may skip optional stage steps (reviewer pass, learnings ritual) or rush approval gates.

core/tools/aidlc-lib.ts

@@ -3926,7 +3926,14 @@ export function loadAgents(): AgentMetadata[] {
     const dir = agentsDir();
     const slugToFile = new Map<string, string>();
     const agents: AgentMetadata[] = [];
-    const files = readdirSync(dir).filter((f) => f.endsWith(".md")).sort();
+    // aidlc.md is the conductor MAIN (IDE custom-agent selector entry), not a
+    // stage lead/support agent — it carries no name/display_name/examples and
+    // must not enter the domain-agent roster (it would fail schema validation
+    // and pollute knownAgents used for stage lead_agent checks). Exclude it.
+    // No-op for harnesses that ship no aidlc.md (every tree but the Kiro IDE).
+    const files = readdirSync(dir)
+      .filter((f) => f.endsWith(".md") && f !== "aidlc.md")
+      .sort();
     for (const f of files) {
       const filePath = join(dir, f);
       const agent = parseAgentFrontmatter(filePath);

core/tools/aidlc-utility.ts

@@ -1239,18 +1239,29 @@ function handleDoctor(projectDir: string, flags: Record<string, string> = {}): v
   // permissions live there) plus settings/cli.json (activation). Codex CLI:
   // config.toml + hooks.json (the hook wiring) + rules/default.rules (permissions).
   if (harness === ".kiro") {
-    const agentPath = join(projectDir, harness, "agents", "aidlc.json");
+    // The conductor agent config carries the hook + permission wiring. Kiro CLI
+    // ships it as agents/aidlc.json; Kiro IDE reads the Markdown agent format
+    // (agents/aidlc.md) instead — either satisfies the wiring requirement, so
+    // accept whichever is present.
+    const jsonAgentPath = join(projectDir, harness, "agents", "aidlc.json");
+    const mdAgentPath = join(projectDir, harness, "agents", "aidlc.md");
     results.push({
-      pass: existsSync(agentPath),
-      label: "agents/aidlc.json present (hook + permission wiring)",
-      fix: "copy from `dist/kiro/.kiro/agents/aidlc.json`",
-    });
-    const cliSettingsPath = join(projectDir, harness, "settings", "cli.json");
-    results.push({
-      pass: existsSync(cliSettingsPath),
-      label: "settings/cli.json present (workspace default-agent activation)",
-      fix: "copy from `dist/kiro/.kiro/settings/cli.json` (or use `kiro-cli chat --agent aidlc`)",
+      pass: existsSync(jsonAgentPath) || existsSync(mdAgentPath),
+      label: "agents/aidlc.{json,md} present (hook + permission wiring)",
+      fix: "copy from `dist/kiro/.kiro/agents/aidlc.json` (Kiro CLI) or `dist/kiro-ide/.kiro/agents/aidlc.md` (Kiro IDE)",
     });
+    // settings/cli.json activates the default agent for Kiro CLI only. Kiro IDE
+    // activates via the agent selector and ships no settings file, so this check
+    // applies solely to a CLI install (aidlc.json present). Skip it for an IDE
+    // install (aidlc.md present, no aidlc.json).
+    if (existsSync(jsonAgentPath)) {
+      const cliSettingsPath = join(projectDir, harness, "settings", "cli.json");
+      results.push({
+        pass: existsSync(cliSettingsPath),
+        label: "settings/cli.json present (workspace default-agent activation)",
+        fix: "copy from `dist/kiro/.kiro/settings/cli.json` (or use `kiro-cli chat --agent aidlc`)",
+      });
+    }
   } else if (harness === ".codex") {
     for (const [file, what, from] of [
       ["config.toml", "model/provider/sandbox config", "dist/codex/.codex/config.toml"],

core/tools/aidlc-version.ts

@@ -1,4 +1,4 @@
 // Hand-edited single source of truth for the AIDLC framework version.
 // Bumped in the same commit that adds the matching ## [N.N.N] heading
 // to CHANGELOG.md. Pinned by tests/unit/t68-version-changelog-sync.test.ts.
-export const AIDLC_VERSION = "2.5.11";
+export const AIDLC_VERSION = "2.5.13";

dist/claude/.claude/tools/aidlc-lib.ts

@@ -3926,7 +3926,14 @@ export function loadAgents(): AgentMetadata[] {
     const dir = agentsDir();
     const slugToFile = new Map<string, string>();
     const agents: AgentMetadata[] = [];
-    const files = readdirSync(dir).filter((f) => f.endsWith(".md")).sort();
+    // aidlc.md is the conductor MAIN (IDE custom-agent selector entry), not a
+    // stage lead/support agent — it carries no name/display_name/examples and
+    // must not enter the domain-agent roster (it would fail schema validation
+    // and pollute knownAgents used for stage lead_agent checks). Exclude it.
+    // No-op for harnesses that ship no aidlc.md (every tree but the Kiro IDE).
+    const files = readdirSync(dir)
+      .filter((f) => f.endsWith(".md") && f !== "aidlc.md")
+      .sort();
     for (const f of files) {
       const filePath = join(dir, f);
       const agent = parseAgentFrontmatter(filePath);

dist/claude/.claude/tools/aidlc-utility.ts

@@ -1239,18 +1239,29 @@ function handleDoctor(projectDir: string, flags: Record<string, string> = {}): v
   // permissions live there) plus settings/cli.json (activation). Codex CLI:
   // config.toml + hooks.json (the hook wiring) + rules/default.rules (permissions).
   if (harness === ".kiro") {
-    const agentPath = join(projectDir, harness, "agents", "aidlc.json");
+    // The conductor agent config carries the hook + permission wiring. Kiro CLI
+    // ships it as agents/aidlc.json; Kiro IDE reads the Markdown agent format
+    // (agents/aidlc.md) instead — either satisfies the wiring requirement, so
+    // accept whichever is present.
+    const jsonAgentPath = join(projectDir, harness, "agents", "aidlc.json");
+    const mdAgentPath = join(projectDir, harness, "agents", "aidlc.md");
     results.push({
-      pass: existsSync(agentPath),
-      label: "agents/aidlc.json present (hook + permission wiring)",
-      fix: "copy from `dist/kiro/.kiro/agents/aidlc.json`",
-    });
-    const cliSettingsPath = join(projectDir, harness, "settings", "cli.json");
-    results.push({
-      pass: existsSync(cliSettingsPath),
-      label: "settings/cli.json present (workspace default-agent activation)",
-      fix: "copy from `dist/kiro/.kiro/settings/cli.json` (or use `kiro-cli chat --agent aidlc`)",
+      pass: existsSync(jsonAgentPath) || existsSync(mdAgentPath),
+      label: "agents/aidlc.{json,md} present (hook + permission wiring)",
+      fix: "copy from `dist/kiro/.kiro/agents/aidlc.json` (Kiro CLI) or `dist/kiro-ide/.kiro/agents/aidlc.md` (Kiro IDE)",
     });
+    // settings/cli.json activates the default agent for Kiro CLI only. Kiro IDE
+    // activates via the agent selector and ships no settings file, so this check
+    // applies solely to a CLI install (aidlc.json present). Skip it for an IDE
+    // install (aidlc.md present, no aidlc.json).
+    if (existsSync(jsonAgentPath)) {
+      const cliSettingsPath = join(projectDir, harness, "settings", "cli.json");
+      results.push({
+        pass: existsSync(cliSettingsPath),
+        label: "settings/cli.json present (workspace default-agent activation)",
+        fix: "copy from `dist/kiro/.kiro/settings/cli.json` (or use `kiro-cli chat --agent aidlc`)",
+      });
+    }
   } else if (harness === ".codex") {
     for (const [file, what, from] of [
       ["config.toml", "model/provider/sandbox config", "dist/codex/.codex/config.toml"],

dist/claude/.claude/tools/aidlc-version.ts

@@ -1,4 +1,4 @@
 // Hand-edited single source of truth for the AIDLC framework version.
 // Bumped in the same commit that adds the matching ## [N.N.N] heading
 // to CHANGELOG.md. Pinned by tests/unit/t68-version-changelog-sync.test.ts.
-export const AIDLC_VERSION = "2.5.11";
+export const AIDLC_VERSION = "2.5.13";

dist/codex/.codex/tools/aidlc-lib.ts

@@ -3926,7 +3926,14 @@ export function loadAgents(): AgentMetadata[] {
     const dir = agentsDir();
     const slugToFile = new Map<string, string>();
     const agents: AgentMetadata[] = [];
-    const files = readdirSync(dir).filter((f) => f.endsWith(".md")).sort();
+    // aidlc.md is the conductor MAIN (IDE custom-agent selector entry), not a
+    // stage lead/support agent — it carries no name/display_name/examples and
+    // must not enter the domain-agent roster (it would fail schema validation
+    // and pollute knownAgents used for stage lead_agent checks). Exclude it.
+    // No-op for harnesses that ship no aidlc.md (every tree but the Kiro IDE).
+    const files = readdirSync(dir)
+      .filter((f) => f.endsWith(".md") && f !== "aidlc.md")
+      .sort();
     for (const f of files) {
       const filePath = join(dir, f);
       const agent = parseAgentFrontmatter(filePath);

dist/codex/.codex/tools/aidlc-utility.ts

@@ -1239,18 +1239,29 @@ function handleDoctor(projectDir: string, flags: Record<string, string> = {}): v
   // permissions live there) plus settings/cli.json (activation). Codex CLI:
   // config.toml + hooks.json (the hook wiring) + rules/default.rules (permissions).
   if (harness === ".kiro") {
-    const agentPath = join(projectDir, harness, "agents", "aidlc.json");
+    // The conductor agent config carries the hook + permission wiring. Kiro CLI
+    // ships it as agents/aidlc.json; Kiro IDE reads the Markdown agent format
+    // (agents/aidlc.md) instead — either satisfies the wiring requirement, so
+    // accept whichever is present.
+    const jsonAgentPath = join(projectDir, harness, "agents", "aidlc.json");
+    const mdAgentPath = join(projectDir, harness, "agents", "aidlc.md");
     results.push({
-      pass: existsSync(agentPath),
-      label: "agents/aidlc.json present (hook + permission wiring)",
-      fix: "copy from `dist/kiro/.kiro/agents/aidlc.json`",
-    });
-    const cliSettingsPath = join(projectDir, harness, "settings", "cli.json");
-    results.push({
-      pass: existsSync(cliSettingsPath),
-      label: "settings/cli.json present (workspace default-agent activation)",
-      fix: "copy from `dist/kiro/.kiro/settings/cli.json` (or use `kiro-cli chat --agent aidlc`)",
+      pass: existsSync(jsonAgentPath) || existsSync(mdAgentPath),
+      label: "agents/aidlc.{json,md} present (hook + permission wiring)",
+      fix: "copy from `dist/kiro/.kiro/agents/aidlc.json` (Kiro CLI) or `dist/kiro-ide/.kiro/agents/aidlc.md` (Kiro IDE)",
     });
+    // settings/cli.json activates the default agent for Kiro CLI only. Kiro IDE
+    // activates via the agent selector and ships no settings file, so this check
+    // applies solely to a CLI install (aidlc.json present). Skip it for an IDE
+    // install (aidlc.md present, no aidlc.json).
+    if (existsSync(jsonAgentPath)) {
+      const cliSettingsPath = join(projectDir, harness, "settings", "cli.json");
+      results.push({
+        pass: existsSync(cliSettingsPath),
+        label: "settings/cli.json present (workspace default-agent activation)",
+        fix: "copy from `dist/kiro/.kiro/settings/cli.json` (or use `kiro-cli chat --agent aidlc`)",
+      });
+    }
   } else if (harness === ".codex") {
     for (const [file, what, from] of [
       ["config.toml", "model/provider/sandbox config", "dist/codex/.codex/config.toml"],

dist/codex/.codex/tools/aidlc-version.ts

@@ -1,4 +1,4 @@
 // Hand-edited single source of truth for the AIDLC framework version.
 // Bumped in the same commit that adds the matching ## [N.N.N] heading
 // to CHANGELOG.md. Pinned by tests/unit/t68-version-changelog-sync.test.ts.
-export const AIDLC_VERSION = "2.5.11";
+export const AIDLC_VERSION = "2.5.13";

dist/kiro-ide/.kiro/agents/aidlc-architect-agent.md

@@ -8,8 +8,18 @@ description: >
   Solutions architect responsible for application design, domain modelling, NFR patterns, and component decomposition.
   Leads Feasibility, Application Design, Units Generation, Functional Design, NFR Requirements, and NFR Design stages,
   and serves as the dispatched final link of the Reverse Engineering pipeline.
-disallowedTools: Task
 tools: ["read", "write", "shell"]
+permissions:
+  rules:
+    - capability: shell
+      effect: allow
+      match:
+        - "bun .kiro/tools/aidlc-*"
+        - "date -u *"
+    - capability: filesystem
+      effect: allow
+      match:
+        - "aidlc/spaces/**"
 ---
 
 **IMPORTANT: Do NOT use the Task tool. You operate as a delegated agent and must not spawn sub-agents.**

dist/kiro-ide/.kiro/agents/aidlc-architecture-reviewer-agent.md

@@ -3,8 +3,18 @@ name: aidlc-architecture-reviewer-agent
 display_name: Architecture Reviewer
 description: >
   Senior solutions architect who reviews technical design artifacts for soundness, implementability, and coherence. Finds broken cross-references, hidden dependencies, unachievable quality targets, and designs that won't survive contact with reality.
-disallowedTools: Task
 tools: ["read", "write", "shell"]
+permissions:
+  rules:
+    - capability: shell
+      effect: allow
+      match:
+        - "bun .kiro/tools/aidlc-*"
+        - "date -u *"
+    - capability: filesystem
+      effect: allow
+      match:
+        - "aidlc/spaces/**"
 ---
 
 **IMPORTANT: Do NOT use the Task tool. You operate as a delegated reviewer and must not spawn sub-agents.**