coilyco-flight-deck/agent-compose

Watch

Materialize role definitions as skills and shrink startup doctrine #121

New issue

Closed

opened 2026-07-29 04:11:54 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-07-29 04:11:54 +00:00

Member

Outcome

Make every person-profile role a first-class skill and use role plus personality
skills as the lazy-loaded behavioral doctrine for native agents.

The startup instruction surface becomes a small bootstrap plus compact identity
cards rather than embedding every long-form role briefing and personality
definition eagerly. The identity cards preserve the delightful visible parts
of the person model: names, pronouns, purposes, personality melds, colors,
symbols or emblems, motifs, and blended favorite colors.

Once a role is assigned, inferred, or switched, the agent must load that role
skill and the complete ordered personality meld before acting.

This turns the role definitions themselves into the canonical skills. It does
not generate a second hand-maintained copy of each briefing.

Current state

#52 made long-form role briefings canonical person-profile data.
#53 projects the selected role briefing through harness instruction load
points.
#61 made personality definitions canonical skill bodies.
#111 is defining the final person-profile and personality-library layout.
#117 permits explicit switching between inferred native roles.

The native host roster still embeds every full role briefing in startup context.
Role-composed task skills are selected separately and are not substitutes for
the role charter.

Source and identity contract

A person profile owns one role skill per role under its final roles/
layout.
Each role has a stable skill id, conventionally role-<slug>.
The role skill body is the sole canonical long-form mission, operating loop,
ownership, completion, handoff, and escalation doctrine for that role.
Role KDL or other profile metadata retains only structured selection data,
including slug, concise purpose, ordered personality meld, seats,
inspirations, colors, symbols or emblems, motifs, other compact identity
primitives, and the stable role-skill binding.
The loader rejects a missing role skill, duplicate skill id, mismatched slug,
malformed frontmatter, or divergent duplicate briefing.
Generated rosters, snapshots, catalogues, transcripts, and bundle manifests
derive from the same role skill and record its logical source id and digest.
No renderer or compatibility adapter maintains a second long-form briefing.

Issue #110 should move the existing authored role prose directly into this
final source shape. Issue #111 should define the profile-relative layout and
compatibility adapter once.

Skill shape

Each role skill uses ordinary skill structure and concise activation metadata:

---
name: role-advisor
description: Adopt the Advisor charter for decision-focused research. Use when the session assigns, infers, or explicitly switches to the advisor role.
---

The body contains only doctrine specific to performing that role. Shared
native adaptation, confirmation, fixed-role, slash-goal, and authority rules
remain engine-owned bootstrap policy rather than being copied into every role.

Personality definitions remain atomic personality skills. Role skills reference
the ordered meld through structured profile metadata rather than copying
personality prose.

Progressive disclosure applies to behavioral prose, not identity texture.
Agent-compose keeps compact structured identity metadata visible even when the
corresponding role or personality body has not loaded.

An assigned Advisor identity card may look like:

# solar advisor

🔭 **Advisor**

Research decisions that need deeper evidence, synthesis, or domain context.

**Codex // he/him**
**Favorite color // #779ae7**

## Personality meld

### 🌙 Reflective

**#787bd2 // patience // depth // consideration**

Bring patience, depth, and consideration before responding to agent work.

### 🔍 Curious

**#d98e48 // exploration // discovery // open questions**

Bring inquisitiveness, exploration, and delight in discovery to agent work.

### 💎 Candid

**#3dbfe2 // clarity // honesty // constructive disagreement**

Bring forthrightness, clarity, and willingness to disagree to agent work.

## Active doctrine

Before acting, load:

* `role-advisor`
* `personality-reflective`
* `personality-curious`
* `personality-candid`

The emoji above are illustrative. The renderer uses the exact symbols or
emblems from the profile or personality libraries, uses // between compact
identity fields, and does not invent fallback decoration or flatten the
existing identity model into plain slugs.

Native startup and progressive disclosure

