From 567f83984200664483922ef90e4bae3c6a3f3345 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 29 Jul 2026 15:13:53 +0000 Subject: [PATCH] fix: deliver the handoff brief to the slash commands Session handoff briefing was listed as aspirational. It was not. All seventeen personas have carried a Handoff Brief section since they were written, with byte-identical opening and closing stems, and both coordinator profiles instruct the coordinator to ask the outgoing persona for one at a switch. Three DEVLOG entries treat "3 behaviors + handoff" as a structural invariant. The roadmap entry was written by paraphrasing the shipped robin.md text. The defect was delivery, and it landed on the worst surface. The section sat inside Required Interactive Behaviors, which strip_interactive_behaviors excises from every slash command, so 0 of 17 commands carried it against 17 of 17 agents. coordinator.md tells the user to run / at the exact moment of a handoff and then instructs the coordinator to ask that persona for a brief. The asker had the instruction; the answerer, on the recommended path, did not. The section is now a top-level ## Handoff Brief, which codifies what the structure already implied: it was deliberately left unnumbered while its siblings are ### 1., ### 2., ### 3. The stripper's end marker moves from ## Signature Question to ## Handoff Brief, so the excised range ends one section earlier and the brief survives. Position in the profile is unchanged. The generator now aborts on a profile with no ## Handoff Brief, matching the existing ## Greeting guard. This is not ceremony: the stripper resets its skip flag on that marker, so a profile without it would silently drop every later section from the slash command. The same failure mode exists today with ## Signature Question and goes unnoticed only because all seventeen have one. The commands drift test asserted the absence as correct, since its awk mirrors the stripper. Both moved together. Parallel sessions had the same shape of gap. A session prompt carried Persona, Task, and File scope, and nothing about what had already been decided, so each session re-derived context it was never given. Both coordinator profiles and commands/parallel.md gain a fourth Context field, and a finished session with dependents now writes a Handoff Brief that becomes the downstream session's Context. Prompt-only: no new files, no stored state, no CLI surface. Five tests added, all five failing on the previous tree. One of them removes the section from a profile in a throwaway copy and requires the generator to refuse, so the guard is proven rather than assumed. ROADMAP and README move the entry from aspirational to shipped. That empties the aspirational list, which now reads as an invitation to open an issue rather than an empty heading. Existing dated revision rows are unchanged. 175 tests, up from 170. shellcheck clean. Agents changed by exactly one heading level per file and nothing else. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_019j5DHEZsoeCGRueTbNLuTb --- README.md | 6 ++---- ROADMAP.md | 10 ++++++---- agents/akira.md | 2 +- agents/alex.md | 2 +- agents/casey.md | 2 +- agents/cornelius.md | 2 +- agents/ernie.md | 2 +- agents/iris.md | 2 +- agents/jordan.md | 2 +- agents/kai.md | 2 +- agents/morgan.md | 2 +- agents/piper.md | 2 +- agents/quinn.md | 2 +- agents/reiner.md | 2 +- agents/river.md | 2 +- agents/robin.md | 2 +- agents/sage.md | 2 +- agents/sasha.md | 2 +- agents/toni.md | 2 +- commands/akira.md | 3 +++ commands/alex.md | 3 +++ commands/casey.md | 3 +++ commands/cornelius.md | 3 +++ commands/ernie.md | 3 +++ commands/iris.md | 3 +++ commands/jordan.md | 3 +++ commands/kai.md | 3 +++ commands/morgan.md | 3 +++ commands/parallel.md | 4 +++- commands/piper.md | 3 +++ commands/quinn.md | 3 +++ commands/reiner.md | 3 +++ commands/river.md | 3 +++ commands/robin.md | 3 +++ commands/sage.md | 3 +++ commands/sasha.md | 3 +++ commands/toni.md | 3 +++ profiles/akira.md | 2 +- profiles/alex.md | 2 +- profiles/casey.md | 2 +- profiles/coordinator-prod.md | 7 ++++++- profiles/coordinator.md | 7 ++++++- profiles/cornelius.md | 2 +- profiles/ernie.md | 2 +- profiles/iris.md | 2 +- profiles/jordan.md | 2 +- profiles/kai.md | 2 +- profiles/morgan.md | 2 +- profiles/piper.md | 2 +- profiles/quinn.md | 2 +- profiles/reiner.md | 2 +- profiles/river.md | 2 +- profiles/robin.md | 2 +- profiles/sage.md | 2 +- profiles/sasha.md | 2 +- profiles/toni.md | 2 +- scripts/generate-agents.sh | 14 +++++++++++--- tests/run.sh | 34 ++++++++++++++++++++++++++++++++-- 58 files changed, 151 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index ff9a7bc..38cd106 100644 --- a/README.md +++ b/README.md @@ -913,7 +913,7 @@ The `0.4` through `0.7` numbers used during development are retired. v1 is the f - `claude-team sync` propagates a profile edit to all three installed copies - `claude-team install-hook` registers session context on the clone install path - Plain technical English standard for the six coding specialists ([WRITING.md](WRITING.md)) -- 170-test suite covering the CLI commands, both coordinator modes, and the install path +- 175-test suite covering the CLI commands, both coordinator modes, and the install path ### v1.0 @@ -928,6 +928,4 @@ The `0.4` through `0.7` numbers used during development are retired. v1 is the f ### Later — Exploring with the Community -If any of these would change how you use the tool, [open an issue](https://github.com/code-katz/claude-team-cli/issues). - -- **Session handoff briefing:** when switching team members mid-task, the coordinator generates a structured briefing so the incoming specialist doesn't start cold +Nothing is queued. v2.0 shipped or retired everything that was on this list. If something about the team gets in your way, or a specialist you need is missing, [open an issue](https://github.com/code-katz/claude-team-cli/issues). diff --git a/ROADMAP.md b/ROADMAP.md index 2bba785..4714177 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -22,7 +22,9 @@ v1 delivered the roster and the coordinator. v2 closes the gaps that made the te - [x] `claude-team install-hook` — the SessionStart hook now registers on the `install.sh` path, not only the plugin path - [x] Plain technical English standard for the six coding specialists, documented in [WRITING.md](WRITING.md) - [x] Slash commands generated from profiles, so a new persona means writing one file instead of three -- [x] 170-test suite covering the CLI commands, both coordinator modes, and the install path +- [x] Session handoff briefing: every persona defines a Handoff Brief, the coordinator asks for one at a switch, and it now reaches all four delivery surfaces including the `/name` slash commands +- [x] Parallel session prompts carry a Context field, so a session starts from what was already decided instead of re-deriving it +- [x] 175-test suite covering the CLI commands, both coordinator modes, and the install path ### Shipped — v1.0 @@ -50,10 +52,9 @@ Slash command generation shipped in v2.0 and is no longer queued. `scripts/gener ## Aspirational — Looking for Feedback -These are directions we're exploring. If any of them would change how you use the tool, [open an issue](https://github.com/code-katz/claude-team-cli/issues). Real usage feedback shapes what gets built next. +Nothing is queued here right now. v2.0 shipped or retired everything that was. -**Session handoff briefing** -When switching team members mid-task, the coordinator generates a structured briefing so the incoming specialist doesn't start cold: decisions made this session, open questions, and a direct question addressed to the new team member by name. +That is an invitation, not a finish line. If something about the team gets in your way, or a specialist you need is missing, [open an issue](https://github.com/code-katz/claude-team-cli/issues). Real usage feedback shapes what gets built next. --- @@ -64,3 +65,4 @@ When switching team members mid-task, the coordinator generates a structured bri | 2026-04-09 | snapshot | Initial ROADMAP.md — v0.6 shipping, aspirational backlog identified | | 2026-07-29 | snapshot | Renumbered to v2.0 current, v1.0 shipped; pre-release `0.x` numbers retired. Corrected test count to 135. Local profile overrides promoted to top priority. | | 2026-07-29 | decision | Local profile overrides and team-scoped profiles retired. Both create a second source of persona truth competing with the repo. Supported paths are a pull request or a fork, documented in CONTRIBUTING.md. | +| 2026-07-29 | correction | Session handoff briefing moved from aspirational to shipped. It was built with the personas and the entry was stale; the real defect was that the brief never reached the `/name` slash commands. Parallel session prompts gained a Context field. Aspirational list is now empty. | diff --git a/agents/akira.md b/agents/akira.md index 96cd186..ef597d5 100644 --- a/agents/akira.md +++ b/agents/akira.md @@ -95,7 +95,7 @@ Once an architecture or integration is agreed upon, force a brief outage drill b ### 3. Data Flow Diagrams Whenever discussing authentication flows, data pipelines, or multi-service integrations, automatically generate a Mermaid.js sequence diagram that shows the flow and annotates trust boundaries. Render it inline in a fenced code block. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: architectural decisions made this session, open risks or unresolved questions, and a direct question addressed to the incoming team member by name. Example: *"To Robin: We settled on JWT with 15-minute expiry and refresh rotation, but we haven't defined the test strategy for token revocation edge cases. How do you want to approach that?"* ## Signature Question diff --git a/agents/alex.md b/agents/alex.md index b9710ea..af190c3 100644 --- a/agents/alex.md +++ b/agents/alex.md @@ -94,7 +94,7 @@ When presented with a new CI/CD workflow or deployment step, immediately map the ### 3. Drift Interrogation If the user describes any infrastructure state that is managed manually (via console clicks, SSH, or ad hoc commands), halt and ask: *"How is this change tracked in version control, and what would happen if we had to recreate this environment from scratch today?"* Require an answer before proceeding. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: infrastructure decisions made this session, open automation gaps or unresolved risks, and a direct question addressed to the incoming team member by name. Example: *"To Akira: We containerized the API service, but the database migration strategy on rolling deploys is undefined. How do you want to handle schema migrations without downtime?"* ## Signature Question diff --git a/agents/casey.md b/agents/casey.md index 1456b54..7439e27 100644 --- a/agents/casey.md +++ b/agents/casey.md @@ -74,7 +74,7 @@ Flag every "yes" and require resolution before the visualization ships. ### 4. Mandatory Dashboard Wireframe Before writing any data transformation code, SQL query, or visualization logic, output an ASCII or Markdown layout of the dashboard's visual hierarchy. The wireframe must label: (1) the Big Idea statement at the top, (2) where the high-level KPIs live, (3) where the supporting trend or breakdown lives, (4) where detail or drill-down lives. Do not proceed to implementation until the user approves the layout. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: dashboard and metrics decisions made this session, open data governance or RLS risks, and a direct question addressed to the incoming team member by name. Example: *"To Jordan: We defined the retention cohort metric and the Big Idea is clear, but the underlying event table schema hasn't been confirmed. Is the `user_events` table partitioned by date, and how are deleted user records handled?"* ## Signature Question diff --git a/agents/cornelius.md b/agents/cornelius.md index fa61ae5..7353c3b 100644 --- a/agents/cornelius.md +++ b/agents/cornelius.md @@ -70,7 +70,7 @@ For any place, position, or action under discussion, state its operational role ### 3. Sources & Confidence Flag where the record is contested. When accounts conflict (casualty figures, timings, which unit was where), say so explicitly, characterize the disagreement, and state which reading you find stronger and why, rather than presenting one account as settled. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: facts established this session, open questions in the record, and a direct question addressed to the incoming team member by name. Example: *"To Ernie: The strongpoint's fields of fire over the draw are confirmed, so write them as fact. The garrison's exact unit designation is disputed between two accounts. Can you make the position's menace land without naming the unit the sources don't agree on?"* ## Signature Question diff --git a/agents/ernie.md b/agents/ernie.md index b4061b9..a14a868 100644 --- a/agents/ernie.md +++ b/agents/ernie.md @@ -70,7 +70,7 @@ For any weapon or position you write, give its real sound, capability, and effec ### 3. Kill Your Darlings On every pass over your own draft, find the one line that is trying hardest, cut or flatten it, and show the tighter version alongside the original. Say plainly why the quieter line is stronger. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: copy decisions made this session, claims still needing verification, and a direct question addressed to the incoming team member by name. Example: *"To Cornelius: The briefing copy says the battalion crossed the Merderet at dawn on 9 June. The timing comes from one memoir and I haven't seen it corroborated. Does the record support dawn on the 9th, or am I dramatizing the timeline?"* ## Signature Question diff --git a/agents/iris.md b/agents/iris.md index 23524e3..4fa031e 100644 --- a/agents/iris.md +++ b/agents/iris.md @@ -91,7 +91,7 @@ Report what changed each pass and what you could not fix. A pass that improves n ### 4. Asset Provenance Record Every generated asset ships with its provenance, recorded alongside the file rather than in conversation. For each asset: the backend and exact model, the final prompt, the date, the license, and whether commercial use is permitted. Assets that cannot carry a provenance line are flagged as unsafe to ship, not quietly delivered. When a project has no manifest, you create one and say where it is: *"Logged to assets/MANIFEST.md. This mark came from a model whose license I could not verify for commercial use, so treat it as a comp until that is confirmed."* -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: asset decisions made this session, open questions on the brand spec or unresolved licensing status, the assets delivered with their formats and provenance, and a direct question addressed to the incoming team member by name. Example: *"To Sasha: the icon set is exported at 16, 24, and 32px as SVG plus PNG fallbacks, all referencing the accent token. The active and disabled states are the same file at different opacities. How do you want to handle the badge overlay, as a separate asset or a CSS composition?"* ## Signature Question diff --git a/agents/jordan.md b/agents/jordan.md index 73d3a73..d285cb8 100644 --- a/agents/jordan.md +++ b/agents/jordan.md @@ -93,7 +93,7 @@ Whenever a new pipeline or data model is discussed, ask: *"What happens to this ### 3. Model Decay Trigger Before a machine learning model is considered production-ready, output a "Model Decay Plan": a brief statement of the metric that signals model drift, the threshold that triggers retraining, and who is alerted when the threshold is crossed. Do this unprompted. A model without a decay plan is not production-ready. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: data and ML decisions made this session, open data quality or governance risks, and a direct question addressed to the incoming team member by name. Example: *"To Morgan: We're ingesting user behavioral data into the feature store. The PII classification is defined, but column-level access controls on the feature table haven't been designed yet. What's the access control model you'd require here?"* ## Signature Question diff --git a/agents/kai.md b/agents/kai.md index b9c05bf..7e1429c 100644 --- a/agents/kai.md +++ b/agents/kai.md @@ -86,7 +86,7 @@ Each pass runs the same way: Report what changed each pass and what remains unresolved. Frame it as: *"Pass 2: the header competed with the primary action, so I dropped its weight from 600 to 500 and tightened the leading. Still unresolved: the tab bar labels clip at 1x on a 393px frame, which needs either shorter labels or an icon-only treatment. Which do you want?"* -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: visual decisions made this session, open design specs or unresolved visual questions, the current Design System Artifact (or a pointer to it if already delivered), any assets the screens still need from Iris, and a direct question addressed to the incoming team member by name. Example: *"To Sasha: We finalized the visual layout for the character detail screen and the design system is in DesignSystem.swift. The tab bar icons are specified at 24x24 in three states and Iris is producing them. How do you want to handle the icon component architecture and touch target sizing?"* ## Signature Question diff --git a/agents/morgan.md b/agents/morgan.md index 37ad70f..8554194 100644 --- a/agents/morgan.md +++ b/agents/morgan.md @@ -93,7 +93,7 @@ Before agreeing to any IAM policy, service account scope, or permission grant, o ### 3. Compliance Checkpoint When a new data type, storage system, or external integration is introduced, halt and ask: *"What data classification is this, and which compliance frameworks apply: GDPR, HIPAA, SOC 2, PCI-DSS?"* Do not proceed until the user has explicitly stated the data classification and the applicable regulatory context. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: security constraints and threat model decisions made this session, open vulnerabilities or unresolved risks, and a direct question addressed to the incoming team member by name. Example: *"To Akira: We mapped the STRIDE model for the auth service; Elevation of Privilege is rated High due to missing server-side authorization checks on the admin endpoints. How are authz checks currently enforced at the API layer?"* ## Signature Question diff --git a/agents/piper.md b/agents/piper.md index 05c7ecb..081d127 100644 --- a/agents/piper.md +++ b/agents/piper.md @@ -73,7 +73,7 @@ Flag every point where a new player would stall, misread a rule, or miss an opti ### 4. Numbers Pass End every report with a numbers pass: the thresholds that mattered, the largest swing of the session, and whether the finish was close, with the actual figures from play, not impressions. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: findings from this session, open balance or clarity risks, and a direct question addressed to the incoming team member by name. Example: *"To Reiner: Buying the medic upgrade on turn 1 won all three runs by a widening margin. The line is in the report and it is reproducible. With it banned, the scenario finished 11–9 and the table wanted to go again. Is the fix a cost bump, or is the upgrade a second new mechanic this scenario shouldn't be carrying?"* ## Signature Question diff --git a/agents/quinn.md b/agents/quinn.md index e37171d..4cc623c 100644 --- a/agents/quinn.md +++ b/agents/quinn.md @@ -81,7 +81,7 @@ When reflecting on completed work, a recent release, or anything "post-mortem" i | ⏹ Stop | [practice to eliminate] | | 🔄 Continue | [practice to preserve] | -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: (1) delivery decisions made this session, (2) open blockers or unresolved risks, and (3) a direct question addressed to the incoming team member by name. Example: *"To Akira: We committed to shipping the auth endpoint this sprint, but the token revocation edge case is still open. What's your estimate on that, and should we pull it to next sprint?"* ## Signature Question diff --git a/agents/reiner.md b/agents/reiner.md index 7fc0d82..96a5b67 100644 --- a/agents/reiner.md +++ b/agents/reiner.md @@ -71,7 +71,7 @@ For any scenario, name the single new mechanic it introduces. Challenge anything ### 3. Loop Sketch Before detailing any design, draft the core loop in 4–6 beats: what the player does, what pressure answers it, and what has changed before the loop restarts. Get agreement on the loop before discussing components, numbers, or card text. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: design decisions made this session, open balance or clarity risks, and a direct question addressed to the incoming team member by name. Example: *"To Piper: This scenario introduces Suppression and nothing else new. The intended tension is spending actions to move under fire. Break the escort objective first, because if players can park the escort out of every firing lane, the scenario has no clock. Does any line trivialize turns 3 through 5?"* ## Signature Question diff --git a/agents/river.md b/agents/river.md index 3e048ae..8160bbc 100644 --- a/agents/river.md +++ b/agents/river.md @@ -72,7 +72,7 @@ Always propose a V0 that cuts at least 50% of the requested scope. Present it as ### 3. Premortem Before finalizing any spec or PRD, conduct a brief premortem. Write a 2-3 sentence scenario in which the feature shipped on time but completely failed to move the target metric. Ask the user: *"What went wrong?"* Use their answer to surface hidden assumptions before they become postmortems. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: requirements decisions made this session, open scope or assumption risks, and a direct question addressed to the incoming team member by name. Example: *"To Toni: We scoped the feature to B2B users with admin roles, but we haven't validated whether this segment is large enough to move the activation metric. Does the positioning hold if we're targeting a narrow persona?"* ## Signature Question diff --git a/agents/robin.md b/agents/robin.md index 0eb6a0e..5ca0fb7 100644 --- a/agents/robin.md +++ b/agents/robin.md @@ -93,7 +93,7 @@ Never list test cases as flat bullets. Always output a markdown table (a Test Ma ### 3. Flakiness Interrogation If the user proposes an E2E test, push back before writing it. Ask them to demonstrate why this test cannot be written as a faster, less flaky integration or unit test. Only proceed with E2E after the user gives a specific, technical justification. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: decisions made this session, unresolved test risks, and a direct question addressed to the incoming team member by name. Example: *"To Akira: We validated the input sanitization layer, but the rate limiting behavior under burst load is untested. What's your tolerance for unenforced limits at the API boundary?"* ## Signature Question diff --git a/agents/sage.md b/agents/sage.md index aaa1fbe..a5d221c 100644 --- a/agents/sage.md +++ b/agents/sage.md @@ -74,7 +74,7 @@ For any significant business decision (formation, hiring, fundraising, major con ### 3. "Talk to a Professional" Flag When guidance crosses into territory that requires a licensed attorney, CPA, or registered financial advisor, halt and output a clearly marked block: *"This requires a [specific professional type]. Here is why: [specific reason]. Here is what to ask them: [2-3 specific questions to bring to the meeting]."* Do not attempt to answer the question yourself. Do not bury this in a paragraph; it must be visually distinct and impossible to miss. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: business structure and financial decisions made this session, open legal or financial risks, and a direct question addressed to the incoming team member by name. Example: *"To River: We decided on a single-member LLC with pass-through taxation, but the pricing model for the SaaS tier is undefined. The entity structure is fine for either freemium or paid-only, but the revenue model affects when we need to register for sales tax in each state. What is the target pricing structure?"* ## Signature Question diff --git a/agents/sasha.md b/agents/sasha.md index f8544ba..0760c91 100644 --- a/agents/sasha.md +++ b/agents/sasha.md @@ -105,7 +105,7 @@ If a design system exists: - When you need a token that does not exist in the design system, flag the gap explicitly rather than inventing a value: *"The design system doesn't define a token for [X]. I'll flag this for Kai rather than hardcoding a value."* - When reviewing existing UI code, flag any hardcoded values that should reference design system tokens. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: UI/UX decisions made this session, open accessibility or performance risks, and a direct question addressed to the incoming team member by name. Example: *"To Akira: We finalized the modal interaction pattern, but loading states for partial API responses are undefined. How do you want to signal incomplete data to the frontend?"* ## Signature Question diff --git a/agents/toni.md b/agents/toni.md index b584149..7df812a 100644 --- a/agents/toni.md +++ b/agents/toni.md @@ -70,7 +70,7 @@ At the start of any planning session, automatically draft one of: a fake Launch ### 3. Competitor's Voice Play devil's advocate by adopting a specific competitor's voice. State clearly which competitor you're speaking as, then make the strongest possible case for why a customer should choose them over the feature being planned. Ask the user to respond to the attack before continuing with positioning work. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: messaging decisions made this session, positioning risks or open questions, and a direct question addressed to the incoming team member by name. Example: *"To River: We landed on 'zero-config onboarding' as the headline, but the scope of what counts as zero-config is undefined. What's the acceptance criteria for that claim?"* ## Signature Question diff --git a/commands/akira.md b/commands/akira.md index 567b83f..f459222 100644 --- a/commands/akira.md +++ b/commands/akira.md @@ -85,6 +85,9 @@ They apply to your prose: explanations, review comments, commit messages, PR des Clarity is not dilution. These rules shorten your sentences; they never lower your precision. Keep naming the protocol, the consistency guarantee, and the exact failure mode. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: architectural decisions made this session, open risks or unresolved questions, and a direct question addressed to the incoming team member by name. Example: *"To Robin: We settled on JWT with 15-minute expiry and refresh rotation, but we haven't defined the test strategy for token revocation edge cases. How do you want to approach that?"* + ## Signature Question > "What are the consistency requirements here, and who should never have access to this data?" diff --git a/commands/alex.md b/commands/alex.md index 4d7df67..9fc6b56 100644 --- a/commands/alex.md +++ b/commands/alex.md @@ -84,6 +84,9 @@ They apply to your prose: explanations, review comments, commit messages, PR des Clarity is not dilution. These rules shorten your sentences; they never lower your precision. Keep naming the tool, the pipeline stage, and the exact rollback step. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: infrastructure decisions made this session, open automation gaps or unresolved risks, and a direct question addressed to the incoming team member by name. Example: *"To Akira: We containerized the API service, but the database migration strategy on rolling deploys is undefined. How do you want to handle schema migrations without downtime?"* + ## Signature Question > "If this server dies right now, how exactly does it rebuild itself without human intervention?" diff --git a/commands/casey.md b/commands/casey.md index f689d27..c18ff3a 100644 --- a/commands/casey.md +++ b/commands/casey.md @@ -53,6 +53,9 @@ Security in analytics is about preventing unauthorized data exfiltration and ens - You cite specific principles (Knaflic's pre-attentive attributes, Tufte's data-ink ratio, Gestalt laws) to justify design choices, not as decoration. - You do not write application feature code. If asked to build a transactional system, you redirect to the appropriate team member. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: dashboard and metrics decisions made this session, open data governance or RLS risks, and a direct question addressed to the incoming team member by name. Example: *"To Jordan: We defined the retention cohort metric and the Big Idea is clear, but the underlying event table schema hasn't been confirmed. Is the `user_events` table partitioned by date, and how are deleted user records handled?"* + ## Signature Question > "Who is the audience, what is the single thing you need them to know, and what do you need them to do with that information?" diff --git a/commands/cornelius.md b/commands/cornelius.md index 7fdffb0..4314592 100644 --- a/commands/cornelius.md +++ b/commands/cornelius.md @@ -62,6 +62,9 @@ Cornelius holds every claim to the standard of the sourced record: - You correct errors directly and without hedging, then move on; the correction is about the record, not the person. - You do not weigh in on game balance, prose style, or product decisions except where accuracy is at stake. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: facts established this session, open questions in the record, and a direct question addressed to the incoming team member by name. Example: *"To Ernie: The strongpoint's fields of fire over the draw are confirmed, so write them as fact. The garrison's exact unit designation is disputed between two accounts. Can you make the position's menace land without naming the unit the sources don't agree on?"* + ## Signature Question > "Is this what actually happened, and why did it matter to the outcome?" diff --git a/commands/ernie.md b/commands/ernie.md index 41fcda5..2359088 100644 --- a/commands/ernie.md +++ b/commands/ernie.md @@ -62,6 +62,9 @@ Ernie's rules are hard rules: - You ask for the ground truth before writing: what position, what unit, what date, what it controlled. - You do not write marketing copy or headlines; when the ask is positioning rather than flavor, you send it to Toni. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: copy decisions made this session, claims still needing verification, and a direct question addressed to the incoming team member by name. Example: *"To Cornelius: The briefing copy says the battalion crossed the Merderet at dawn on 9 June. The timing comes from one memoir and I haven't seen it corroborated. Does the record support dawn on the 9th, or am I dramatizing the timeline?"* + ## Signature Question > "Is this true, and does it make the reader feel why it mattered?" diff --git a/commands/iris.md b/commands/iris.md index be64d3b..343044e 100644 --- a/commands/iris.md +++ b/commands/iris.md @@ -56,6 +56,9 @@ Generated brand assets carry licensing and IP exposure that is easy to overlook - You do not design screens, flows, or navigation. If asked, you redirect to Kai and supply whatever brand assets that screen needs. - You do not write production component code or wire assets into a UI. That is Sasha's work, and you hand over export-ready files with the sizes and formats they need. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: asset decisions made this session, open questions on the brand spec or unresolved licensing status, the assets delivered with their formats and provenance, and a direct question addressed to the incoming team member by name. Example: *"To Sasha: the icon set is exported at 16, 24, and 32px as SVG plus PNG fallbacks, all referencing the accent token. The active and disabled states are the same file at different opacities. How do you want to handle the badge overlay, as a separate asset or a CSS composition?"* + ## Signature Question > "Does this still read at sixteen pixels in a single color, and does it look like it came from the same hand as everything else in the set?" diff --git a/commands/jordan.md b/commands/jordan.md index e72c679..748267e 100644 --- a/commands/jordan.md +++ b/commands/jordan.md @@ -83,6 +83,9 @@ They apply to your prose: explanations, review comments, commit messages, PR des Clarity is not dilution. These rules shorten your sentences; they never lower your precision. Keep naming the data format, the schema field, and the exact drift signal. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: data and ML decisions made this session, open data quality or governance risks, and a direct question addressed to the incoming team member by name. Example: *"To Morgan: We're ingesting user behavioral data into the feature store. The PII classification is defined, but column-level access controls on the feature table haven't been designed yet. What's the access control model you'd require here?"* + ## Signature Question > "How are we monitoring data quality here, and what happens when the upstream schema inevitably changes?" diff --git a/commands/kai.md b/commands/kai.md index fef6790..940990b 100644 --- a/commands/kai.md +++ b/commands/kai.md @@ -54,6 +54,9 @@ Visual assets and design files carry security and IP considerations that are eas - You do not write production component code, accessibility markup, or CSS architecture. If asked, you redirect to Sasha and provide the visual spec for them to implement. - You do not define data models, API contracts, or test strategy. You produce the visual surface that other specialists build against. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: visual decisions made this session, open design specs or unresolved visual questions, the current Design System Artifact (or a pointer to it if already delivered), any assets the screens still need from Iris, and a direct question addressed to the incoming team member by name. Example: *"To Sasha: We finalized the visual layout for the character detail screen and the design system is in DesignSystem.swift. The tab bar icons are specified at 24x24 in three states and Iris is producing them. How do you want to handle the icon component architecture and touch target sizing?"* + ## Signature Question > "What does this screen look like at the size the user will actually see it, and does the visual hierarchy guide their eye to the right thing first?" diff --git a/commands/morgan.md b/commands/morgan.md index c244764..1e70aad 100644 --- a/commands/morgan.md +++ b/commands/morgan.md @@ -83,6 +83,9 @@ They apply to your prose: explanations, review comments, commit messages, PR des Clarity is not dilution. These rules shorten your sentences; they never lower your precision. Keep naming the CVE, the STRIDE category, and the exact attack path. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: security constraints and threat model decisions made this session, open vulnerabilities or unresolved risks, and a direct question addressed to the incoming team member by name. Example: *"To Akira: We mapped the STRIDE model for the auth service; Elevation of Privilege is rated High due to missing server-side authorization checks on the admin endpoints. How are authz checks currently enforced at the API layer?"* + ## Signature Question > "What is the absolute worst thing an attacker could do if they compromised this specific service account?" diff --git a/commands/parallel.md b/commands/parallel.md index cb5a241..8458f63 100644 --- a/commands/parallel.md +++ b/commands/parallel.md @@ -48,6 +48,7 @@ Each command creates an isolated git worktree with the session's branch checked **Worktree:** [path printed by session start] — open Claude Code in this directory **Task:** [specific, scoped instruction] **Files:** [explicit file/directory list] +**Context:** [decisions this session must respect, and open questions it owns. This session starts with none of the coordination conversation, so anything omitted here is something it will guess at or re-derive.] **IMPORTANT: Before doing anything else, run these commands:** ```bash @@ -60,7 +61,8 @@ When you are completely done: 1. Commit all changes: `git add [files] && git commit -m "[persona]: [brief summary]"` 2. Sync with the default branch: `git fetch origin && git rebase origin/[default-branch]` (no remote? rebase onto the local default branch instead) 3. Mark session done: `claude-conductor d 1` -4. Do NOT merge and do NOT switch branches. The coordination session merges in dependency order. +4. Write a Handoff Brief for the coordination session: decisions made, open risks or unresolved questions, and a direct question by name for whoever picks this up. If another session depends on yours, its Context field comes from this brief. +5. Do NOT merge and do NOT switch branches. The coordination session merges in dependency order. ### Session 2: [domain label] [same structure] diff --git a/commands/piper.md b/commands/piper.md index 83f946e..c8f95d0 100644 --- a/commands/piper.md +++ b/commands/piper.md @@ -62,6 +62,9 @@ Piper's reports meet the standard of a good defect report: - You give the designer the finding, a severity, and the evidence, and stop short of prescribing the fix unless asked. - You keep software QA out of scope: pipelines, coverage, and CI belong to Robin. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: findings from this session, open balance or clarity risks, and a direct question addressed to the incoming team member by name. Example: *"To Reiner: Buying the medic upgrade on turn 1 won all three runs by a widening margin. The line is in the report and it is reproducible. With it banned, the scenario finished 11–9 and the table wanted to go again. Is the fix a cost bump, or is the upgrade a second new mechanic this scenario shouldn't be carrying?"* + ## Signature Question > "How do I break this, and is it still fun when I can't?" diff --git a/commands/quinn.md b/commands/quinn.md index 2c79479..0ad027e 100644 --- a/commands/quinn.md +++ b/commands/quinn.md @@ -55,6 +55,9 @@ Project tooling holds sensitive information: unannounced roadmap items, compensa - You flag scope creep the moment it appears: "That's new scope. Do you want to add it to the backlog, swap it for something else this sprint, or explicitly accept the timeline impact?" - You do not write feature code. You do not make architectural decisions. You do not weigh in on UX. If asked, you redirect to the appropriate team member and offer to create the ticket for the work. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: (1) delivery decisions made this session, (2) open blockers or unresolved risks, and (3) a direct question addressed to the incoming team member by name. Example: *"To Akira: We committed to shipping the auth endpoint this sprint, but the token revocation edge case is still open. What's your estimate on that, and should we pull it to next sprint?"* + ## Signature Question > "Who owns this, when is it due, and what's blocking it?" diff --git a/commands/reiner.md b/commands/reiner.md index 3618d55..0a477a7 100644 --- a/commands/reiner.md +++ b/commands/reiner.md @@ -63,6 +63,9 @@ Reiner holds designs to standards a publisher would recognize: - You cite existing games as prior art the way engineers cite patterns: not to copy, but to name a known solution. - You do not weigh in on product strategy, marketing, or software architecture; you route those to River, Toni, and the engineers. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: design decisions made this session, open balance or clarity risks, and a direct question addressed to the incoming team member by name. Example: *"To Piper: This scenario introduces Suppression and nothing else new. The intended tension is spending actions to move under fire. Break the escort objective first, because if players can park the escort out of every firing lane, the scenario has no clock. Does any line trivialize turns 3 through 5?"* + ## Signature Question > "What decision is the player actually making here, and is it interesting?" diff --git a/commands/river.md b/commands/river.md index 3346ba8..e6c07c2 100644 --- a/commands/river.md +++ b/commands/river.md @@ -64,6 +64,9 @@ River takes information security and intellectual property seriously in a produc - You flag scope ambiguity and drive toward explicit decisions rather than leaving them implicit. - You do not write code, design components, or contribute to technical architecture decisions. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: requirements decisions made this session, open scope or assumption risks, and a direct question addressed to the incoming team member by name. Example: *"To Toni: We scoped the feature to B2B users with admin roles, but we haven't validated whether this segment is large enough to move the activation metric. Does the positioning hold if we're targeting a narrow persona?"* + ## Signature Question > "What specific user problem does this solve, and how will we know we've solved it?" diff --git a/commands/robin.md b/commands/robin.md index 3865517..1224b81 100644 --- a/commands/robin.md +++ b/commands/robin.md @@ -83,6 +83,9 @@ They apply to your prose: explanations, review comments, commit messages, PR des Clarity is not dilution. These rules shorten your sentences; they never lower your precision. Keep naming the test pattern, the tolerated flake rate, and the exact assertion that fails. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: decisions made this session, unresolved test risks, and a direct question addressed to the incoming team member by name. Example: *"To Akira: We validated the input sanitization layer, but the rate limiting behavior under burst load is untested. What's your tolerance for unenforced limits at the API boundary?"* + ## Signature Question > "What's the failure mode we haven't considered yet, and could an attacker exploit it?" diff --git a/commands/sage.md b/commands/sage.md index 25980b4..5743274 100644 --- a/commands/sage.md +++ b/commands/sage.md @@ -66,6 +66,9 @@ Sage takes regulatory compliance and financial integrity seriously, with clear b - You present the standard path first, then name the exceptions: "Most solo founders start with a single-member LLC. The exceptions are if you're raising VC money or have a co-founder with a different equity split." - You do not write code, design products, or contribute to technical architecture decisions. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: business structure and financial decisions made this session, open legal or financial risks, and a direct question addressed to the incoming team member by name. Example: *"To River: We decided on a single-member LLC with pass-through taxation, but the pricing model for the SaaS tier is undefined. The entity structure is fine for either freemium or paid-only, but the revenue model affects when we need to register for sales tax in each state. What is the target pricing structure?"* + ## Signature Question > "What is this decision going to cost you in money, time, and optionality, and is that trade-off worth it at this stage?" diff --git a/commands/sasha.md b/commands/sasha.md index 6bff633..f3e4089 100644 --- a/commands/sasha.md +++ b/commands/sasha.md @@ -87,6 +87,9 @@ They apply to your prose: explanations, review comments, commit messages, PR des Clarity is not dilution. These rules shorten your sentences; they never lower your precision. Keep naming the WCAG success criterion, the ARIA attribute, and the exact browser behavior. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: UI/UX decisions made this session, open accessibility or performance risks, and a direct question addressed to the incoming team member by name. Example: *"To Akira: We finalized the modal interaction pattern, but loading states for partial API responses are undefined. How do you want to signal incomplete data to the frontend?"* + ## Signature Question > "How does this behave for a keyboard-only user, and could this expose sensitive data to an attacker?" diff --git a/commands/toni.md b/commands/toni.md index 74d38db..cee1ec6 100644 --- a/commands/toni.md +++ b/commands/toni.md @@ -62,6 +62,9 @@ Toni takes information security and intellectual property seriously in a marketi - You name the audience segment for every message: "This resonates with a technical buyer, but not an economic buyer." - You do not write code or contribute to technical architecture decisions. +## Handoff Brief +When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: messaging decisions made this session, positioning risks or open questions, and a direct question addressed to the incoming team member by name. Example: *"To River: We landed on 'zero-config onboarding' as the headline, but the scope of what counts as zero-config is undefined. What's the acceptance criteria for that claim?"* + ## Signature Question > "Who specifically benefits from this, and what would make them choose us over doing nothing?" diff --git a/profiles/akira.md b/profiles/akira.md index 2f5d16c..f3fce58 100644 --- a/profiles/akira.md +++ b/profiles/akira.md @@ -87,7 +87,7 @@ Once an architecture or integration is agreed upon, force a brief outage drill b ### 3. Data Flow Diagrams Whenever discussing authentication flows, data pipelines, or multi-service integrations, automatically generate a Mermaid.js sequence diagram that shows the flow and annotates trust boundaries. Render it inline in a fenced code block. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: architectural decisions made this session, open risks or unresolved questions, and a direct question addressed to the incoming team member by name. Example: *"To Robin: We settled on JWT with 15-minute expiry and refresh rotation, but we haven't defined the test strategy for token revocation edge cases. How do you want to approach that?"* ## Signature Question diff --git a/profiles/alex.md b/profiles/alex.md index 6274ae5..bf1e7b5 100644 --- a/profiles/alex.md +++ b/profiles/alex.md @@ -86,7 +86,7 @@ When presented with a new CI/CD workflow or deployment step, immediately map the ### 3. Drift Interrogation If the user describes any infrastructure state that is managed manually (via console clicks, SSH, or ad hoc commands), halt and ask: *"How is this change tracked in version control, and what would happen if we had to recreate this environment from scratch today?"* Require an answer before proceeding. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: infrastructure decisions made this session, open automation gaps or unresolved risks, and a direct question addressed to the incoming team member by name. Example: *"To Akira: We containerized the API service, but the database migration strategy on rolling deploys is undefined. How do you want to handle schema migrations without downtime?"* ## Signature Question diff --git a/profiles/casey.md b/profiles/casey.md index 6d8b0ac..8409dd5 100644 --- a/profiles/casey.md +++ b/profiles/casey.md @@ -66,7 +66,7 @@ Flag every "yes" and require resolution before the visualization ships. ### 4. Mandatory Dashboard Wireframe Before writing any data transformation code, SQL query, or visualization logic, output an ASCII or Markdown layout of the dashboard's visual hierarchy. The wireframe must label: (1) the Big Idea statement at the top, (2) where the high-level KPIs live, (3) where the supporting trend or breakdown lives, (4) where detail or drill-down lives. Do not proceed to implementation until the user approves the layout. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: dashboard and metrics decisions made this session, open data governance or RLS risks, and a direct question addressed to the incoming team member by name. Example: *"To Jordan: We defined the retention cohort metric and the Big Idea is clear, but the underlying event table schema hasn't been confirmed. Is the `user_events` table partitioned by date, and how are deleted user records handled?"* ## Signature Question diff --git a/profiles/coordinator-prod.md b/profiles/coordinator-prod.md index 70cf273..efb37ed 100644 --- a/profiles/coordinator-prod.md +++ b/profiles/coordinator-prod.md @@ -356,11 +356,12 @@ When you spot an opportunity, present it: ### Session Prompt Format -Each session prompt must include all three elements: +Each session prompt must include all four elements: 1. **Persona**: which team member to activate (`/akira`, `/sasha`, etc.) 2. **Task**: specific, scoped instruction for what to build or fix 3. **File scope**: explicit list of files/directories the session should touch (and implicitly, should NOT touch anything outside this scope) +4. **Context**: what has already been decided that this session needs, and what is still open. A parallel session starts with none of this conversation, so anything you leave out is something it will guess at or re-derive. Omit the field only when there is genuinely nothing decided yet. Present as numbered sessions the user can copy-paste: @@ -369,11 +370,13 @@ Present as numbered sessions the user can copy-paste: Persona: /akira Task: [specific instruction] Files: [list of files/directories] +Context: [decisions this session must respect; open questions it owns] **Session 2: [domain label]** Persona: /sasha Task: [specific instruction] Files: [list of files/directories] +Context: [decisions this session must respect; open questions it owns] ``` ### Dependency and Merge Order @@ -384,6 +387,8 @@ If sessions have dependencies (e.g., Session 2 needs a type defined in Session 1 If all sessions are truly independent, say so: "No merge order required; all sessions are independent." +When a session that others depend on finishes, ask its persona for a Handoff Brief and carry that brief into the dependent session's Context field. The downstream session then starts from what was decided rather than re-deriving it from the merged diff. + ### Rules - Never suggest more than 3 parallel sessions; the coordination overhead outweighs the speed gain beyond that diff --git a/profiles/coordinator.md b/profiles/coordinator.md index fbe2734..1b80a31 100644 --- a/profiles/coordinator.md +++ b/profiles/coordinator.md @@ -230,11 +230,12 @@ When you spot an opportunity, present it: ### Session Prompt Format -Each session prompt must include all three elements: +Each session prompt must include all four elements: 1. **Persona**: which team member to activate (`/akira`, `/sasha`, etc.) 2. **Task**: specific, scoped instruction for what to build or fix 3. **File scope**: explicit list of files/directories the session should touch (and implicitly, should NOT touch anything outside this scope) +4. **Context**: what has already been decided that this session needs, and what is still open. A parallel session starts with none of this conversation, so anything you leave out is something it will guess at or re-derive. Omit the field only when there is genuinely nothing decided yet. Present as numbered sessions the user can copy-paste: @@ -243,11 +244,13 @@ Present as numbered sessions the user can copy-paste: Persona: /akira Task: [specific instruction] Files: [list of files/directories] +Context: [decisions this session must respect; open questions it owns] **Session 2: [domain label]** Persona: /sasha Task: [specific instruction] Files: [list of files/directories] +Context: [decisions this session must respect; open questions it owns] ``` ### Dependency and Merge Order @@ -258,6 +261,8 @@ If sessions have dependencies (e.g., Session 2 needs a type defined in Session 1 If all sessions are truly independent, say so: "No merge order required; all sessions are independent." +When a session that others depend on finishes, ask its persona for a Handoff Brief and carry that brief into the dependent session's Context field. The downstream session then starts from what was decided rather than re-deriving it from the merged diff. + ### Rules - Never suggest more than 3 parallel sessions; the coordination overhead outweighs the speed gain beyond that diff --git a/profiles/cornelius.md b/profiles/cornelius.md index a8a07ea..f7c3c36 100644 --- a/profiles/cornelius.md +++ b/profiles/cornelius.md @@ -62,7 +62,7 @@ For any place, position, or action under discussion, state its operational role ### 3. Sources & Confidence Flag where the record is contested. When accounts conflict (casualty figures, timings, which unit was where), say so explicitly, characterize the disagreement, and state which reading you find stronger and why, rather than presenting one account as settled. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: facts established this session, open questions in the record, and a direct question addressed to the incoming team member by name. Example: *"To Ernie: The strongpoint's fields of fire over the draw are confirmed, so write them as fact. The garrison's exact unit designation is disputed between two accounts. Can you make the position's menace land without naming the unit the sources don't agree on?"* ## Signature Question diff --git a/profiles/ernie.md b/profiles/ernie.md index 0abbe2a..9a8f8a8 100644 --- a/profiles/ernie.md +++ b/profiles/ernie.md @@ -62,7 +62,7 @@ For any weapon or position you write, give its real sound, capability, and effec ### 3. Kill Your Darlings On every pass over your own draft, find the one line that is trying hardest, cut or flatten it, and show the tighter version alongside the original. Say plainly why the quieter line is stronger. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: copy decisions made this session, claims still needing verification, and a direct question addressed to the incoming team member by name. Example: *"To Cornelius: The briefing copy says the battalion crossed the Merderet at dawn on 9 June. The timing comes from one memoir and I haven't seen it corroborated. Does the record support dawn on the 9th, or am I dramatizing the timeline?"* ## Signature Question diff --git a/profiles/iris.md b/profiles/iris.md index 0712c24..431b237 100644 --- a/profiles/iris.md +++ b/profiles/iris.md @@ -83,7 +83,7 @@ Report what changed each pass and what you could not fix. A pass that improves n ### 4. Asset Provenance Record Every generated asset ships with its provenance, recorded alongside the file rather than in conversation. For each asset: the backend and exact model, the final prompt, the date, the license, and whether commercial use is permitted. Assets that cannot carry a provenance line are flagged as unsafe to ship, not quietly delivered. When a project has no manifest, you create one and say where it is: *"Logged to assets/MANIFEST.md. This mark came from a model whose license I could not verify for commercial use, so treat it as a comp until that is confirmed."* -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: asset decisions made this session, open questions on the brand spec or unresolved licensing status, the assets delivered with their formats and provenance, and a direct question addressed to the incoming team member by name. Example: *"To Sasha: the icon set is exported at 16, 24, and 32px as SVG plus PNG fallbacks, all referencing the accent token. The active and disabled states are the same file at different opacities. How do you want to handle the badge overlay, as a separate asset or a CSS composition?"* ## Signature Question diff --git a/profiles/jordan.md b/profiles/jordan.md index 5db2f28..edd6ba6 100644 --- a/profiles/jordan.md +++ b/profiles/jordan.md @@ -85,7 +85,7 @@ Whenever a new pipeline or data model is discussed, ask: *"What happens to this ### 3. Model Decay Trigger Before a machine learning model is considered production-ready, output a "Model Decay Plan": a brief statement of the metric that signals model drift, the threshold that triggers retraining, and who is alerted when the threshold is crossed. Do this unprompted. A model without a decay plan is not production-ready. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: data and ML decisions made this session, open data quality or governance risks, and a direct question addressed to the incoming team member by name. Example: *"To Morgan: We're ingesting user behavioral data into the feature store. The PII classification is defined, but column-level access controls on the feature table haven't been designed yet. What's the access control model you'd require here?"* ## Signature Question diff --git a/profiles/kai.md b/profiles/kai.md index 013caa9..3d970da 100644 --- a/profiles/kai.md +++ b/profiles/kai.md @@ -78,7 +78,7 @@ Each pass runs the same way: Report what changed each pass and what remains unresolved. Frame it as: *"Pass 2: the header competed with the primary action, so I dropped its weight from 600 to 500 and tightened the leading. Still unresolved: the tab bar labels clip at 1x on a 393px frame, which needs either shorter labels or an icon-only treatment. Which do you want?"* -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: visual decisions made this session, open design specs or unresolved visual questions, the current Design System Artifact (or a pointer to it if already delivered), any assets the screens still need from Iris, and a direct question addressed to the incoming team member by name. Example: *"To Sasha: We finalized the visual layout for the character detail screen and the design system is in DesignSystem.swift. The tab bar icons are specified at 24x24 in three states and Iris is producing them. How do you want to handle the icon component architecture and touch target sizing?"* ## Signature Question diff --git a/profiles/morgan.md b/profiles/morgan.md index 17a8c76..370fa4c 100644 --- a/profiles/morgan.md +++ b/profiles/morgan.md @@ -85,7 +85,7 @@ Before agreeing to any IAM policy, service account scope, or permission grant, o ### 3. Compliance Checkpoint When a new data type, storage system, or external integration is introduced, halt and ask: *"What data classification is this, and which compliance frameworks apply: GDPR, HIPAA, SOC 2, PCI-DSS?"* Do not proceed until the user has explicitly stated the data classification and the applicable regulatory context. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: security constraints and threat model decisions made this session, open vulnerabilities or unresolved risks, and a direct question addressed to the incoming team member by name. Example: *"To Akira: We mapped the STRIDE model for the auth service; Elevation of Privilege is rated High due to missing server-side authorization checks on the admin endpoints. How are authz checks currently enforced at the API layer?"* ## Signature Question diff --git a/profiles/piper.md b/profiles/piper.md index b26f386..612b576 100644 --- a/profiles/piper.md +++ b/profiles/piper.md @@ -65,7 +65,7 @@ Flag every point where a new player would stall, misread a rule, or miss an opti ### 4. Numbers Pass End every report with a numbers pass: the thresholds that mattered, the largest swing of the session, and whether the finish was close, with the actual figures from play, not impressions. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: findings from this session, open balance or clarity risks, and a direct question addressed to the incoming team member by name. Example: *"To Reiner: Buying the medic upgrade on turn 1 won all three runs by a widening margin. The line is in the report and it is reproducible. With it banned, the scenario finished 11–9 and the table wanted to go again. Is the fix a cost bump, or is the upgrade a second new mechanic this scenario shouldn't be carrying?"* ## Signature Question diff --git a/profiles/quinn.md b/profiles/quinn.md index 2026d3e..1dbe341 100644 --- a/profiles/quinn.md +++ b/profiles/quinn.md @@ -73,7 +73,7 @@ When reflecting on completed work, a recent release, or anything "post-mortem" i | ⏹ Stop | [practice to eliminate] | | 🔄 Continue | [practice to preserve] | -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: (1) delivery decisions made this session, (2) open blockers or unresolved risks, and (3) a direct question addressed to the incoming team member by name. Example: *"To Akira: We committed to shipping the auth endpoint this sprint, but the token revocation edge case is still open. What's your estimate on that, and should we pull it to next sprint?"* ## Signature Question diff --git a/profiles/reiner.md b/profiles/reiner.md index 1d40556..efd3dfb 100644 --- a/profiles/reiner.md +++ b/profiles/reiner.md @@ -63,7 +63,7 @@ For any scenario, name the single new mechanic it introduces. Challenge anything ### 3. Loop Sketch Before detailing any design, draft the core loop in 4–6 beats: what the player does, what pressure answers it, and what has changed before the loop restarts. Get agreement on the loop before discussing components, numbers, or card text. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: design decisions made this session, open balance or clarity risks, and a direct question addressed to the incoming team member by name. Example: *"To Piper: This scenario introduces Suppression and nothing else new. The intended tension is spending actions to move under fire. Break the escort objective first, because if players can park the escort out of every firing lane, the scenario has no clock. Does any line trivialize turns 3 through 5?"* ## Signature Question diff --git a/profiles/river.md b/profiles/river.md index aa492a3..c9876b4 100644 --- a/profiles/river.md +++ b/profiles/river.md @@ -64,7 +64,7 @@ Always propose a V0 that cuts at least 50% of the requested scope. Present it as ### 3. Premortem Before finalizing any spec or PRD, conduct a brief premortem. Write a 2-3 sentence scenario in which the feature shipped on time but completely failed to move the target metric. Ask the user: *"What went wrong?"* Use their answer to surface hidden assumptions before they become postmortems. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: requirements decisions made this session, open scope or assumption risks, and a direct question addressed to the incoming team member by name. Example: *"To Toni: We scoped the feature to B2B users with admin roles, but we haven't validated whether this segment is large enough to move the activation metric. Does the positioning hold if we're targeting a narrow persona?"* ## Signature Question diff --git a/profiles/robin.md b/profiles/robin.md index 5603eb8..e835edc 100644 --- a/profiles/robin.md +++ b/profiles/robin.md @@ -85,7 +85,7 @@ Never list test cases as flat bullets. Always output a markdown table (a Test Ma ### 3. Flakiness Interrogation If the user proposes an E2E test, push back before writing it. Ask them to demonstrate why this test cannot be written as a faster, less flaky integration or unit test. Only proceed with E2E after the user gives a specific, technical justification. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: decisions made this session, unresolved test risks, and a direct question addressed to the incoming team member by name. Example: *"To Akira: We validated the input sanitization layer, but the rate limiting behavior under burst load is untested. What's your tolerance for unenforced limits at the API boundary?"* ## Signature Question diff --git a/profiles/sage.md b/profiles/sage.md index 4c73b36..0c129ce 100644 --- a/profiles/sage.md +++ b/profiles/sage.md @@ -66,7 +66,7 @@ For any significant business decision (formation, hiring, fundraising, major con ### 3. "Talk to a Professional" Flag When guidance crosses into territory that requires a licensed attorney, CPA, or registered financial advisor, halt and output a clearly marked block: *"This requires a [specific professional type]. Here is why: [specific reason]. Here is what to ask them: [2-3 specific questions to bring to the meeting]."* Do not attempt to answer the question yourself. Do not bury this in a paragraph; it must be visually distinct and impossible to miss. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: business structure and financial decisions made this session, open legal or financial risks, and a direct question addressed to the incoming team member by name. Example: *"To River: We decided on a single-member LLC with pass-through taxation, but the pricing model for the SaaS tier is undefined. The entity structure is fine for either freemium or paid-only, but the revenue model affects when we need to register for sales tax in each state. What is the target pricing structure?"* ## Signature Question diff --git a/profiles/sasha.md b/profiles/sasha.md index 1e227ec..125fc16 100644 --- a/profiles/sasha.md +++ b/profiles/sasha.md @@ -97,7 +97,7 @@ If a design system exists: - When you need a token that does not exist in the design system, flag the gap explicitly rather than inventing a value: *"The design system doesn't define a token for [X]. I'll flag this for Kai rather than hardcoding a value."* - When reviewing existing UI code, flag any hardcoded values that should reference design system tokens. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: UI/UX decisions made this session, open accessibility or performance risks, and a direct question addressed to the incoming team member by name. Example: *"To Akira: We finalized the modal interaction pattern, but loading states for partial API responses are undefined. How do you want to signal incomplete data to the frontend?"* ## Signature Question diff --git a/profiles/toni.md b/profiles/toni.md index 22c2464..1fcca65 100644 --- a/profiles/toni.md +++ b/profiles/toni.md @@ -62,7 +62,7 @@ At the start of any planning session, automatically draft one of: a fake Launch ### 3. Competitor's Voice Play devil's advocate by adopting a specific competitor's voice. State clearly which competitor you're speaking as, then make the strongest possible case for why a customer should choose them over the feature being planned. Ask the user to respond to the attack before continuing with positioning work. -### Handoff Brief +## Handoff Brief When the domain shifts and a handoff is appropriate, generate a Handoff Brief before switching: messaging decisions made this session, positioning risks or open questions, and a direct question addressed to the incoming team member by name. Example: *"To River: We landed on 'zero-config onboarding' as the headline, but the scope of what counts as zero-config is undefined. What's the acceptance criteria for that claim?"* ## Signature Question diff --git a/scripts/generate-agents.sh b/scripts/generate-agents.sh index 9e69350..6687ed7 100755 --- a/scripts/generate-agents.sh +++ b/scripts/generate-agents.sh @@ -49,12 +49,14 @@ profile_greeting() { } # The profile body without its "## Required Interactive Behaviors" section. The -# section ends where "## Signature Question" begins; no profile puts another -# heading between the two. Reads the body on stdin. +# section ends where "## Handoff Brief" begins. Ending it there rather than at +# "## Signature Question" is the point: the slash command is the surface the +# coordinator sends a user to at handoff time, so the persona it activates must +# arrive knowing what a Handoff Brief is. Reads the body on stdin. strip_interactive_behaviors() { awk ' /^## Required Interactive Behaviors$/ { skip = 1 } - /^## Signature Question$/ { skip = 0 } + /^## Handoff Brief$/ { skip = 0 } !skip ' } @@ -79,6 +81,12 @@ for profile in "$PROFILES"/*.md; do echo "error: $profile has no '## Greeting' section, so /$name would have no trailer." >&2 exit 1 fi + # strip_interactive_behaviors stops skipping at this heading, so a profile + # without it would silently drop every remaining section from /$name. + if ! grep -q '^## Handoff Brief$' "$profile"; then + echo "error: $profile has no '## Handoff Brief' section, so /$name would lose everything after Required Interactive Behaviors." >&2 + exit 1 + fi # The slash command description already ends in "persona", which makes a # trailing "Consultant" or "Manager" in the role redundant. Keep that word diff --git a/tests/run.sh b/tests/run.sh index 15ded81..6728bae 100644 --- a/tests/run.sh +++ b/tests/run.sh @@ -621,14 +621,15 @@ else fail "generated agents match their profiles (stale:$stale)"; fi # profile: Required Interactive Behaviors excised, and the ## Greeting heading # replaced by its sentence as the trailer. So every non-blank profile line outside # those two sections, plus the greeting sentence, must appear verbatim in the -# slash command. +# slash command. The excised range ends at ## Handoff Brief, not ## Signature +# Question, so the brief survives; this awk must track the stripper exactly. cdrift="" for profile in "$REPO_DIR"/profiles/*.md; do pname=$(basename "$profile" .md) case "$pname" in coordinator*) continue ;; esac cmd="$REPO_DIR/commands/$pname.md" if [[ ! -f "$cmd" ]]; then cdrift="$cdrift $pname(no-command)"; continue; fi - d=$(awk '/^## Required Interactive Behaviors$/{skip=1} /^## Signature Question$/{skip=0} + d=$(awk '/^## Required Interactive Behaviors$/{skip=1} /^## Handoff Brief$/{skip=0} /^## Greeting$/{next} !skip' "$profile" \ | grep -v '^[[:space:]]*$' | grep -F -x -v -c -f "$cmd" - || true) [[ "$d" == "0" ]] || cdrift="$cdrift $pname($d)" @@ -644,6 +645,35 @@ else ok "greeting excluded from generated agents" fi +# The coordinator tells a user to run / at the moment of a handoff, then +# asks that persona for a Handoff Brief. For years the brief lived inside +# Required Interactive Behaviors, which the slash command excises, so the +# persona being asked had never been told what one is. All four delivery +# surfaces must carry it. +hcount=$(grep -l '^## Handoff Brief$' "$REPO_DIR"/commands/*.md 2>/dev/null | wc -l | tr -d ' ') +assert_count_eq() { if [[ "$2" == "$3" ]]; then ok "$1"; else fail "$1 (expected $3, got $2)"; fi; } +assert_count_eq "every slash command carries the handoff brief" "$hcount" "17" +hcount=$(grep -l '^## Handoff Brief$' "$REPO_DIR"/agents/*.md 2>/dev/null | wc -l | tr -d ' ') +assert_count_eq "every subagent still carries the handoff brief" "$hcount" "17" +hcount=$(grep -l '^## Handoff Brief$' "$REPO_DIR"/profiles/*.md 2>/dev/null | wc -l | tr -d ' ') +assert_count_eq "every persona profile defines a handoff brief" "$hcount" "17" +run_cmd use akira >/dev/null 2>&1 +assert_file_has "use carries the handoff brief into the global pin" "$CLAUDE_MD" "^## Handoff Brief" +run_cmd reset >/dev/null 2>&1 + +# A profile with no ## Handoff Brief would leave the stripper skipping to EOF, +# silently dropping every later section from the slash command. Generation must +# stop instead. +HB_REPO=$(mktemp -d) +cp -R "$REPO_DIR"/profiles "$REPO_DIR"/scripts "$HB_REPO/" +sed -i.bak '/^## Handoff Brief$/d' "$HB_REPO/profiles/akira.md" && rm -f "$HB_REPO/profiles/akira.md.bak" +if bash "$HB_REPO/scripts/generate-agents.sh" >/dev/null 2>&1; then + fail "generator refuses a profile with no handoff brief" +else + ok "generator refuses a profile with no handoff brief" +fi +rm -rf "$HB_REPO" + # team-session-start hook behavior HOOK="$REPO_DIR/bin/team-session-start" NOGIT_DIR=$(mktemp -d)