awslabs / awslabs/aidlc-workflows
[Question]: the plugin-native-agent allowance is gated to .aidlc, so a Markdown-conductor Kiro tree refuses a plugin-owned dispatch target
- Dominant language
- TypeScript
- Stars
- 4.6k
- Forks
- 827
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 165
Description
### Version
2.6.9 (`core/tools/aidlc-version.ts`), commit `905eb3e2`. The behaviour below
appears once #775's Markdown-conductor detection is in, so this is a question about
intended scope rather than a defect report against the released tree.
### Summary
`compose.ts` accepts a dispatched plugin stage whose agent has no installed
surface **only** when the plugin itself ships a viable native persona and the
harness leaf is `.aidlc` (`scripts/plugin-hooks-template/compose.ts:982`,
`pluginShipsViableNativeAgent` at `:802`). The allowance exists because opencode
and Copilot dispatch from a native Markdown roster that the same compose pass
emits, so the surface does not exist yet at validation time. Once #775 lands, a
Kiro tree with a Markdown conductor dispatches from `agents/.md` — the same
form `pluginShipsViableNativeAgent` validates — but the allowance still does not
apply there, so a plugin-owned dispatch target is refused.
### Evidence
Measured on the #775 branch, with the `test-pro` fixture projection and its
`test-pro-integration` stage flipped from `mode: inline` to `mode: subagent` (the
stage already names the plugin-owned `test-pro-metrics-agent` as a support agent).
On a shipped `dist/kiro-unified` install, compose drops the stage:
```
[degraded] plugin "test-pro" stage "test-pro-integration" references agent
"test-pro-metrics-agent" with mode "subagent" and was not composed: author
.kiro/agents/test-pro-metrics-agent.md (a Kiro Markdown agent with closed
frontmatter), or change the stage's mode to inline
```
The remediation names the file the plugin already ships, at
`/agents/test-pro-metrics-agent.md`.
The same plugin on a stock `dist/opencode` install composes: the stage lands at
`.aidlc/aidlc-common/stages/construction/test-pro-integration.md`, the persona is
installed into both `.aidlc/agents/` and `.opencode/agents/`, and no dispatch drop
is recorded.
Two observations from the Kiro run that I did not chase to a cause: neither the
plugin's persona nor its scope landed in the tree (`.kiro/agents/` stayed at its
15 shipped files), and a retry marker `aidlc/.plugin-compose-retry-test-pro` was
written after the dependent stage `test-pro-full-suite` failed graph compile on
its `requires_stage: test-pro-integration`. So a single refused dispatch target
also cost the plugin's other stage.
### The question
For the agent-v1 JSON trees the refusal is correct, and the suite pins it
(`t188`, "Kiro rejects plugin-owned ensemble collaborators with a compose drop"):
a Markdown persona cannot stand in for the `agents/.json` surface that runtime
dispatches from. On a Markdown-conductor tree that premise no longer holds, so
which of these is intended?
- A plugin-owned dispatch target is meant to work wherever the plugin ships the
harness-native form — in which case the `.aidlc` gate is the thing that is out of
date, and the surface the drop message asks the author to write is one the plugin
already carries.
- Plugin-owned dispatch targets are meant to be an `.aidlc`-only capability, and on
Kiro a plugin may contribute stages but not the personas they dispatch — in which
case the refusal is correct and the remediation text is the part that reads
otherwise.
#775 does not depend on either answer.
Contributor guide
Research direction
Start in scripts/plugin-hooks-template/compose.ts at pluginShipsViableNativeAgent and the allowance around line 982, then compare the Kiro and opencode compose paths using the test-pro fixture projection. Read test t188 and the #775 behavior before deciding whether the .aidlc gate should include Markdown-conductor trees. Done means the intended scope is settled and the compose behavior, remediation text, and dependent-stage handling match that decision.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, typescript
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100