Assigned role

For a caller-assigned native bundle, agent-compose:

materializes the selected role-<slug> skill
materializes every personality skill in the selected ordered meld
emits a compact selected-identity card plus a bootstrap naming those exact
skill ids
requires the agent to read the complete role skill and every meld skill before
taking task action
omits inactive role bodies, inactive personality bodies, and the complete
long-form role catalogue from startup instructions

A missing selected skill is a composition or verification failure. The agent
does not silently proceed with only a pointer.

Unassigned native session

For a directly steered native session with no caller-assigned role,
agent-compose:

installs all available role and personality skills for lazy discovery
emits the personality invariant, native adaptation policy, compact role
identity cards, and the selection bootstrap
requires the agent to infer one role from the initial substantive request
requires the agent to load that role skill and its complete ordered meld
before acting

Each compact role card may include the role slug and purpose, available seats,
ordered meld, personality symbols or emblems and colors, and blended favorite
color. The full behavioral briefings for inactive roles do not appear in
startup context.
Personality aliases and the compact index from #112 remain discovery metadata,
not eagerly loaded personality bodies.

Native role switch

When #117 permits an inferred native role switch, the bootstrap requires the
agent to load the new role skill and its complete ordered meld before continuing.
The prior role charter stops governing the session. A caller-assigned role
remains fixed.

Compiled delivery

Compiled delivery cannot assume a native skill loader. It continues to inline
the selected role skill and active personality bodies with deterministic source
markers. Agent-compose never emits an unusable pointer merely to reduce bytes.

Role-composed capability boundary

Role skills define who the agent is and the feedback loop the role owns.
Existing AOS role-composed skills define task methods and specialist knowledge.

Selecting a role may select both surfaces, but agent-compose does not merge
their ownership:

person profile: role skill plus ordered personality meld
capability provider: ordinary and role-composed task skills
Ward and guarded tools: executable authority

A role skill grants no commands, credentials, mounts, network access, model
selection, or permission.

Compatibility

v1.x complete-person packages with inline role briefings remain readable
through a documented adapter.
The adapter exposes one logical role skill per legacy role without writing a
mutable source tree or creating divergent prose.
Existing person.json, roster, compose, evaluation, palette, overlay, bundle,
and catalogue behavior remains available while consuming the resolved role
skill internally.
Public generated artifacts never expose local filesystem paths.

Acceptance evidence

The shipped default profile has one valid role skill for every role.
No canonical long-form role briefing remains embedded in KDL, Go, generated
roster prose, or another competing source.
The Engineer and Ops role skills carry #116's symmetric ownership, promotion,
live-verification, and rollback boundary.
The QA role skill carries #128's conditional fixture-verification doctrine
without claiming that role prose grants executable authority.
An assigned Advisor bundle contains role-advisor plus reflective,
curious, and candid, and contains no inactive role body.
An unassigned native fixture infers Advisor, loads those four skill bodies,
and only then answers the task.
A native Advisor to QA switch loads role-qa, meticulous, candid, and
playful, then stops applying the Advisor charter.
A caller-assigned bundle still rejects role switching.
A missing or malformed selected role or personality skill fails before task
execution.
Native startup output contains only the compact bootstrap, invariant, role
identity cards, and skill metadata. The cards preserve seat names and
pronouns, role purposes, ordered melds, colors, symbols or emblems, motifs,
and blended favorite colors. Compact identity fields use // separators,
not middle dots. Startup contains no inactive long-form role or personality
body.
A checked-in context-budget comparison reports the before and after startup
bytes and tokens for unassigned native Codex and Claude plus one assigned
role bundle.
Compiled delivery contains the selected role and meld bodies and passes
semantic parity tests with native delivery.
Tests prove that role selection changes doctrine and knowledge only, never
executable authority.
Documentation covers authoring, loading order, native inference, switching,
compiled fallback, compatibility, and the profile/provider/authority split.
ward exec test and ward exec smoke pass.

