Repository navigation
docs(agent-spec-fields): explain how the other backends consume a spec - #12209
Conversation
|
Intent: Put the answer to "how do the other ACP backends read and use an agent spec?" on the agent spec field reference as its own section, derived from each mirror's own Not a goal: changing any code, changing any mirror's ruling, restructuring the rest of the page, or documenting fields kiro-cli accepts and Kiro Crew ignores. Scope is one markdown file. |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify #12215 exists and carries both the mirror [DESIGN-REVIEWED] 9b2a483 |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The per-harness rulings table is a third hand-maintained copy — agent-host-contract §1's Format cells already spell these dispositions, and nothing syncs any prose copy. Not justified as shipped
What this change shipsInventory (10 items) — 9 justifiedIntent: let a spec author see, on the packaged spec-fields page, which spec fields still take effect on each non-kiro backend — an ADDITION (new doc section), one file.
[FIRST-PRINCIPLES-REVIEWED] 9b2a483 |
eb0a9f9 to
5062ce3
Compare
GPT 5.6 Review —
|
GPT 5.6 Review —
|
|
|
|
|
5062ce3 to
871ba33
Compare
871ba33 to
7650dc3
Compare
|
|
|
7650dc3 to
4d78439
Compare
|
|
|
|
|
What fails. Four tests in They expect
Why it is main's. Three independent open PRs on the same base Only one commit in that range touches both Why nobody caught it. #12188's own CI never validated Windows. Six commits The fix belongs with #12188's Windows reap path, not here: this PR is scoped to |
|
|
The page answered "who reads a spec" with a surface table and then buried the question a reader arrives with -- how the backends that get no spec file still receive its fields -- in two paragraphs of aside. Promote it to its own section, derived from each mirror's own rulings() rather than from prose: the four-case rule (kiro-cli reads the file, KAS gets a wire projection, four mirrored harnesses get individual fields, pi and deepseek get nothing the spec declared), the two entry points that run a mirror at session establishment, a per-harness table of delivered / translated / not-delivered fields with numbered qualifiers, the withholding reason classes, and what a spec author can rely on across harnesses. One correction to the mirrors, stated as such: three of them justify withholding `resources` on the reason that skills and steering are injected as context text instead, which describes the dormant provider=claude_code seam and not the harness they serve. On a mirrored harness a mapped skill:// reaches nothing. Tracked in #12215.
|
Rebased onto The No change to this PR's own diff: still one file, |
4d78439 to
9b2a483
Compare
|
bolichen97
left a comment
There was a problem hiding this comment.
Reviewed against the pr-triage-pipeline gates plus a full-diff read.
docs, 1 file (src/kiro_crew/docs/agent-spec-fields.md, +227/-21). Promotes a buried aside into a 'How the other backends consume a spec' section: a four-case model (kiro-cli reads the file, KAS gets a wire projection, the four mirrored harnesses get per-field rulings, pi and deepseek get no projection), a where-the-mirror-runs table, a per-harness delivered/translated/not-delivered table with numbered qualifiers, and a what-this-means-for-a-spec-author section. The diff is docs-only; no code change rides along.
Design-doc gate: no match. The path is under src/, not the docs/system-specs, docs/design, docs/architecture, docs/request-for-change or docs/task-specs trees (Rule A); no segment token matches (Rule B); the basename is not rfc-*, DESIGN.md or *.spec.md (Rule C); and it normalizes to agentspecfieldsmd with no readme, prfaq or changerequest (Rule D). The spec paths it references appear only as prose links, not in the diff. So this is not the docs-dominant flavor that forbids an approval.
All six security-checklist answers NO, no denylist match, CodeQL PR-scoped open-alert query empty, Semgrep success, readiness label applied after the head commit.
One unresolved advisory concern, recorded rather than dismissed: First Principles Review concluded success but left a warning-level CONCERNS that the per-harness rulings table is a third hand-maintained copy, since agent-host-contract section 1 already spells these dispositions and nothing syncs any prose copy. That is a real maintainability cost and it is accepted here rather than fixed; a drift-prone third copy is worth closing separately.
The PR also self-discloses a defect that lives in the code rather than in this doc: claude_code.py, codex.py and opencode.py justify withholding resources with an 'injected as context text instead' reason that describes the dormant provider=claude_code seam rather than the mirrored harness they serve, where a mapped skill:// reaches nothing. The doc corrects this narratively and the code fix is tracked in #12215.
kirodotdev#12209) The page answered "who reads a spec" with a surface table and then buried the question a reader arrives with -- how the backends that get no spec file still receive its fields -- in two paragraphs of aside. Promote it to its own section, derived from each mirror's own rulings() rather than from prose: the four-case rule (kiro-cli reads the file, KAS gets a wire projection, four mirrored harnesses get individual fields, pi and deepseek get nothing the spec declared), the two entry points that run a mirror at session establishment, a per-harness table of delivered / translated / not-delivered fields with numbered qualifiers, the withholding reason classes, and what a spec author can rely on across harnesses. One correction to the mirrors, stated as such: three of them justify withholding `resources` on the reason that skills and steering are injected as context text instead, which describes the dormant provider=claude_code seam and not the harness they serve. On a mirrored harness a mapped skill:// reaches nothing. Tracked in kirodotdev#12215. Co-authored-by: Joe Guo <zejiangg@amazon.com>
Problem / Motivation
src/kiro_crew/docs/agent-spec-fields.mdanswers "who reads an agent spec" witha four-row surface table, and then leaves the question a reader actually arrives
with — how do the other ACP backends read and use a spec? — in two paragraphs
of aside underneath it. Those paragraphs said the five backends missing from the
table get "no agent definition in any shape", then admitted in the next sentence
that some of their fields arrive anyway, and pointed at
src/kiro_crew/providers/mirrors/as the place to go and find out which.So the page named the folder and withheld the answer. A reader who wants to know
whether their spec's
hooksblock runs oncodex, or whetherdisabledToolssurvives to
goose, had to read seven mirror modules to find out.Why it matters
A spec author picks a harness and writes one file. Which of that file's fields
still mean something after the switch is not guessable from the field tables: the
same key is delivered on one harness, translated on a second, withheld by a
deliberate security decision on a third, and simply has nowhere to go on a
fourth. Getting it wrong is quiet — a
hooksblock that never fires and askill://mapping that loads nothing both look exactly like a spec that works.The mirrors already record most of the answer, one
Rulingper field perbackend, with a required reason. The page never surfaced it.
What changed (motivation → approach → change)
Goal: put the per-harness answer on the page, once, where the question is asked.
Approach: derive it from each mirror's own
rulings()rather than restate it inprose.
providers/mirrors/base.pyalready models this —Concernis the closedlist of things a spec expresses,
Dispositionis the four answers — so thatstructure transposes into a table.
Citing the rulings buys less than it looks, and the limit is worth stating: the
docs lint catches a cited symbol that is RENAMED or DELETED, so a mirror class or
helper going away reds a build. It does not read dispositions, so a mirror that
FLIPS one -- goose gaining per-call deny, or #12215 rewording the three
resourcesreasons -- leaves this table quietly wrong. Only a test that parsesthe table and asserts each cell against
rulings(), or generating the rows fromthem, would close that; both are code and out of this PR's one-file scope, so
#12215 carries it.
Built, as a new
## How the other backends consume a specsection between thesurface table and the field inventory:
projection (
acp/kas_agents.py,to_client_custom_agent); the four mirroredharnesses get individual fields;
pianddeepseekget no projection.AcpRuntime._mirrored_session_mcpandAcpClient._resolve_session_mcp_servers,and why both call
session_projection— onlycodex.pyfills the deny set.mirror module and the reason class, plus eight notes holding the qualifiers so
cells stay scannable.
pi(no-channel) anddeepseek(broker-only) differ:a deepseek session holds the gateway's pooled stubs, not its spec's servers.
harness-owns-the-vocabulary, fixed-by-governance — and why
no-channelis notone of them, which is why
hookssits in that column without being a withhold.claude_code.py,codex.pyandopencode.pyruleresourceswithheld on the reason thatskills and steering are injected as context text instead. That reason holds for
the
provider=claude_codeseam, not for a mirrored harness:_skills_injection_planand the
file://steering block are both gated onis_claude_code, so a mappedskill://is neither loaded natively nor injected by Crew — it reaches nothing.goose.py's reason is already correct. Correcting the three strings, anddeciding whether a spec author should be warned at spawn, is tracked in
resourceshas no reader on a mirrored ACP harness, and nothing says so — at runtime or in the mirrors #12215.mcpServers,toolsandmodeltravel;toolsonly at SERVER granularity, so an@server/toolgrant widens to thewhole server on every mirror.
The two old paragraphs shrink to one sentence. Three places that duplicated them
now point at the section: the top-of-page reading note, the surface table's
acp_backend="claude"row, and the## Per-surface summarypreamble. Theagent-host-contract §1 cross-link is kept;
## Where to lookgains two rows.Follow-up to #12155. Nothing outside that one file changes.
Backwards compatibility
Compatible: documentation only. One markdown file under
src/kiro_crew/docs/changes; no code, no schema, no configuration, and nothing main accepts today is
rejected, renamed or removed.
Tests
N/A — no code changed. The page's own gates are what apply:
python3 scripts/docs_lint.py --test,./scripts/docs-lint.shandpython3 scripts/check_brand_name.pyall exit 0, and the docs lint is whatenforces the symbol-not-line citation convention this section follows.
Manual verification
Every symbol cited was verified present on this base by reading the module, not
by grepping the name:
providers/mirrors/base.py(Concern,Disposition,Ruling,SessionProjection,AgentConfigMirror),registry.py(MIRRORS,PROJECTIONS,ProjectionKind,PerToolDeny),identity.py, and therulings()of all four mirrors, which is where every verdict in the table comesfrom. The two seams were read in place (
acp/runtime.py,acp/client.py), aswere
acp/session_mcp.py(session_mcp_projection,ToolsAllowlist.grants),context.py(_skills_injection_plan,_load_steering_resources),agent_sdk/provider_identity.py(is_claude_code) andagent_sdk/tool_gate.py(ENFORCED_ROUTINGS).Three claims were corrected after a local review round falsified them against
the code, and each correction was re-verified the same way:
resourcesdoes notarrive as context text on a mirrored harness (
is_claude_codeis false for everyacp_backend);toolsdoes not keep kiro-cli's per-tool shape(
ToolsAllowlist.grantsmatches on server name); andidentity.pyis not sharedby all four mirrors (
codexandopencodecall it,goosereaches it throughopencode_projection,claudedoes not use it because its MCP children inheritthe adapter's process env).
Local gate run on this head: the backend gate floor from the resolved prepare-pr
profile exits 0 — black, isort, flake8, mypy (1653 files), and the
docs/brand/harness-parity/feature-map/changelog/focus-cue/comment-history/
memory-store-seam checks, with the scoped test selection reporting
related: 0 test file(s), expected for a markdown-only diff. The frontend andpackaging gates are not run: the diff touches no file under
website/, nolockfile and no template.
Related Issues
No linked issue to close: this is a documentation follow-up to #12155, an
already-merged PR rather than an open issue. It FILES #12215 for the mirror
resourcesreasons it documents but cannot fix under this PR's one-file scope;that issue is deliberately not closed by this PR.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)