chore(kiro): refresh mirror to latest Kiro CLI features (v1.3.0)

.claude-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "ERPAVal — autonomous software development workflow for Claude Code.",
-    "version": "1.2.0"
+    "version": "1.3.0"
   },
   "plugins": [
     {
       "name": "erpaval",
       "source": "./",
       "description": "Six-phase Explore/Research/Plan/Act/Validate/Compound workflow with classifier-driven routing and a compounding lessons store.",
-      "version": "1.2.0",
+      "version": "1.3.0",
       "author": { "name": "Laith Al-Saadoon" },
       "homepage": "https://github.com/theagenticguy/erpaval",
       "repository": "https://github.com/theagenticguy/erpaval",

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "erpaval",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "ERPAVal — autonomous software development workflow for Claude Code. Comprehensive standalone bundle: the erpaval workflow plus 10 vendored companion skills (product-discovery, research, ultraplan, tech-stack-builder, product-strategy, working-backwards, customer-research, meta-prompt-optimizer, product-design-shared, agent-ux-patterns) so the six-phase Explore/Research/Plan/Act/Validate/Compound loop routes resolve out of the box. Designed to be forked.",
   "author": {
     "name": "Laith Al-Saadoon"

.erpaval/solutions/api-patterns/kiro-cli-port-playbook.md

@@ -21,8 +21,10 @@ pattern: |
   - Hook events: SessionStart→agentSpawn, PostToolUse→postToolUse, Stop→stop,
     PreToolUse→preToolUse, UserPromptSubmit→userPromptSubmit
   - Subagents: `.kiro/agents/<n>.json` + `subagent` built-in tool, max 4 parallel
-  - Tools: fs_read↔Read, fs_write↔Write+Edit, execute_bash↔Bash, glob↔Glob,
-    grep↔Grep, web_fetch↔WebFetch, web_search↔WebSearch
+  - Tools (emit the canonical Kiro names; `fs_*`/`execute_bash`/`use_aws` are
+    deprecated Q-era aliases that still resolve): read↔Read, write↔Write+Edit,
+    shell↔Bash, aws↔(no CC equiv), glob↔Glob, grep↔Grep, web_fetch↔WebFetch,
+    web_search↔WebSearch
 
   ### Folder renames (3 of them)
   - `templates/` → `assets/`
@@ -46,8 +48,11 @@ pattern: |
     to act. Acceptable degradation.
   - Task dependencies: Kiro `/todo` lacks `addBlockedBy` / status workflow.
     Use filesystem state in task packets as authoritative, `/todo` for UI mirror.
-  - `Edit` tool: Kiro has no separate Edit. `fs_write` overwrites. Hook matchers
-    target `fs_write` only.
+  - `Edit` tool: Kiro has no separate Edit. The `write` tool overwrites. Hook
+    matchers target `write` only.
+  - `postToolUse` cannot block: a `postToolUse` validation hook can only warn,
+    not reject a write. For hard rejection, move the check to `preToolUse` +
+    exit code 2 (Kiro's single blocking path).
   - SessionEnd / SubagentStop / PreCompact / Notification hooks: not present
     in Kiro. erpaval doesn't use them, so no shim needed.
 

.erpaval/solutions/best-practices/kiro-subagent-vs-spawn-summary-return-path.md

@@ -39,9 +39,14 @@ pattern: |
     can return to later."*
   - **Not for orchestrator-driven delegation.**
 
-  ### Failure mode: silent "No result"
-  Symptoms: a subagent dispatch returns `Pipeline completed ... No result`
-  or an empty summary, even though the configs look correct.
+  ### Failure mode: silent empty / "No result"
+  Symptoms: a subagent dispatch returns an empty summary (observed as
+  `Pipeline completed ... No result` in practice), even though the configs
+  look correct. NOTE: the literal string "No result" is an empirical
+  observation, not documented in current kiro.dev docs (the Q ancestor used
+  "Summary unavailable - see full details in agent execution file"), and may
+  vary by Kiro version. Don't pattern-match on the exact string — treat any
+  empty/missing summary as this failure class. The fix is the same regardless.
 
   Common causes:
   1. **Subagent finished without calling `summary`.** The summary tool is
@@ -81,7 +86,7 @@ pattern: |
   And on each subagent:
   ```json
   {
-    "tools": ["fs_read", "grep", "glob", "execute_bash", "..."],
+    "tools": ["read", "grep", "glob", "shell", "..."],
     "allowedTools": ["*"]
   }
   ```

.gitignore

@@ -3,3 +3,4 @@ __pycache__/
 *.pyo
 .DS_Store
 .erpaval/sessions/
+research/

CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 1.3.0 — 2026-05-29 · Kiro mirror refresh (latest CLI)
+
+Refresh of the `kiro/` Claude Code → Kiro CLI port to track the latest
+Kiro CLI features, backed by a `/research` pass over kiro.dev docs
+(captured findings: fan-out, hooks, subagents, agent-config surface as
+of 2026-05-29).
+
+- Modernized built-in tool names across all three agent JSONs and every
+  hook matcher: `fs_read`→`read`, `fs_write`→`write`,
+  `execute_bash`→`shell`, `use_aws`→`aws`. The Q-era aliases still
+  resolve, but the canonical names are forward-safe. The
+  `kiro_validate_packet.py` runtime check accepts both spellings.
+- Dropped the experimental `delegate` tool from the orchestrator and
+  researcher agents — Kiro is replacing it with the official `subagent`
+  tool (already wired).
+- `postToolUse` packet validation documented as **advisory** — Kiro
+  `postToolUse` cannot block, so a malformed `.erpaval/` packet is
+  warned, not rejected (move to `preToolUse` + exit 2 for hard
+  rejection). Updated KIRO-COMPATIBILITY, AGENTS, SKILL mirror, and
+  context-packets to match.
+- Orchestrator prompt adopts the latest subagent patterns: the 4-per-
+  DAG-level concurrency cap, v2.5.0 in-pipeline review loops for the
+  Act→Validate→re-Act cycle, and v2.3 `$AGENT_DISPLAY_OUT` /
+  `$AGENT_CONTEXT_OUT` progress side-channels (alongside `wc -l` /
+  Ctrl+G monitoring).
+- KIRO-COMPATIBILITY headline + hook table rewritten for the nuanced
+  capability map (shell-only hooks, single blocking path, prompt-based
+  hooks gap), with a dated "re-check the changelog" caveat and a
+  `KIRO_HOME` note.
+- Corrected two lessons-store assumptions: the literal "No result"
+  subagent string is an empirical observation, not documented (don't
+  pattern-match on it); `/spawn --name` labels the session, not an agent
+  (already reflected in the runbook).
+- Synced `kiro/install.sh` `ERPAVAL_VERSION` (was stranded at 1.1.1).
+- Bump 1.2.0 → 1.3.0 (plugin.json + marketplace.json + install.sh).
+
 ## 1.2.0 — 2026-05-29 · fan-out + grounding sync
 
 Sync of the upstream `erpaval` and `product-discovery` skills, porting

kiro/AGENTS.md

@@ -50,7 +50,9 @@ kiro-cli chat --agent erpaval-orchestrator --trust-all-tools
 `--trust-all-tools` auto-approves every tool call so subagents can write,
 shell out, and call MCP servers without prompting. For unattended runs add
 `--no-interactive` and set `KIRO_API_KEY`. For least-privilege scoping use
-`--trust-tools=read,grep,glob,write,execute_bash` instead.
+`--trust-tools=read,grep,glob,write,shell` instead. (Trusted-command matching
+is a prefix string match, so prefer scoped `allowedTools` + `toolsSettings` in
+the agent JSON over a blanket `--trust-all-tools` for anything beyond dev/test.)
 
 All three agents pin `model: claude-opus-4-7`. Override per-invocation with
 `--model <id>` or edit the JSONs.
@@ -67,7 +69,7 @@ relative to it. This is the Kiro-distribution analogue of Claude Code's
 Three of Kiro's five hook events are wired (per the orchestrator agent JSON):
 
 - `agentSpawn` → `kiro_session_start_bootstrap.py` — emits prior-lesson summary on session start
-- `postToolUse` (matcher: `fs_write`) → `kiro_validate_packet.py` — Pydantic schema check on `.erpaval/` writes
+- `postToolUse` (matcher: `write`) → `kiro_validate_packet.py` — **advisory** Pydantic schema check on `.erpaval/` writes; Kiro `postToolUse` cannot block, so a malformed packet is warned, not rejected (move to `preToolUse` + exit 2 if hard rejection is ever needed)
 - `stop` → `kiro_compound_nudge.py` — **advisory only**; Kiro stop hooks cannot block-and-re-prompt the agent the way Claude Code's `Stop` channel does
 
 All hooks are fail-open (`framework.run_hook` catches exceptions and exits 0).

kiro/KIRO-COMPATIBILITY.md

@@ -5,16 +5,27 @@ gap shims, and migration playbook.
 
 ## Headline
 
-Three of erpaval's primitives are 1:1 with Kiro: Skills (the open Agent
-Skills standard), MCP, and the three hook events erpaval uses. Six gaps
-exist. All have shipped shims documented below.
-
-The 1:1 hook mapping is: `SessionStart` → `agentSpawn`, `PostToolUse` →
-`postToolUse`, `Stop` → `stop`.
-
-The six gaps are: `${CLAUDE_PLUGIN_ROOT}` env var, plugin manifest, plugin
-namespacing, Stop-hook re-prompt channel, built-in `Explore` subagent, and
-`addBlockedBy` task deps.
+Two of erpaval's primitives are clean 1:1 with Kiro: Skills (the open Agent
+Skills standard) and MCP. Subagents map closely (the `subagent` tool, the 4-per-
+DAG-level cap, the `summary` return channel). Hooks map by event name but
+**lose capability**: Kiro hooks are shell-only (no prompt-based hooks), only
+`preToolUse` can block (via exit code 2), and `postToolUse`/`stop` are
+advisory. All gaps have shipped shims documented below.
+
+The hook event mapping is: `SessionStart` → `agentSpawn` (1:1),
+`UserPromptSubmit` → `userPromptSubmit` (1:1), `PreToolUse` → `preToolUse`
+(block via exit 2 only), `PostToolUse` → `postToolUse` (cannot block —
+packet validation is advisory), `Stop` → `stop` (advisory channel).
+
+The gaps are: `${CLAUDE_PLUGIN_ROOT}` env var, plugin manifest, plugin
+namespacing, prompt-based hooks, blocking `PostToolUse`/`Stop` channels,
+built-in `Explore` subagent, and `addBlockedBy` task deps. Four Claude Code
+hook events — `SessionEnd`, `SubagentStop`, `PreCompact`, `Notification` —
+have no Kiro equivalent (erpaval uses none of them).
+
+> Verified against Kiro CLI docs as of 2026-05-29. Kiro CLI is on a fast
+> minor-version cadence (v2.2 → v2.5 in May 2026 alone) — re-check
+> [kiro.dev/changelog](https://kiro.dev/changelog/) before each refresh.
 
 ## Capability mapping
 
@@ -41,15 +52,17 @@ namespacing, Stop-hook re-prompt channel, built-in `Explore` subagent, and
 
 ### Hooks
 
-| Capability                                         | Status                 |
-| -------------------------------------------------- | ---------------------- |
-| SessionStart → agentSpawn                          | 1:1                    |
-| PostToolUse → postToolUse                          | 1:1                    |
-| Stop → stop                                        | 1:1, channel-different |
-| PreToolUse, UserPromptSubmit                       | 1:1                    |
-| SessionEnd, SubagentStop, PreCompact, Notification | gap, unused by erpaval |
-| Hook config location                               | partial                |
-| Plugin-root env var                                | gap, shimmed           |
+| Capability                                         | Status                  |
+| -------------------------------------------------- | ----------------------- |
+| SessionStart → agentSpawn                          | 1:1                     |
+| PostToolUse → postToolUse                          | partial, cannot block   |
+| Stop → stop                                        | partial, advisory only  |
+| PreToolUse → preToolUse                            | partial, exit-2 only    |
+| UserPromptSubmit → userPromptSubmit                | 1:1                     |
+| SessionEnd, SubagentStop, PreCompact, Notification | gap, unused by erpaval  |
+| Hook config location                               | inline in agent JSON    |
+| Hook trigger model (prompt-based hooks)            | gap, shell-only on Kiro |
+| Plugin-root env var                                | gap, shimmed            |
 
 ### MCP
 
@@ -157,9 +170,10 @@ This is the cost of a softer channel.
 
 Claude Code provides a built-in read-only Explore subagent. Kiro does not.
 `kiro/agents/erpaval-explorer.json` ships a custom agent with read-only
-tools (`read`, `grep`, `glob`, `execute_bash` with a deny list for
-destructive commands) and a system prompt that mirrors Claude Code's Explore
-behavior.
+tools (`read`, `grep`, `glob`, `shell` with a deny list for destructive
+commands) and a system prompt that mirrors Claude Code's Explore behavior.
+Kiro's read-only **Plan Agent** (`/plan`, v1.23.0) is an alternative for
+structured read-only planning.
 
 ### `addBlockedBy` task dependencies
 
@@ -171,10 +185,26 @@ progress only. The packets remain the source of truth.
 
 ### `Edit` tool separate from `Write`
 
-Kiro has no separate `Edit` tool. `fs_write` overwrites. Hook matchers
-target `fs_write` only, not `Write|Edit|MultiEdit` like Claude Code. Skills
-that document file edits use `fs_write` semantics: rewrite the file with
-the new content.
+Kiro has no separate `Edit` tool — the `write` tool (canonical name; `fs_write`
+is the deprecated Q-era alias) overwrites. Hook matchers target `write` only,
+not `Write|Edit|MultiEdit` like Claude Code. Skills that document file edits
+use `write` semantics: rewrite the file with the new content.
+
+> Tool-name modernization: this distribution emits the current canonical
+> built-in names (`read`, `write`, `shell`, `aws`) in every agent JSON and hook
+> matcher, not the deprecated Q-era aliases (`fs_read`, `fs_write`,
+> `execute_bash`, `use_aws`). The old names still resolve as aliases, but the
+> canonical names are forward-safe.
+
+### `postToolUse` cannot block — packet validation is advisory
+
+Claude Code's `PostToolUse` hook can reject a write. Kiro's `postToolUse`
+**cannot block** — any non-zero exit surfaces a warning but the write stands.
+`kiro_validate_packet.py` therefore runs as an advisory schema check: it warns
+on a malformed `.erpaval/` packet but does not reject it. If hard rejection is
+ever required, move the check to `preToolUse` on `write` and return exit code 2
+(the single blocking path in Kiro's hook model). The fail-open design is
+unchanged — `framework.run_hook` still catches exceptions and exits 0.
 
 ## Migration playbook
 
@@ -185,7 +215,8 @@ If you fork this plugin and want to maintain both distributions:
 2. Mirror updates into `kiro/skills/erpaval/` with the documented surface
    rewrites. `${CLAUDE_PLUGIN_ROOT}` becomes `${ERPAVAL_HOME}`. `templates/`
    becomes `assets/`. `tools/` becomes `scripts/`. Task tool refs become
-   filesystem state plus `/todo`.
+   filesystem state plus `/todo`. Built-in tool names use the canonical
+   forms (`read`/`write`/`shell`/`aws`), not the Q-era aliases.
 3. Run `bash kiro/install.sh --dry-run` to verify the install path.
 4. Install into a workspace `.kiro/` and run `kiro-cli chat --agent
    erpaval-orchestrator`.
@@ -198,7 +229,11 @@ by reading `skills/` and emitting `kiro/skills/`.
 Kiro's documented agent JSON schema does not specify `${VAR}` interpolation
 on field values. The installer sidesteps this by `sed`-substituting at
 install time. If Kiro ever adds first-class env-var expansion, the JSONs
-can be shipped verbatim.
+can be shipped verbatim. (Kiro's `mcp.json` *does* expand `${VAR}` in `env`
+and `headers`; agent-JSON field values do not, which is why `${ERPAVAL_HOME}`
+is resolved at install time, not by Kiro.) To relocate the whole Kiro home,
+Kiro honors `KIRO_HOME` (v2.3.0) — the installer's `--workspace`/default
+target is the analogue here.
 
 `kiro-cli` does not have a `kiro install` subcommand. Install is via
 cloning the repo and running `install.sh`.

kiro/README.md

@@ -39,8 +39,9 @@ kiro-cli chat --agent erpaval-orchestrator --trust-all-tools
 The `--trust-all-tools` flag auto-approves every tool call, so subagents can
 write files, run shell commands, and call MCP servers without prompting. For
 unattended overnight runs, also pass `--no-interactive` and set
-`KIRO_API_KEY`. For tighter scoping, use `--trust-tools=read,grep,glob,write`
-instead of `--trust-all-tools`.
+`KIRO_API_KEY`. For tighter scoping, use `--trust-tools=read,grep,glob,write,shell`
+instead of `--trust-all-tools` — trusted-command matching is a prefix string
+match, so least-privilege scoping in the agent JSON is safer than a blanket flag.
 
 Then state your request. The orchestrator runs the classifiers (CL-SCOPE,
 CL-COMPLEXITY, CL-RESUME, CL-DIR, CL-RIGOR, CL-SPEC) to decide which phases

kiro/agents/README.md

@@ -16,7 +16,7 @@ with `--trust-all-tools` on the CLI, the orchestrator and its subagents run
 without permission prompts — necessary for the autonomous overnight loop.
 
 For headless runs add `--no-interactive` and set `KIRO_API_KEY`. For
-least-privilege scoping use `--trust-tools=read,grep,glob,write,execute_bash`
+least-privilege scoping use `--trust-tools=read,grep,glob,write,shell`
 instead of `--trust-all-tools`.
 
 System prompts live as sibling Markdown files under `prompts/` and are pulled in via `file://` URIs in each agent JSON.
@@ -39,7 +39,7 @@ If you install by hand, replace every `${ERPAVAL_HOME}` in the JSONs with the ab
 The orchestrator hosts the three ERPAVal hooks inline (Kiro stores hooks per-agent rather than in a global `hooks.json`):
 
 - `agentSpawn` → `kiro_session_start_bootstrap.py` (emits prior-lesson summary)
-- `postToolUse` (matcher: `fs_write`) → `kiro_validate_packet.py` (Pydantic-checks `.erpaval/` writes)
+- `postToolUse` (matcher: `write`) → `kiro_validate_packet.py` (advisory Pydantic check on `.erpaval/` writes — `postToolUse` cannot block)
 - `stop` → `kiro_compound_nudge.py` (one-shot Compound-pending nudge)
 
 The researcher and explorer agents inherit no hooks — they are leaf subagents and don't drive the session loop.

kiro/agents/erpaval-explorer.json

@@ -4,10 +4,10 @@
   "prompt": "file://./prompts/erpaval-explorer.md",
   "model": "claude-opus-4-7",
   "tools": [
-    "fs_read",
+    "read",
     "grep",
     "glob",
-    "execute_bash",
+    "shell",
     "code",
     "introspect",
     "tool_search",

kiro/agents/erpaval-orchestrator.json

@@ -4,16 +4,15 @@
   "prompt": "file://./prompts/erpaval-orchestrator.md",
   "model": "claude-opus-4-7",
   "tools": [
-    "fs_read",
-    "fs_write",
+    "read",
+    "write",
     "glob",
     "grep",
-    "execute_bash",
-    "use_aws",
+    "shell",
+    "aws",
     "code",
     "introspect",
     "tool_search",
-    "delegate",
     "subagent",
     "summary",
     "knowledge",
@@ -56,7 +55,7 @@
     ],
     "postToolUse": [
       {
-        "matcher": "fs_write",
+        "matcher": "write",
         "command": "${ERPAVAL_HOME}/hooks/kiro_validate_packet.py",
         "timeout_ms": 10000
       }

kiro/agents/erpaval-researcher.json

@@ -4,16 +4,15 @@
   "prompt": "file://./prompts/erpaval-researcher.md",
   "model": "claude-opus-4-7",
   "tools": [
-    "fs_read",
-    "fs_write",
+    "read",
+    "write",
     "grep",
     "glob",
-    "execute_bash",
-    "use_aws",
+    "shell",
+    "aws",
     "code",
     "introspect",
     "tool_search",
-    "delegate",
     "knowledge",
     "thinking",
     "todo",