Non-goals

Turning role-composed task skills into role briefings
Loading every full role skill at startup
Inferring a role inside the engine from arbitrary task text
Letting a model skip mandatory role or meld loading
Changing role authority, model routing, seats, or harness selection
Removing the personality invariant or native adaptation bootstrap
Removing colors, icons, symbols, emblems, motifs, favorite colors, names,
pronouns, or other compact identity texture from startup

Dependencies

#110 for authored-content extraction
#111 for the final profile and personality-library source contract
#112 for compact personality discovery and aliases
#116 supplies the final Engineer and Ops ownership wording and may land in
the same implementation slice
#128 supplies the final conditional QA fixture-verification wording and may
land in the same implementation slice

## Outcome Make every person-profile role a first-class skill and use role plus personality skills as the lazy-loaded behavioral doctrine for native agents. The startup instruction surface becomes a small bootstrap plus compact identity cards rather than embedding every long-form role briefing and personality definition eagerly. The identity cards preserve the delightful visible parts of the person model: names, pronouns, purposes, personality melds, colors, symbols or emblems, motifs, and blended favorite colors. Once a role is assigned, inferred, or switched, the agent must load that role skill and the complete ordered personality meld before acting. This turns the role definitions themselves into the canonical skills. It does not generate a second hand-maintained copy of each briefing. ## Current state * #52 made long-form role briefings canonical person-profile data. * #53 projects the selected role briefing through harness instruction load points. * #61 made personality definitions canonical skill bodies. * #111 is defining the final person-profile and personality-library layout. * #117 permits explicit switching between inferred native roles. The native host roster still embeds every full role briefing in startup context. Role-composed task skills are selected separately and are not substitutes for the role charter. ## Source and identity contract * A person profile owns one role skill per role under its final `roles/` layout. * Each role has a stable skill id, conventionally `role-<slug>`. * The role skill body is the sole canonical long-form mission, operating loop, ownership, completion, handoff, and escalation doctrine for that role. * Role KDL or other profile metadata retains only structured selection data, including slug, concise purpose, ordered personality meld, seats, inspirations, colors, symbols or emblems, motifs, other compact identity primitives, and the stable role-skill binding. * The loader rejects a missing role skill, duplicate skill id, mismatched slug, malformed frontmatter, or divergent duplicate briefing. * Generated rosters, snapshots, catalogues, transcripts, and bundle manifests derive from the same role skill and record its logical source id and digest. * No renderer or compatibility adapter maintains a second long-form briefing. Issue #110 should move the existing authored role prose directly into this final source shape. Issue #111 should define the profile-relative layout and compatibility adapter once. ## Skill shape Each role skill uses ordinary skill structure and concise activation metadata: ```yaml --- name: role-advisor description: Adopt the Advisor charter for decision-focused research. Use when the session assigns, infers, or explicitly switches to the advisor role. --- ``` The body contains only doctrine specific to performing that role. Shared native adaptation, confirmation, fixed-role, slash-goal, and authority rules remain engine-owned bootstrap policy rather than being copied into every role. Personality definitions remain atomic personality skills. Role skills reference the ordered meld through structured profile metadata rather than copying personality prose. Progressive disclosure applies to behavioral prose, not identity texture. Agent-compose keeps compact structured identity metadata visible even when the corresponding role or personality body has not loaded. An assigned Advisor identity card may look like: ```md # solar advisor 🔭 **Advisor** Research decisions that need deeper evidence, synthesis, or domain context. **Codex // he/him** **Favorite color // #779ae7** ## Personality meld ### 🌙 Reflective **#787bd2 // patience // depth // consideration** Bring patience, depth, and consideration before responding to agent work. ### 🔍 Curious **#d98e48 // exploration // discovery // open questions** Bring inquisitiveness, exploration, and delight in discovery to agent work. ### 💎 Candid **#3dbfe2 // clarity // honesty // constructive disagreement** Bring forthrightness, clarity, and willingness to disagree to agent work. ## Active doctrine Before acting, load: * `role-advisor` * `personality-reflective` * `personality-curious` * `personality-candid` ``` The emoji above are illustrative. The renderer uses the exact symbols or emblems from the profile or personality libraries, uses ` // ` between compact identity fields, and does not invent fallback decoration or flatten the existing identity model into plain slugs. ## Native startup and progressive disclosure ### Assigned role For a caller-assigned native bundle, agent-compose: * materializes the selected `role-<slug>` skill * materializes every personality skill in the selected ordered meld * emits a compact selected-identity card plus a bootstrap naming those exact skill ids * requires the agent to read the complete role skill and every meld skill before taking task action * omits inactive role bodies, inactive personality bodies, and the complete long-form role catalogue from startup instructions A missing selected skill is a composition or verification failure. The agent does not silently proceed with only a pointer. ### Unassigned native session For a directly steered native session with no caller-assigned role, agent-compose: * installs all available role and personality skills for lazy discovery * emits the personality invariant, native adaptation policy, compact role identity cards, and the selection bootstrap * requires the agent to infer one role from the initial substantive request * requires the agent to load that role skill and its complete ordered meld before acting Each compact role card may include the role slug and purpose, available seats, ordered meld, personality symbols or emblems and colors, and blended favorite color. The full behavioral briefings for inactive roles do not appear in startup context. Personality aliases and the compact index from #112 remain discovery metadata, not eagerly loaded personality bodies. ### Native role switch When #117 permits an inferred native role switch, the bootstrap requires the agent to load the new role skill and its complete ordered meld before continuing. The prior role charter stops governing the session. A caller-assigned role remains fixed. ### Compiled delivery Compiled delivery cannot assume a native skill loader. It continues to inline the selected role skill and active personality bodies with deterministic source markers. Agent-compose never emits an unusable pointer merely to reduce bytes. ## Role-composed capability boundary Role skills define who the agent is and the feedback loop the role owns. Existing AOS role-composed skills define task methods and specialist knowledge. Selecting a role may select both surfaces, but agent-compose does not merge their ownership: * person profile: role skill plus ordered personality meld * capability provider: ordinary and role-composed task skills * Ward and guarded tools: executable authority A role skill grants no commands, credentials, mounts, network access, model selection, or permission. ## Compatibility * v1.x complete-person packages with inline role briefings remain readable through a documented adapter. * The adapter exposes one logical role skill per legacy role without writing a mutable source tree or creating divergent prose. * Existing `person.json`, roster, compose, evaluation, palette, overlay, bundle, and catalogue behavior remains available while consuming the resolved role skill internally. * Public generated artifacts never expose local filesystem paths. ## Acceptance evidence * The shipped default profile has one valid role skill for every role. * No canonical long-form role briefing remains embedded in KDL, Go, generated roster prose, or another competing source. * The Engineer and Ops role skills carry #116's symmetric ownership, promotion, live-verification, and rollback boundary. * The QA role skill carries #128's conditional fixture-verification doctrine without claiming that role prose grants executable authority. * An assigned Advisor bundle contains `role-advisor` plus `reflective`, `curious`, and `candid`, and contains no inactive role body. * An unassigned native fixture infers Advisor, loads those four skill bodies, and only then answers the task. * A native Advisor to QA switch loads `role-qa`, `meticulous`, `candid`, and `playful`, then stops applying the Advisor charter. * A caller-assigned bundle still rejects role switching. * A missing or malformed selected role or personality skill fails before task execution. * Native startup output contains only the compact bootstrap, invariant, role identity cards, and skill metadata. The cards preserve seat names and pronouns, role purposes, ordered melds, colors, symbols or emblems, motifs, and blended favorite colors. Compact identity fields use ` // ` separators, not middle dots. Startup contains no inactive long-form role or personality body. * A checked-in context-budget comparison reports the before and after startup bytes and tokens for unassigned native Codex and Claude plus one assigned role bundle. * Compiled delivery contains the selected role and meld bodies and passes semantic parity tests with native delivery. * Tests prove that role selection changes doctrine and knowledge only, never executable authority. * Documentation covers authoring, loading order, native inference, switching, compiled fallback, compatibility, and the profile/provider/authority split. * `ward exec test` and `ward exec smoke` pass. ## Non-goals * Turning role-composed task skills into role briefings * Loading every full role skill at startup * Inferring a role inside the engine from arbitrary task text * Letting a model skip mandatory role or meld loading * Changing role authority, model routing, seats, or harness selection * Removing the personality invariant or native adaptation bootstrap * Removing colors, icons, symbols, emblems, motifs, favorite colors, names, pronouns, or other compact identity texture from startup ## Dependencies * #110 for authored-content extraction * #111 for the final profile and personality-library source contract * #112 for compact personality discovery and aliases * #116 supplies the final Engineer and Ops ownership wording and may land in the same implementation slice * #128 supplies the final conditional QA fixture-verification wording and may land in the same implementation slice

