Skip to content

refactor(agent): move the rebuild, prompts and grants to agent_parts - #22981

Merged
iamwhatever merged 1 commit into
mainfrom
refactor/linecap-s35-agent-p2
Oct 22, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
refactor/linecap-s35-agent-p2

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Bring agent.py under the 2,000-line cap with every import path, patch seam and behaviour unchanged; this second PR moves the rebuild, its governance-ceiling projection, and the installed agents' prompts and grants into agent_parts.

src/kiro_crew/agent.py is 4,070 lines on main after #22890, still over the repository's 2,000-line limit for hand-written files, and still listed in .github/file-line-cap-baseline.txt. Its largest unit, rebuild_agent_config (523 lines), is the function most agent-spec changes touch.

Why it matters

The line cap only holds if the files on its baseline shrink. Until this half lands, every change to the rebuild order, a conductor prompt or a grant tuple edits a 4,000-line module, and the file keeps its baseline row.

Not a goal

  • No behaviour change: no spec byte, refusal, audit record, log line or prompt changes.
  • No new or renamed public names; every name kiro_crew.agent held still resolves on it as the same object.
  • No change to the agent_materialization owners, to how kiro_crew.agent forwards to them, or to the six owners refactor(agent): move spec writes, build and lookups to agent_parts #22890 added.
  • No edit to any CI workflow or gate. The only row edits are this split's own: deleting agent.py's line-cap row, the inventory JSON, and the path rows of two tests that read moved code by path; five more test files get comment-only cite fixes.

What changed (motivation → approach → change)

agent.py keeps its import path and its facade shape from #22890; three more owners in kiro_crew.agent_parts take whole definitions moved without edits:

Owner (lines) What it owns
agent_parts/spec_rebuild.py (1,420) rebuild_agent_config and its outcome tracking, the ceiling-projection memo and the entry points that re-project the specs, the fork-governance check, ensure_agent_materialized, and the installs the rebuild drives
agent_parts/spec_prompts.py (674) the guest, team-lead, conductor, dashboard-manager, pipeline-conductor, worker and security-conductor prompts and the shared work-ledger protocol
agent_parts/spec_grants.py (585) the server grants each installed agent gets without an approval prompt

The same kiro_crew._facade_compose.compose call runs the new owners' functions on agent.py's globals, so a patch through kiro_crew.agent still reaches the moved code and global rebinds still land there. rebuild_agent_config is wrapped where it is defined (_tracks_rebuild_outcome), and compose reaches a wrapper but not the function its closure holds, so agent.py wraps it again around a rebound copy and binds install_agent to the same object, as it was. agent.py goes from 4,070 to 1,566 lines and its baseline row is deleted.

Backwards compatibility

