Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Every crewmate still bound to a user-level agent moves onto its conductor, and a restriction its file cannot carry moves with it and is named in its notice

Decided by: Ray (project owner, @buluoray)
Date: 2026-10-28
Supersedes: 2026-10-27-every-used-crewmate-moves-to-the-conductor.md

## Decision

The startup migration moves every crewmate still bound to an agent spec in the user-level agents folder onto its conductor and its own crewmate file: a loss moves with the one-time notice; a grant the worker would gain is never written and is offered only through the capability card; a `hooks`, `permissions` or `toolsSettings` restriction the crewmate file cannot carry no longer keeps the crewmate where it is and withholds no tool, the crewmate moves as it is, and its one-time notice names each restriction that no longer applies; the governance ceiling still governs the merged worker spec; a crewmate whose id is shadowed by a Kiro Crew-owned private copy moves after that copy is retired, one shadowed by a spec Kiro Crew does not own stays and is told once; a used row with no `member_id` is given one and its own V2 store before it moves; and the shared-template governance pass never writes a spec Kiro Crew does not own.

## Why

- A row left on a user-level agent made the shared-template governance pass rewrite the user's own file, which kiro-cli also loads outside Kiro Crew, so the user's own sessions lost their auto-approvals and a package manager reinstalling the spec fought the rewrite on every restart.
- Keeping a crewmate on its old agent for a restriction its file cannot carry left the crewmate doing its work in its chat, the opposite of what the upgrade notice describes; the user is told which restrictions no longer apply, and the governance ceiling still bounds what the worker may do.
- This replaces only the earlier entry's rule that a hook or a `permissions` / `toolsSettings` restriction keeps the crewmate where it is; its rules on losses, gains and unreadable agents stand.

## Evidence