coilyco-ops referenced this issue

2026-07-29 04:39:40 +00:00

Ship executable external person-profile example and arbitrary-role vertical #122

coilyco-ops referenced this issue

2026-07-29 04:39:46 +00:00

Add effective-profile catalogue inspection commands #126

coilyco-ops referenced this issue

2026-07-29 04:39:47 +00:00

Add deterministic bundle export and content-aware diff #127

coilyco-ops referenced this issue

2026-07-29 04:41:07 +00:00

Adapt persona system to true use case #114

coilyco-ops referenced this issue

2026-07-29 04:41:08 +00:00

Run contract: complete the Agent Compose v1.x issue suite #115

coilyco-ops referenced this issue

2026-07-29 04:41:10 +00:00

Clarify engineer and Ops ownership when both can push code #116

coilyco-ops referenced this issue

2026-07-29 04:41:34 +00:00

Move authored prose and configuration out of Go #110

coilyco-ops referenced this issue

2026-07-29 04:41:38 +00:00

Split person profiles from composable personality libraries #111

coilyco-ops added the

priority

autonomy

headless

labels

2026-07-29 04:42:01 +00:00

coilyco-ops referenced this issue

2026-07-29 04:47:27 +00:00

Grant QA bounded verification-action authority #128

coilyco-ops commented