Compatible: every name kiro_crew.agent held still resolves on it as the same object (pinned by test/campaign_facade_inventories/kiro_crew.agent.json, now 76 names pinned to their home object, and test_agent_refactor_contracts.py's frozen surface), and a patch through it still reaches the code that reads the name, because that code runs on its globals.

Reader: src/kiro_crew/agent.py:rebuild_agent_config -- release -- re-wrapped on the facade around a rebound copy; slack/gateway_runtime/service_boot.py:155 and mcp_broker.py:164 import it from kiro_crew.agent; test_agent_parts.py::test_the_rebuild_tracker_rebinds_its_globals_on_the_facade
Reader: src/kiro_crew/agent.py:rebuild_agent_config_reporting -- crew page -- composed from agent_parts.spec_rebuild; dashboard/handlers/_shared_config_followups.py:42 and connections/ownership.py:712 import it from kiro_crew.agent; test_agent_home_isolation.py
Reader: src/kiro_crew/agent.py:ensure_agent_materialized -- chat -- composed; acp/client_start.py:257 and acp/harness/kas.py:455 reach it through kiro_crew.agent; test_acp_harness_contract.py
Reader: src/kiro_crew/agent.py:require_fork_governance -- chat -- composed; acp/client_start.py:286 and acp/harness/kas.py:453 reach it through kiro_crew.agent; test_agent_spec_hardened_reads.py
Reader: src/kiro_crew/agent.py:prime_ceiling_projection -- release -- composed; slack/gateway_runtime/service_boot.py:1116 imports it from kiro_crew.agent; test_conductor_allowed_tools_survive.py
Reader: src/kiro_crew/agent.py:reproject_for_ceiling_change -- release -- composed; service_boot.py:1141 registers it as a post-install hook; test_agent_refactor_fork_refresh.py
Reader: src/kiro_crew/agent.py:reproject_for_profile_change -- release -- composed; service_boot.py:1095 imports it from kiro_crew.agent; test_governance_profile_reprojection.py
Reader: src/kiro_crew/agent.py:retry_held_conductor_specs -- release -- composed; slack/gateway_runtime/process_entry.py:439 imports it from kiro_crew.agent; test_agent_refactor_fork_refresh.py
Reader: src/kiro_crew/agent.py:sync_aim_packages -- release -- composed; called by rebuild_agent_config from the same globals; test_agent_refactor_contracts.py

Tests

  • test/test_agent_parts.py covers the three new owners with the same contract as refactor(agent): move spec writes, build and lookups to agent_parts #22890's six: every composed function runs on kiro_crew.agent's globals, names it as its module and is the object it binds; the bytecode sweep finds every global bound there; the patch scan of the test trees reaches each owner; owners import stdlib plainly and the facade only for type checking; nothing but the facade imports an owner. New here: the rebuild's outcome tracker rebinds _rebuild_incomplete and _projected_ceiling_generation on the facade when the rebuild raises; a facade patch reaches the rebuild; install_agent is the re-wrapped rebuild; the fresh-interpreter value check now covers at least 40 module-level values.
  • Re-pointed or joined, assertions unchanged (L30, one mutation proof each, red): test_ledger_conductor_agent.py re-points its read from agent.py to agent_parts/spec_rebuild.py; test_agent_spec_hardened_reads.py keys require_fork_governance's row on agent_parts/spec_rebuild.py.
  • test/campaign_facade_inventories/kiro_crew.agent.json: the 84 BASE public names, 76 pinned to their home object.

Local floor at this head (-n 3, through the campaign's gate slots): the 608 test files that import, patch or read kiro_crew.agent or its owners, plus every test that scans the source tree and the repository guards. 30,525 passed, 98 skipped, 6 xfailed, 0 failed. Per-file line coverage (--cov=kiro_crew, the 234 test files that import the facade): spec_rebuild 92.4%, spec_prompts 100%, spec_grants 100%, agent.py 93.1%; the six #22890 owners stay at 89.9-97.4%. test/test_agent_parts.py passed five times at -n0 and in the -n 3 floor; the flake-pattern and wait-discipline ratchets pass.

Manual verification

N/A — a structural move: the move audit proves the moved code is unchanged, and the floor above runs every test that imports, patches or reads kiro_crew.agent.

Related Issues

Part of #20192

Move audit

python3 bin/move_audit.py --base <merge-base> --head <this head> (units keyed by AST, positions and comments ignored):

src/kiro_crew/agent.py: 4070 -> 1566 lines; moved 81.66% (python-ast)
   changed: rebuild_agent_config [FunctionDef] 523 lines
   changed: Expr [Expr] 36 lines
   changed: _install_aim_capabilities [FunctionDef] 11 lines
   changed: Assign [Assign] 8 lines
   changed: sync_aim_packages [FunctionDef] 8 lines

Expr is the facade's module docstring (rewritten for the layout) and Assign is the _PARTS owner tuple (three owners added). The three functions' only edit is a docstring reword; stripping docstrings, 82 of the 83 units of main's agent.py are AST-identical at their new home, and the 83rd is _PARTS. Every non-move edit inside moved code:

  • brand (Kiro Crew prose spelling): three comments in rebuild_agent_config;
  • internal references (Master rulings; docstring-only, AST-identical once docstrings are stripped):
    • rebuild_agent_config docstring: names "AIM's mcp-servers directory" instead of a home-directory path, because the 523-line function cannot stay in agent.py under the cap;
    • _install_aim_capabilities docstring: "Amazon-internal package manager" -> "internal package manager";
    • sync_aim_packages docstring: "Amazon-internal agents/skills/plugins package manager" -> "internal agents/skills/plugins package manager".
    • rebuild_agent_config comment above sync_shared_server_refs: "via aim mcp install" -> "via AIM's installer" (the internal content scan's aim-invocation rule; comment only, AST unchanged).

Diff shape

  • git diff <merge-base>...HEAD | wc -c = 344,753 bytes.
  • git diff --numstat and git diff --minimal --numstat are identical for all 27 files; agent.py +73/-2577 under both.
  • New files: agent_parts/spec_rebuild.py 1,420, spec_prompts.py 674 and spec_grants.py 585 lines.
  • agent.py ends at 1,566 lines, so this PR deletes its row from .github/file-line-cap-baseline.txt.

CI path references

None: no workflow path filter or file list names agent.py.

Facade target exception

The card's target for agent.py is 1,200 lines; it ends at 1,566 (Master ruling R2, inside the campaign's 1,600). What stays, and why:

Kept in agent.py Lines Why
the TYPE_CHECKING block 215 test_agent_refactor_facade.py pins exactly one block equal to _EXPORTS
_EXPORTS_BY_OWNER and the forwarding machinery 302 pinned shape; the text kiro_crew.agent_materialization may appear only in agent.py and that package
the 7-statement tail 72 pinned statement by statement
_MANAGED_MCP_SERVERS 158 its invocation lambdas must read the facade's globals (tests patch _kirocrew_mcp_invocation)
_all_skill_paths and its alias 122 .aim literals stay in their original file (L31)
_refresh_dynamic_fields 218 its model-id migration map fails code-review.yml's added-line check if moved
the knowledge, research and heartbeat prompts 130 their bytes spell "KiroCrew" inside the string, with no room for a marker, and spec-bytes digests freeze them
_KIRO_MCP_JSON, _CC_MCP_JSON, _DEFAULT_KIRO_HOOKS_DIR 8 conftest's _SHARED_KIRO_PATHS and the host-isolation ratchet key them by module
_BUNDLED_CFG_DIR 2 evaluated from __file__ at import
SharedAgentHomeRefused, ForkGovernanceUnresolved 19 exception classes keep kiro_crew.agent as their module
import header, re-imports and compose glue ~320 read by the composed functions and by mypy

Notes for reviewers

  • Series. refactor(agent): move spec writes, build and lookups to agent_parts #22890 (merged as 5921c0a) moved the first six owners; this PR is its second half, rebased onto main after it merged. Upstream since then touched agent.py once (fix(pi): honour an agent spec's zero-tool ban on pi sessions #22808 added knowledge_agent_model to the forwarding table and the TYPE_CHECKING block); those lines are kept, and nothing upstream touched the moved rebuild, prompts or grants.
  • Mechanism and loggers. Unchanged from refactor(agent): move spec writes, build and lookups to agent_parts #22890: compose, the moved functions log through agent.logger (kiro_crew.agent), no owner binds a logger, no class moves.
  • Re-wrap placement. The rebuild's re-wrap sits beside the spec lock's, right after the compose call and before _MANAGED_MCP_SERVERS is built; the pinned 7-statement tail is unchanged.
  • L29 cite edits (cited path only): docs/architecture/mcp.md:2255; docs/architecture/overview.md:29; docs/system-specs/modules/config.md:3973; heartbeat.md:114, 154; pipeline-conductor.md:37-38; session-control.md:1892, 2148; src/kiro_crew/docs/agent-spec-fields.md:846-847, 887, 894 and a new "Where to look" row for spec_rebuild.py; src/kiro_crew/agent_files.py:120; src/kiro_crew/dashboard/side_readonly_spec.py:23; src/kiro_crew/mcp_discovery_config.py:224; src/kiro_crew/mcp_discovery_server_info.py:113; src/kiro_crew/mcp_gateway/rewriter_launch.py:193, 206. Test comments and docstrings (no assertion or code change): test/test_conductor_agent.py:181 agent.py -> agent_parts/spec_grants.py; test/test_goal_conductor_skill_grants.py:4 agent.py -> agent_parts/spec_grants.py; test/test_worker_agent_spawn_gate.py:316, 396 "the definitions themselves" -> "the facade binding these names"; test/worker_agent_helpers.py:48 "defining every name" -> "binding every name"; test/test_app_mcp_scoping.py:1186-1188 "composed from the agent_materialization modules" -> "composed from its agent_parts owners and the agent_materialization modules"; test/test_app_mcp_scoping.py:1342-1343 "in agent.py" -> "in agent.py and its agent_parts owners".
  • References not edited. Historical "verified at" records in docs/request-for-change/ and the RFCs and plans that name agent.py (Master ruling R7).
  • Local gate. scripts/local-gate.py --dry-run selects most of the suite (the bare agent stem matches it), so the floor above ran instead. Static gates at this head: black, isort (whole tree), flake8, cold mypy src/kiro_crew on a git archive export (3,507 files, clean), subprocess-encoding, agent-sdk boundary, sync-io, memory-store seam, lockdown, harness parity, comment history, brand, feature map, line cap, docs lint, cross-platform replay (0 findings), code-review.yml greps, semgrep 1.78 with the CI configs and --baseline-commit (0 findings, no parse errors), and check_inventory.py (84/84). Installed-mode smoke: a wheel built from a git archive export imports kiro_crew.agent and all nine owners from site-packages, composed (rebuild_agent_config runs on the facade's globals and install_agent is the same object).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 22, 2026 00:40
@bolichen97
bolichen97 requested a review from CrysisDeu October 22, 2026 00:41
@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision fd80f36b73c3ae87701f18bd71bf683009bdfb04 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 22, 2026
@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of fd80f36b73c3ae87701f18bd71bf683009bdfb04 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: this is a pure structural move. It follows the facade-compose pattern from #22890, keeps every import path and patch seam, and the inventory and contract tests pin both.

[DESIGN-REVIEWED] fd80f36

Description read

[DESCRIPTION-READ] 25788a6ecedf0f7b9bdff01389e37c6b6d6d97e9cb70d995ea41f00c87876a4f

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of fd80f36b73c3ae87701f18bd71bf683009bdfb04 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks: a structural split that AGENTS.md's 2,000-line cap requires, with every public name still resolving on the facade.

What this change ships

Inventory (6 items) — 6 justified

Intent: shrink agent.py below the line cap without changing any behaviour or import path. This is a FIX (a cap violation that is on the baseline), done as a refactor.

  1. The rebuild, the ceiling projection, fork governance and the heartbeat installer move to agent_parts/spec_rebuild.py. — justified
  2. The installed agents' system prompts move to agent_parts/spec_prompts.py. — justified
  3. The per-agent auto-approve grant tuples move to agent_parts/spec_grants.py. — justified
  4. agent.py re-wraps rebuild_agent_config/install_agent around a rebound copy so facade patches still reach it. — justified
  5. agent.py's row is deleted from .github/file-line-cap-baseline.txt. — justified
  6. Docs, comments and two path-reading tests are re-pointed at the new files, and the facade inventory JSON is updated. — justified

[FIRST-PRINCIPLES-REVIEWED] fd80f36

Description read

[DESCRIPTION-READ] 6108e825ecead109e4ece75a0015dc5d463f4f8a77e2e55562c371f2be13b177

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed fd80f36b73c3ae87701f18bd71bf683009bdfb04 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] fd80f36

Verdict parsed from the review's SHA-scoped output markers for commit fd80f36b73c3ae87701f18bd71bf683009bdfb04.

False positive or not applicable? A repository writer can comment:
/ai-review override fable fd80f36b73c3ae87701f18bd71bf683009bdfb04: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of fd80f36b73c3ae87701f18bd71bf683009bdfb04 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] fd80f36

False positive or not applicable? A repository writer can comment:
/ai-review override gpt fd80f36b73c3ae87701f18bd71bf683009bdfb04: <one-sentence reason>

@bolichen97
bolichen97 enabled auto-merge (squash) October 22, 2026 01:05
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 22, 2026
@bolichen97
bolichen97 force-pushed the refactor/linecap-s35-agent-p2 branch from be80704 to 16bbd86 Compare October 22, 2026 01:34
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 22, 2026
The second of two PRs that bring agent.py under the 2,000-line cap. It
moves the rebuild with its governance-ceiling projection, the agents'
system prompts and their server grants, unchanged, into three more
kiro_crew.agent_parts owners (spec_rebuild, spec_prompts, spec_grants);
agent.py drops from 4,070 to 1,566 lines and leaves the line-cap
baseline.

The owners run on agent.py's module globals through
kiro_crew._facade_compose.compose, as the first six do, so the rebuild's
global rebinds still land on the facade that fork_refresh and the tests
read. agent.py wraps rebuild_agent_config (and its alias install_agent)
again around a rebound copy, since compose reaches the outcome
tracker's wrapper but not the function its closure holds. The
knowledge, research and heartbeat prompts stay in agent.py: their bytes
spell the product name joined, which the brand gate refuses on a moved
line.

test/test_agent_parts.py grows to the nine owners and pins the re-wrap
and the tracker's global rebinds; path-keyed test rows and the docs
that cite the moved code follow it.

Part of #20192
@bolichen97
bolichen97 force-pushed the refactor/linecap-s35-agent-p2 branch from 16bbd86 to fd80f36 Compare October 22, 2026 02:12
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 22, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE at fd80f36.

This is a faithful move. Of the 82 top-level units in BASE agent.py, 78 are AST-identical at their new home, 3 differ only in docstrings, and the last is the _PARTS tuple. So the grant tuples, require_fork_governance and the prompts move unchanged. The facade rebinds every owner function onto its own globals, then re-applies _tracks_rebuild_outcome around a rebound rebuild_agent_config and binds install_agent to the same object, as BASE did (agent.py L493-L510). Every AI lane passed with no notes, checks are green, and the branch merges cleanly into main.

— crew-pr-reviewer (r119)

@iamwhatever
iamwhatever merged commit 0de5ab1 into main Oct 22, 2026
105 checks passed
@iamwhatever
iamwhatever deleted the refactor/linecap-s35-agent-p2 branch October 22, 2026 06:31
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants