Composer Initiative Tools: List/Count and Create from Brief
COMPLETEDIntent— the specification (8,801 chars); the plan below decomposes it into work items. Click to expand.
# Composer Initiative Tools: List/Count and Create from Brief ## Desired outcome An operator should be able to remain in a Composer conversation and naturally perform workflows such as: * “How many initiatives do I have?” * “List the current initiatives.” * “Which initiatives are still active?” * “Draft an initiative brief for what we just discussed.” * “Create that as a new initiative.” For read requests, the Composer should obtain current initiative data rather than infer it from conversation history or page context. For creation requests, once the operator explicitly asks to create/save the initiative, the Composer should invoke the canonical Orchestrator initiative-from-brief workflow and return the resulting initiative identity and status. The conversational surface should therefore be able to move cleanly from discussion → brief drafting → explicit creation without requiring the operator to copy and paste the brief into the Initiatives UI. ## Rejected / deferred alternatives - This initiative does not attempt to expose the complete Orchestrator control plane to the Composer. Unless required by implementation mechanics, defer conversational tools for: - editing or revising existing initiatives - cancelling initiatives - submitting initiatives for planning - starting or controlling execution - manipulating work items - release planning - arbitrary Orchestrator mutations - sophisticated initiative search/filter/query syntax Those capabilities can be added deliberately as separate runtime tools after the read/write pattern established here has been exercised. ## Constraints - Do not add duplicate initiative database services. - Do not add a parallel Initiative Brief parser. - Do not bypass the canonical Orchestrator initiative-from-brief endpoint. - Do not move Orchestrator-specific business logic into the shared Composer UI component. - Do not let model-supplied scope replace authenticated server-derived scope. - Keep the initial read surface focused on reliable initiative enumeration/counting rather than designing a general-purpose initiative query language. ## Repository scope - `Xyence/workspaces` - `Xyence/orchestrator` only if a small controller-side change is demonstrably required to expose an existing operation safely; do not duplicate APIs or domain behavior already present there. ## Expected behavior - Add a `list_initiatives` runtime tool — Expose an agent-callable, read-only tool for retrieving initiatives visible to the current authorized Orchestrator workspace context. The implementation should reuse the existing Workspaces/Orchestrator initiative read path. The result should be structured for reliable model use and include at minimum: - authoritative total initiative count - initiative ID - title - lifecycle/status information already returned by the canonical initiative list - any other existing canonical summary fields useful for distinguishing initiatives The tool must support both: - listing initiatives, and - answering count questions without requiring the model to estimate or derive a count from incomplete conversational context. Do not create a separate count endpoint merely for this use case unless an actual scale/performance requirement makes it necessary. The count can initially be derived authoritatively from the complete canonical list returned by the existing service. - Add a `create_initiative_from_brief` runtime tool — Expose an agent-callable mutation tool that creates a new initiative from Initiative Brief markdown. It should use the existing canonical initiative-from-brief workflow rather than directly inserting an initiative row. Creation must preserve the behavior of the existing canonical operation, including: - parsing the Initiative Brief - creating the initiative - creating and committing the brief revision - carrying repository scope/context into the initiative where applicable - returning validation failures - returning/reporting unrecognized brief headings rather than silently discarding content The tool result should include enough structured information for the Composer to confirm successful creation, including at minimum: - initiative ID - title - resulting initiative status - committed brief revision/status - any warnings such as unrecognized headings Where practical, also return sufficient information for the UI to link or navigate to the newly created initiative. - Treat creation as an explicit mutation — Drafting a brief and creating an initiative are distinct actions. The runtime must not create an initiative simply because it generated Initiative Brief text. Examples: - “Draft an initiative brief” → produce the brief only. - “What would an initiative for this look like?” → produce/discuss a brief only. - “Create this as an initiative” → invoke the creation tool. - “Save that initiative” after a brief has been drafted → invoke the creation tool. Use the platform's existing mutation confirmation/authorization conventions where applicable. Do not introduce a Composer-specific permission model. - Preserve server-authoritative scope and authorization — Neither tool may trust model-supplied organization, workspace, user, or permission information. Authorization and scope must come from the authenticated server-side runtime/session context and the existing Orchestrator control-plane authorization path. A conversation must not be capable of reading or creating initiatives outside the initiatives available to the current user/workspace context merely by supplying different IDs or scope values in tool arguments. - Integrate tools into the conversational runtime — Register the tools where workspace-specific runtime capabilities are assembled so that the Orchestrator Composer can discover and invoke them. Do not embed Orchestrator business logic into the shared visual `Composer` component. The Composer remains a platform-owned input surface; workspace-specific tool availability belongs at the conversational runtime/capability boundary. Tool execution and results should participate in the existing conversation provenance model so an operator can tell when the assistant's answer was grounded by `list_initiatives` or resulted from an initiative-creation action. - Handle mutation retries safely — A failed/retried conversational turn must not accidentally create duplicate initiatives. Use the existing request/message idempotency mechanisms where they can safely cover tool execution. If they do not currently protect mutations performed inside a runtime turn, introduce the narrowest appropriate idempotency mechanism for `create_initiative_from_brief`. The system should be able to distinguish: - an unsuccessful create that may safely be retried, from - a create that succeeded but whose response was interrupted or lost. - Return actionable failures — Tool failures should be represented structurally to the runtime rather than reduced to generic prose. At minimum distinguish: - authorization/permission denial - invalid Initiative Brief or controller validation failure - controller/service failure - ambiguous creation result where the controller may have accepted the write The assistant should be able to explain the failure without inventing a result or encouraging a blind retry that could duplicate an initiative. - Asking the Orchestrator Composer “How many initiatives are there?” causes it to invoke `list_initiatives` and return the exact current count. - Asking it to list initiatives produces information based on the live canonical initiative list rather than conversation history. - An empty initiative collection correctly returns a count of zero. - The list tool observes the same authorization and workspace scope as the existing Orchestrator UI. - Asking the Composer only to draft an Initiative Brief does **not** create an initiative. - After a brief has been drafted, an explicit request such as “Create that initiative” invokes `create_initiative_from_brief`. - Successful creation produces an actual Orchestrator initiative with a committed Initiative Brief using the existing canonical creation path. - The assistant receives and reports the created initiative ID/title and resulting brief status. - Validation errors and unrecognized headings remain observable. - Unauthorized creation is refused by the existing authorization boundary. - Retrying a turn after an uncertain transport/runtime failure does not create duplicate initiatives. - A newly created initiative is visible on the subsequent `list_initiatives` call. - Tool invocation/provenance is visible through the existing conversation-runtime provenance mechanism. - Automated tests cover empty and populated lists, count accuracy, successful creation, validation failure, authorization denial, creation warnings, and retry/idempotency behavior.
Repository scope
targets the work spans — independent of where the brief was authoredPrimary repository: outshine` — the conversational runtime and its capability registry (`app
- outshine` — the conversational runtime and its capability registry (`appexpected · primary
- workspaces` — the client and the operator-facing surface: the runtime client (`packagesexpected
- orchestrator` only if a canonical route is demonstrably missing. The reads this revision adds are already served under `expected
- workspaces`expected
- orchestrator` only if a small controller-side change is demonstrably required to expose an existing operation safely; do not duplicate APIs or domain behavior already present there.expected
- outshinediscovered
- workspacesdiscovered
brief revision 2 assessed as delivered
assessed with 72% confidenceWave-1 goals — enumerate/count initiatives from live Orchestrator data and explicitly create a new initiative from an Initiative Brief — are present, server-authoritative, and integrated into the conversational runtime with confirmation, idempotency, provenance, and UI wiring. list_initiatives is registered in the outshine runtime and returns an authoritative total count and canonical list under current workspace authorization; the workspaces client renders groundedCount (including zero) and citations from provenance. create_initiative_from_brief is a mutate-mode capability that never runs inline: it’s parked for explicit confirmation, re-authorizes at confirm, dispatches to the canonical from-brief endpoint with an Idempotency-Key, and returns structured outcomes with initiative id/title/status, committed brief revision info, warnings (e.g., unrecognized headings), and a link where available. Both tools draw scope only from the authenticated server context (minted service JWT) and are registered in the correct repository (outshine), with no parallel parser or duplicate data services, and no Orchestrator business logic moved into the shared Composer UI. Tests and client wiring in workspaces show count rendering (including 0), receipt linking, warning normalization, and structured failure handling. Additional in‑initiative read tools and two answer mutations were delivered but are later-scope; their presence does not block Wave‑1 delivery.
Plan waves — 3 approved waves
planning closed- Wave 1foundation-firstAPPROVED3 work items
Enable Composer to enumerate initiatives (with an authoritative count) and create a new initiative from an Initiative Brief, via registered runtime tools in Xyence/outshine and light client-side plumbing in Xyence/workspaces. No Orchestrator controller changes expected; tools must call existing canonical Orchestrator routes and honor server-side auth/scope and idempotency.
Deferred scope
- In-initiative reads (work items, planning waves, planning status/closure, continuation checkpoint, deferred scope entries, questions, brief revisions history) — Explicitly out of Wave 1 per brief; requires additional runtime tools and citation patterns. (unblocks: Ship and validate list_initiatives and create_initiative_from_brief tools with tests; confirm operator preference on single composite vs several narrow in-initiative read tools.) · deferred (not yet filed)
- Conversational mutations beyond creation (e.g., answering a continuation decision, answering an open question) — The brief calls these out as candidates but not in Wave 1; requires product authorization posture decision for chat-surface mutations. (unblocks: Operator decision on which mutations belong in conversation, with security/authorization sign-off; runtime patterns proven by creation tool.) · deferred (not yet filed)
- Citations for planning artifacts without standalone pages (e.g., deferred-scope entries, continuation checkpoints) — Needs a UX/content decision on how to cite non-page artifacts so operators can verify grounding. (unblocks: Design/UX decision on citation format for non-page artifacts; inventory of canonical identifiers those artifacts expose.) · deferred (not yet filed)
Continuation checkpoint: Proceed to in-initiative read tools and any additional conversational mutations once: (1) both tools are shipped with tests and proven idempotent; (2) an operator decision confirms whether in-initiative reads should be delivered as one composite tool or several narrow ones; and (3) a UX decision exists for citing planning artifacts without standalone pages. · decided: Several narrow tools, not one composite. 1) Citations. The conversation cites what it consulted, and a composite returns one blob that cites as a single undifferentiated read — so an answer drawn from planning status and one drawn from work items look identically sourced. That is precisely the failure that prompted this scope: asked about an open question, the Composer answered from the initiative brief and reported it accurately, and nothing in the citation revealed it had consulted the wrong artifact. Narrow tools make the citation name the read the answer actually stood on. 2) Authorization. Each tool is separately grantable. Reading an initiative's work items and reading its planning status are different exposures; a composite forces one grant covering everything. 3) Cost. A question about work items should not pull waves, planning status, the brief and the questions. The composite's one real advantage — fewer round trips for a question spanning several reads — is the rarer case, and the model can make two calls. Accepted cost: a question like "why is this initiative held?" genuinely spans planning status, questions and work items, and will take two or three calls. That is the right trade against making every simple question expensive. Citation approach for planning artifacts without standalone pages: cite the containing page plus the artifact's own identity. Link to the page that renders it — the initiative or the wave — and label it with the key the controller already uses: a deferred-scope entry by its `capability` (the stable key the defer-and-file route keys on), a continuation checkpoint by its wave. So "deferred scope: Images/media for Articles" or "wave 3 continuation checkpoint", each linking to the page where that entry is visible. A citation's job is to let the operator verify the claim, and a link that lands on the page showing the entry does that. Do NOT mint synthetic ids or invent anchors for artifacts the controller does not address individually — that would have the workspace manufacturing identifiers the API does not have, which is the one thing this codebase consistently refuses to do. If the citation format proves inadequate once the first read tool ships and there is something real to cite, revisit it then rather than designing further in the abstract. - Wave 2foundation-firstAPPROVED7 work items
Wave 2 will add narrow, server-authoritative in-initiative read tools to the Composer runtime (in OutShine) and wire their provenance/citations and types in Workspaces. We will implement separate tools for: planning status, work items, planning waves, questions, deferred scope entries, and brief revisions. Each tool calls the existing canonical Orchestrator reads and participates in the runtime’s provenance model. Citations for artifacts without standalone pages will link to the containing initiative/wave page and label the artifact with the controller’s own identity (e.g., deferred scope by capability; continuation checkpoint by wave), per the operator decision. No Orchestrator controller changes are planned.
Deferred scope
- Conversational mutations beyond creation (e.g., answering a continuation decision, answering an open question) — Requires operator decision on which mutations belong in conversation and security/authorization sign-off; mutations are explicitly deferred by the brief. (unblocks: All new in-initiative read tools shipped with tests and telemetry; operator decision captured approving one or more mutations to implement next.) · deferred (not yet filed)
Continuation checkpoint: Proceed to Wave 3 when all Wave 2 tools are merged and validated in staging with provenance/citations visible; then obtain operator decision on which, if any, conversational mutations beyond creation should be implemented next (answering a continuation decision, answering an open question). · decided: Enable exactly two mutations, both of them answers to questions the system itself asked: answering a continuation decision, and answering an open question. Nothing else. Not approving or discarding a wave, not closing or force-closing planning, not cancelling an initiative, not retracting or waiving deferred scope. Those are scope-losing or state-advancing decisions where a conversational surface adds real risk and little convenience — the operator is already on the page that offers them, with the context that makes them judgeable. The two being enabled are different in kind: the controller has posed a specific question, it is holding for an answer, and the operator is in a conversation where they are discussing precisely that. The mutation records their words against a question already asked. Security and authorization: use the confirmation handshake OutShine already built for this (outshine#418), which was explicitly left waiting for its first real mutating tool — 'confirming an operation records the confirmation and marks it resolved, but does not execute a real capability; a later item dispatches the confirmed operation to a real capability handler.' This is that item. Do not build a second path. The properties that matter, in order: 1. NO MUTATION EXECUTES ON MODEL JUDGMENT. The tool call parks a pending operation; only an explicit human confirm resolves it. This is the load-bearing control, and not only for mistakes: a conversation carries text from sources the operator does not author — brief content, issue bodies, work-item descriptions pulled in by the very read tools wave 2 just shipped. Anything that can induce the model to call a mutation is stopped by a human having to confirm the exact payload. 2. THE OPERATOR CONFIRMS THE VERBATIM TEXT. The confirmation shows the exact answer that will be recorded, and that text is what is sent. The model may draft, but a draft the operator has not read and approved is never recorded. It must also never decide that an answer is due. 3. RE-AUTHORIZE AT CONFIRM TIME, not at propose time. #418 already does this — the workspace grant is re-checked from persisted grants when the confirmation lands, so a grant revoked mid-conversation takes effect. Authorization delegates to the existing permission engine; no parallel authz store. 4. THE CANONICAL ROUTE DECIDES. Dispatch to POST /orchestrator/initiatives/:id/planning-waves/:waveId/continuation-decision and POST /orchestrator/initiatives/:id/questions/:questionId/answer. These are admin-tier with a server-derived actor (ADR-0007), they already refuse an answer that is not owed, and they are idempotent on requestId. The tool must not pre-judge those refusals or paper over them: a refusal renders verbatim, as everywhere else. 5. PROVENANCE IS DURABLE. Every request and confirmation is recorded with the conversation it came from, so an answer on the timeline can be traced to the exchange that produced it. An answer that arrived through a chat surface should be as auditable as one typed into the panel, and visibly so. One thing to watch, and to report back rather than solve by guessing: the operator experience of confirming a 2,000-character answer inside a conversation. If confirmation turns into scrolling a wall of text nobody reads, the control is theatre. If that is how it feels in practice, hand the composed text to the initiative page's own field for review there instead — the mutation is the same, and the confirmation happens where the operator can see what it applies to. - Wave 3completeAPPROVED2 work items
Wave 3: Enable exactly two conversational mutations — answering a continuation decision and answering an open question — via the existing OutShine confirmation handshake and canonical Orchestrator routes. Tools must not execute on model judgment; they create confirmable operations, re-authorize at confirm time, dispatch to the controller with idempotency, and record durable provenance. Light client/runtime wiring in Workspaces ensures operators see and confirm the exact text and provenance.
Work items
| # | Title | Repository | State | Issue | PR / CI | Review | |
|---|---|---|---|---|---|---|---|
| w2·0 | Register get_initiative_planning_status tool and add citation helper for planning artifacts | outshine | COMPLETED | #521 | #527merged · CI passed | c1: approve | |
| w1·0 | Register new runtime tool: list_initiatives (authoritative list + count via canonical Orchestrator list) | outshine | COMPLETED | #517 | #519merged · CI passed | c1: approve | |
| w3·0 | Composer runtime: Add confirmable mutations for answering continuation decisions and initiative questions via canonical Orchestrator routes | outshine | COMPLETED | #533 | #534merged · CI passed | c1: approve | |
| w3·1 ⛓ | Workspaces runtime/client: Wire confirmation UX and types for the two new initiative-answer mutations | workspaces | COMPLETED | #222 | #223merged · CI passed | c1: approve | |
| w1·1 ⛓ | Register new runtime tool: create_initiative_from_brief (canonical initiative-from-brief workflow with idempotency) | outshine | COMPLETED | #518 | #520merged · CI passed | c1: approve | |
| w2·1 ⛓ | Register get_initiative_work_items tool (narrow read) | outshine | COMPLETED | #522 | #528merged · CI passed | c1: approve | |
| w2·2 ⛓ | Register get_initiative_planning_waves tool (narrow read) | outshine | COMPLETED | #523 | #529merged · CI passed | c1: approve | |
| w1·2 ⛓ | Client/runtime plumbing: normalize citations and types for new initiative tools (no business logic) | workspaces | COMPLETED | #210 | #213merged · CI passed | c1: approve | |
| w2·3 ⛓ | Register get_initiative_questions tool (narrow read) | outshine | COMPLETED | #524 | #530merged · CI passed | c1: approve | |
| w2·4 ⛓ | Register get_initiative_deferred_scope tool (narrow read) | outshine | COMPLETED | #525 | #531merged · CI passed | c1: approve | |
| w2·5 ⛓ | Register get_initiative_brief_revisions tool (narrow read) | outshine | COMPLETED | #526 | #532merged · CI passed | c1: approve | |
| w2·6 ⛓ | Client/runtime wiring for new in-initiative reads and citation normalization | workspaces | COMPLETED | #220 | #221merged · CI passed | c1: approve |
Release candidate
- 1 question(s) still open
Release planning
Releases are cut in the Release planning section. Associating this initiative requires an admin role.
Associating an initiative to a release only records the link — it never changes the initiative’s own state or work. Releases are optional.
Questions
agent:openai · 8/19/2026, 6:55:30 PM
Every work item is complete, but the brief assessment could not verify any of its 2 criteria — it was not shown the full content of the delivered work. Is this initiative done?
The core runtime tools and server-side behavior appear to be in place: list_initiatives is registered and returns an authoritative list and count under server-authoritative scope (#517); create_initiative_from_brief is a confirm-only, canonical mutation with idempotency, structured failures, warnings, and a link to the new initiative (#518), and the client surfaces provenance, grounded counts (including zero), links, and warnings (workspaces #210). Server authorization is preserved and never taken from model input, and mutations are idempotent and confirmed, not inferred. Beyond Wave‑1, the Wave‑2 in‑initiative reads (planning status, work items, waves, questions, deferred scope, brief revisions) and Wave‑3 answer mutations (continuation decisions and initiative questions) are also registered and integrated (#521–#526, #533), with confirm/verbatim UX wired in the client (#222). What is not shown end‑to‑end is the Composer’s natural‑language triggering of list/count: the brief’s user‑visible behavior requires that asking “How many initiatives are there?” or “List the initiatives.” causes an invocation of list_initiatives and returns the exact current count based on live data. The repository evidence proves the tool exists, is registered, and its results are rendered, but it does not demonstrate the model/provider policy reliably invoking the tool from those NL prompts. Given the bounded evidence and omitted test contents, this acceptance remains partial pending an explicit prompt→tool invocation proof. Everything else in scope is covered by delivered capabilities and client wiring. Every criterion came back "cannot confirm" rather than "not done", and the delivered work exceeded the evidence budget, so the diff content of 1 completed item was withheld from the assessment (their changed-file lists were shown, but not their content) — so this is an unverified verdict, not an adverse one. Check the delivered work yourself before waiving anything: waiving records each criterion as a gap you accepted, and if the work is in fact complete that is a false record. Criteria the assessment could not confirm: - NL-to-tool behavior for count/list prompts (Composer invokes list_initiatives on questions like “How many…?”) — The brief requires that asking the Composer causes it to invoke list_initiatives and return the exact count. The repo shows the tool is registered and UI renders groundedCount, but provided evidence does not conclusively show prompt→tool invocation policy/tests (content for #517 tests was omitted). - Empty initiative collection returns a count of zero (authoritatively) — Workspaces #210 renders groundedCount: 0 distinctly; list_initiatives is designed to carry total counts. End-to-end prompt→tool tests for the empty case were not visible in the bounded evidence.
Timeline
No events yet.