[Bug]: The Kiro IDE harness (`harness/kiro-ide/`) ships CLI-format surfaces — JSON agents, `settings/cli.json`, and legacy `.kiro.hook` files — that Kiro IDE 1.0 does not read (agents/settings) or flags for migration (hooks)

[wowzoo]

Summary

dist/kiro-ide/ is nearly a byte-for-byte copy of dist/kiro/ (the CLI harness): it ships JSON agent configs, a settings/cli.json, and .kiro.hook files. But Kiro IDE 1.0 reads a different agent format (Markdown), activates agents differently (selector, not a settings key), and treats the .kiro.hook schema as legacy (migration-prompted). So an IDE install carries surfaces the IDE either ignores or warns about.

I maintain a downstream IDE-format variant and have confirmed each point below against the official IDE docs and a live 1.0.116 run. Filing this to align on scope before a PR.

1. Agents — IDE reads Markdown, not JSON (mismatch, factual)

The IDE custom-agent format is a Markdown file with YAML frontmatter (tools: tags, permissions:/mcpServers: inline); the JSON agent config is the Kiro CLI format. dist/kiro-ide/.kiro/agents/ ships both .md and .json, plus the conductor as aidlc.json:

aidlc.json                            <- CLI conductor config; IDE does not read it
aidlc-architect-agent.json            <- CLI; the IDE reads the .md sibling
aidlc-composer-agent.json
aidlc-developer-agent.json
aidlc-product-lead-agent.json
aidlc-architecture-reviewer-agent.json

On the IDE these .json files are dead weight — the IDE resolves the conductor and every delegated subagent from the .md frontmatter. The IDE-correct shape is: conductor as agents/aidlc.md, and no agent .json at all.

Code that must change when the conductor becomes aidlc.md

Two core checks assume the conductor is aidlc.json, so moving to aidlc.md requires an additive fix (both are otherwise byte-identical for a CLI tree):

• core/tools/aidlc-utility.ts, handleDoctor: the Kiro branch checks agents/aidlc.json for the hook+permission wiring, and unconditionally checks settings/cli.json. On an IDE tree (aidlc.md, no aidlc.json, no settings/) both rows false-fail. Fix: accept agents/aidlc.{json,md}, and gate the settings/cli.json row on a CLI install (aidlc.json present).
• core/tools/aidlc-lib.ts, loadAgents: enumerates agents/*.md. With the conductor shipped as aidlc.md it enters the domain-agent roster, but it carries no name/display_name/examples and is not a stage lead/support agent — it fails agent-schema validation and pollutes the knownAgents set used for stage lead_agent checks. Fix: exclude aidlc.md from the roster.

2. settings/cli.json — CLI activation only (mismatch, factual)

dist/kiro-ide/.kiro/settings/cli.json sets chat.defaultAgent: "aidlc". That key activates the default agent for the Kiro CLI. Kiro IDE activates an agent through the workspace agent selector, not through a settings key, and ships no such file. On an IDE install this file has no effect. The IDE-correct shape drops settings/cli.json.

3. AGENTS.md — install guidance describes the CLI shape (content, not format)

dist/kiro-ide/AGENTS.md is the onboarding doc the IDE user reads. Its Prerequisites/Activation prose describes the CLI activation and agent-JSON wiring rather than the IDE selector + Markdown-agent reality of an IDE install. This is a content accuracy issue, not a file-format one: the doc should describe how the IDE actually loads and activates the workflow.

4. Hooks — works, but .kiro.hook is the legacy schema (opinion / policy)

This one is not broken. dist/kiro-ide/.kiro/hooks/*.kiro.hook uses the older schema:

{"version":"1.0.0","enabled":true,"name":"aidlc-audit-logger","when":{"type":"postToolUse","toolTypes":["write"]},"then":{"type":"runCommand","command":"..."}}

Kiro IDE 1.0 still runs these, but prompts to migrate. The IDE 1.0 documented hook format is:

{"version":"v1","hooks":[{"name":"...","trigger":"PostToolUse","matcher":"...","action":{"type":"command","command":"..."},"enabled":true}]}

(version: v1, a hooks[] array, PascalCase trigger, matcher, action.) On a 1.0.116 run the .kiro.hook files fire but surface a migration prompt.

My opinion: now that the 1.x line has shipped its own hook schema, targeting the 1.x format for the IDE harness is preferable to keeping the legacy schema for backward compatibility — the IDE harness exists to serve IDE 1.x, and a migration prompt on a fresh framework install reads as a defect to the end user. I would convert the IDE harness hooks to the v1 array schema. (This is a maintainer policy call, hence "opinion" rather than a hard bug — happy to defer if backward-compat with pre-1.0 IDE builds is a goal.)

Scope / what I'm proposing

For the IDE harness specifically (harness/kiro-ide/ → dist/kiro-ide/): conductor + persona agents as .md (drop the .json), drop settings/cli.json, correct the AGENTS.md install prose, and (opinion) convert hooks to the v1 array schema. Plus the two additive core checks in §1 so doctor/loadAgents accept the IDE agent shape. The CLI harness (dist/kiro/) is unaffected.

I have a patchset that implements the direction described above and can open a PR if it would help. But since it touches a fair number of files, I'm filing this issue first to align on scope per CONTRIBUTING.

Environment

• Kiro IDE 1.0.116
• AI-DLC v2 2.3.3

[raj-jain-aws]

There will be Kiro IDE pre-v1 users for a long time. v1 is not an auto push upgrade which makes it a longer phase. I think there should be two separate distros of Kiro IDE v1 and pre-v1 (v0?).