- https://github.com/kirodotdev/KiroCrew/issues/25289 -- the reported rewrite of a bound package spec.
- https://github.com/kirodotdev/KiroCrew/pull/25325 -- the pull request that implements this entry.
1 change: 1 addition & 0 deletions docs/decisions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,4 +110,5 @@ Links to the pull requests, issues and commits that carry the decision.
| [2026-10-22-heartbeat-is-a-schedules-tab-row-not-a-goals-check-in.md](2026-10-22-heartbeat-is-a-schedules-tab-row-not-a-goals-check-in.md) | The crewmate's Heartbeat switch is the first row of the Profile card's Schedules tab, not a check-in on the Goals tab. |
| [2026-10-22-a-new-goal-starts-in-the-crewmate-chat.md](2026-10-22-a-new-goal-starts-in-the-crewmate-chat.md) | A new goal starts from the Goals tab's Create a goal row as a conversation in the crewmate's chat, with no text editor for it on the tab; the "Add something to track" row is gone. |
| [2026-10-27-every-used-crewmate-moves-to-the-conductor.md](2026-10-27-every-used-crewmate-moves-to-the-conductor.md) | On upgrade a crewmate moves onto its conductor even when its worker would lose a grant (told once) or its agent is unreadable (default template); a gain is withheld for the capability card, and a loosened limit still keeps it where it is. |
| [2026-10-28-every-crewmate-on-a-user-level-agent-moves-to-the-conductor.md](2026-10-28-every-crewmate-on-a-user-level-agent-moves-to-the-conductor.md) | Every crewmate still bound to a user-level agent moves onto its conductor; a hook or `permissions` / `toolsSettings` restriction its file cannot carry moves with it and is named in its notice instead of keeping it in place, and the shared-template pass never writes a spec Kiro Crew does not own. Supersedes the 2026-10-27 crewmate-migration entry. |
| [2026-10-27-a-crewmate-the-person-created-is-listed-with-an-empty-chat.md](2026-10-27-a-crewmate-the-person-created-is-listed-with-an-empty-chat.md) | A crewmate the person created (on the Mates page, or by approving Mate's card) is listed even with an empty chat; product-made rows still wait for a message, and the reserved `default` member waits for a message the person sent. |
53 changes: 38 additions & 15 deletions docs/system-specs/modules/crew-mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -3909,9 +3909,23 @@ check".

**Existing crewmates move at startup** (`kiro_crew.mate_config_migration`, off
the loop before the slot restores, never gating readiness). Every crewmate whose
`kiro_agent` does not name its own file is a candidate. A binding with an empty
`member_id` is not a crewmate (an old `assistant`, the built-in
`kirocrew-conductor`): skipped silently. Its roster rows follow the rule for
`kiro_agent` does not name its own file is a candidate
(the 2026-10-28 owner decision in docs/decisions, every crewmate on a user-level agent moves to the conductor
supersedes the 2026-10-27 entry). A binding with an empty `member_id` is not a crewmate
(an old `assistant`, the built-in `kirocrew-conductor`): skipped silently, except a used
row a person or a package sync wrote on a user-level spec Kiro Crew does not own. Such a
row (`source` `kirocrew`, `package` or `aim`; not `default`, the default agent, a legacy
built-in or an app's row) whose DM thread holds a turn (the evidence the synced-crewmate
prune keeps a row on) is first given a `member_id` and its own V2 store
(`_move_with_identity`, `provision_member_memory(upgrade=True)`) once its crewmate file is
written and proven, published together with its repoint in one compare-and-set (a failure
before that publish retires the allocation), the id allocated as the upgrade allocates it
so it keeps the name-derived slug its DM binding and member directory already use; a row
that stays keeps the memory it had. A conversation from before the move keeps the template
and store its own record names, so the notice says a new chat starts on its conductor, and
the agent the crewmate ran on stays one a kiro-cli start is checked on
(`moved_from_agents`, read from the ledger's `threads.<name>.from`). A row never chatted
with is left for the prune. Its roster rows follow the rule for
any row the person did not create: `GET /api/members` ships it with
`dashboard_created` false and the page lists it once `has_dm_message` holds,
and `GET /api/agents` (the pickers) lists it only when its DM thread holds a
Expand All @@ -3926,9 +3940,12 @@ prompt, servers the base lacks with their approvals and selectors, skills, and
its restrictions. Before any write, `plan_move` merges the planned file as a
worker session would (`differences`; `dry_run` is the same as one sentence)
and sorts what differs (`docs/decisions/2026-10-27-every-used-crewmate-moves-to-the-conductor.md`).
A **loosening** keeps the crewmate where it is: a grant the worker would gain,
a switched-off server it would start, a `hooks` entry it would not run, or a
`permissions` / `toolsSettings` restriction it would not keep. Two are cured
A **loosening** keeps the crewmate where it is: a grant the worker would gain
or a switched-off server it would start. A `hooks` entry it would not run or a
`permissions` / `toolsSettings` restriction it would not keep does not: the crewmate
moves as it is, no tool is withheld for it, and its one notice names each restriction
that no longer applies (`dropped_restrictions`, `restrictions_notice`); the governance
ceiling still governs the merged worker spec. The two loosenings are cured
first: a server the source switched off is written `{"disabled": true}`, and a
grant the worker would gain is taken out of the file (`_strip_grants`), so
nothing the old agent lacked is ever granted; the user gets it only through
Expand All @@ -3947,16 +3964,22 @@ read raw, and the default template's file never loosens them
(`_fallback_keeping_limits`): a server it switched off is written
`{"disabled": true}`, a tool it excludes or disables goes into
`excludedTools`, and a grant it never had is taken out. A hook or a
`permissions` / `toolsSettings` restriction the file cannot carry leaves it
where it is. Governance applies as before: the source is read
`permissions` / `toolsSettings` restriction the file cannot carry moves with it
and is named in its notice. Governance applies as before: the source is read
governed, and the worker session still passes POLICY ∩ PROFILE. A crewmate
whose id is also a user-level agent's name, or a spec Kiro Crew generates, is
skipped: its file would never be read, and giving it another file name breaks
every reader that knows a crewmate's file by its binding key
(`mate_capabilities.binding_is_mate`, `member_mate_tools`,
`mate_worker._claimed_file`, the revocations keyed by file id). A binding with
no `member_id` stays out of the migration: a `member_id` on a store that is not
its own V2 store fails every turn (`memory_stores.require_member_memory_store`).
whose id is also a user-level agent's name is moved only when that agent is its
own private copy (a fork whose lineage is private to it and that its binding runs,
`_crew_owned_shadow`): the copy is moved to `~/.kiro/mates/retired/` and its
lineage dropped just before the repoint (`_retire_shadow`), so pointing the binding
back and moving the file back is a rollback. Any other user-level agent under its id
is not Kiro Crew's: the crewmate stays and is told once, and that spec is never
written. A crewmate named after a spec Kiro Crew generates is skipped. Its file would
never be read, and giving it another file name breaks every reader that knows a
crewmate's file by its binding key (`mate_capabilities.binding_is_mate`,
`member_mate_tools`, `mate_worker._claimed_file`, the revocations keyed by file id). Any other binding
with no `member_id` stays out of the migration: a `member_id` on a store that is not
its own V2 store fails every turn (`memory_stores.require_member_memory_store`), which
is why a minted row gets its store with its id.
A crewmate left where it was gets one WARNING (`MigrationReport.dry_run_failed`)
and is tried again next boot. A written file is read back and checked against
the same loosening rule, and the kit record names its source. The ledger keeps
Expand Down
Loading
Loading