2026-07-29 05:10:01 +00:00

Author

Member

Landed on canonical main in cd99a44. All 12 canonical roles now have role- SKILL.md sources with stable ids and provenance digests. Native startup uses a compact identity card and loads the selected role skill before the personality meld. Compiled delivery includes the complete role doctrine. Legacy inline briefings remain readable through an in-memory adapter. Verification: ward exec test and ward exec smoke passed. Measured startup reductions are 54% for the generated roster, 56% for the combined Claude startup surface, and 70% for an assigned Engineer bundle. Details: docs/role-skill-context-budget.md.

Landed on canonical main in cd99a44. All 12 canonical roles now have role-<slug> SKILL.md sources with stable ids and provenance digests. Native startup uses a compact identity card and loads the selected role skill before the personality meld. Compiled delivery includes the complete role doctrine. Legacy inline briefings remain readable through an in-memory adapter. Verification: ward exec test and ward exec smoke passed. Measured startup reductions are 54% for the generated roster, 56% for the combined Claude startup surface, and 70% for an assigned Engineer bundle. Details: docs/role-skill-context-budget.md.

coilyco-ops closed this issue

2026-07-29 05:10:19 +00:00

coilyco-ops referenced this issue

2026-07-29 06:30:33 +00:00

Run contract: complete the Agent Compose v1.x issue suite #115

coilyco-ops referenced this issue

2026-07-30 09:43:35 +00:00

Let Designer implement visual-only web UI changes #138