settled-reach/.claude/skills/workshop-start/SKILL.md

name, description

name	description
workshop-start	Start a multi-agent design workshop from a workshop brief. Use when the user says "start workshop", "run workshop", "let's start the workshop", or invokes /workshop-start. Parses the workshop brief to extract participants, questions, and round format. Creates a team, tasks, and spawns agents as teammates via the Task tool.

Start Workshop

Prerequisites

A workshop brief must exist at docs/workshops/{name}/{name}-workshop-brief.md containing:

• Participants line (comma-separated agent names)
• Questions for participants sections with numbered questions tagged by agent name
• Workshop Format section defining number of rounds and their purpose

Workflow

1. Parse the Brief

Read the workshop brief. Extract:

• Workshop name (from directory name)
• Participant list (from **Participants:** line)
• Per-participant questions (scan for **{AgentName}**: patterns in questions sections)
• Round count and round descriptions (from **Workshop Format** section)

2. Create Team

TeamCreate: team_name = "{workshop-name}", description from brief title

3. Always-Present Agents

Two agents join every workshop regardless of the participant list:

Agent	Role	Task	Participates in discussion?
Qatux	Documenter	Captures all decisions, questions, dissent, consensus. Writes workshop-notes.md per round, produces final workshop-outcomes.md.	No — observes and records only
SI	Sprint prep	Suggest adding when outputs include tickets. Creates tickets from decisions, links to sprint backlog.	No — execution prep only

Qatux and SI are never dismissed early. If the user reduces the team mid-workshop, keep qatux and si (if added). Documenting everything prevents loss of valuable information.

4. Create Tasks (Round 1)

One task per participant containing:

• Instruction to read the full brief at its path
• The specific questions assigned to that participant (extracted from all layers)
• The output format from the brief's round description
• IMPORTANT — file output requirement: Instruct each agent to write their full output to docs/workshops/{name}/{agent}-round{N}.md (e.g., docs/workshops/test-architecture/gestalt-round1.md). Agents must write to disk, not just send messages. This ensures Qatux and other agents can read all outputs directly without relying on message forwarding.

One task for Qatux: "Document Round N — read all agent output files at docs/workshops/{name}/*-round{N}.md and capture decisions, questions, and dissent."

Assign all tasks using TaskUpdate with owner = agent name.

5. Spawn Agents

Use the Task tool to spawn each agent as a teammate. Each call should:

• Set team_name to the workshop team name
• Set name to the agent name (e.g., "gestalt")
• Set subagent_type to the matching agent type (same as name — see reference table)
• Provide a prompt telling the agent to check TaskList for their assigned task

Spawn all agents in parallel (one Task call per agent in a single message). Agents will appear as teammates in the Claude Code UI and pick up their tasks from the shared task list.

For large workshops (>6 agents), spawn participants in batches to avoid overwhelming the system. Always-present agents (Qatux, SI) can run in background via run_in_background: true.

6. Monitor

• TaskList to check progress
• SendMessage to nudge idle agents or provide clarification
• Agents work autonomously — claim tasks, read the brief, produce responses

7. Between Rounds — USER REVIEW CHECKPOINT (MANDATORY)

When all Round N tasks are complete:

1. Verify all agents wrote output files to docs/workshops/{name}/. If any are missing, nudge the agent or extract from their message and write the file yourself.
2. Qatux reads all *-round{N}.md files and produces round summary in round-{N}-notes.md
3. MANDATORY: Present round results to the user via AskUserQuestion before proceeding.
   • Summarize the key findings, votes, consensus, and tensions from the round
   • Present open decisions that need user input (product decisions, scope calls, design direction)
   • Ask the user whether to proceed to the next round, adjust direction, or add rounds
   • Do NOT create next-round tasks or synthesize proposals until the user has reviewed and approved
   • The user cannot see agent messages or file contents — present all key information directly
4. After user approval, create Round N+1 tasks (integration pass, synthesis, etc.) — include the same file output requirement
5. Assign to agents with TaskUpdate
6. Agents continue working

8. Wrap Up — USER CONTROLS SHUTDOWN (MANDATORY)

The user decides when the workshop ends and when the team is dismissed. Never initiate shutdown, team cleanup, or wrap-up autonomously. Only proceed when the user explicitly says to wrap up.

Before the user dismisses the team, the following are hard requirements:

1. User reviews final outcomes — Present workshop-outcomes.md content to the user via AskUserQuestion. Get explicit approval before proceeding to filing.
2. D-records filed — All new D-records, amendments, and supersessions are written to decisions/ domain files. This is non-negotiable — workshops that produce decisions MUST file them before shutdown.
3. Discussion captured — Qatux produces final workshop-outcomes.md from accumulated notes. Qatux creates or updates diagrams (via /d2-diagram) for any new D-records produced by the workshop.
4. Tickets created — If SI is present, SI creates tickets from decided items and the user reviews the ticket list.
5. User gives explicit go-ahead to dismiss — Only after steps 1-4 are complete AND the user confirms, send shutdown_request to all agents (qatux and si last).
6. TeamDelete to clean up.

Never shortcut this sequence. Filing D-records and capturing the discussion are not optional cleanup — they are workshop deliverables.

Workshop Format: Interview Mode

When the workshop brief specifies **Format:** Interview (or the user requests "interactive interview mode"), the between-rounds flow changes for the interview round:

How Interview Mode Works

Instead of agents writing responses to each other, the facilitator (team lead) conducts a live interview with the user:

1. Collect all agent questions — Read all Round 1 output files to gather every question.
2. Group thematically — Organize questions into 5-7 thematic clusters (e.g., "The Vision," "The Confusion Type," "The Emotional Loop"). Questions from different agents that probe similar territory go together.
3. Present via AskUserQuestion — Present each group using the AskUserQuestion tool, one group at a time (1-3 questions per group). For each question:
   • Include the asking agent's name and domain
   • Include the full question text with context
   • Include the agent's reasoning for why the question matters
   • Provide 2-4 option choices that represent distinct answer categories
   • Always allow free-text via the "Other" option (automatic)
4. Capture nuance — The user's free-text notes often contain the most important insights. Capture these verbatim in the transcript.
5. Summarize between groups — After each group, briefly reflect back the key finding before moving to the next group.
6. Write full transcript — When all groups are done, write the complete interview to docs/workshops/{name}/lead-interview.md with:
   • Every question and full answer (verbatim where the user provided free text)
   • Key findings per answer
   • An interview summary section with the major revelations
   • "What Survives" and "What Changes" sections

Why AskUserQuestion

The user CANNOT see agent messages, task details, or file contents in the conversation. They only see your text output and AskUserQuestion prompts. Present all question context directly — never assume the user has read agent outputs.

Distributing Interview Results

When creating Round 3 (proposal) tasks after an interview round, include the full transcript path and a summary of the major reframe in every agent's task description. If the user requests it, instruct agents to read the verbatim transcript.

Agent Type Reference

Agent name maps directly to subagent_type:

Name	Domain	Typical workshop role
gestalt	Systems design	Mechanics, fun factor, system interactions
ozzie	Player experience	Wow moments, feel, emotional response
tyre	Technical architect	Feasibility, performance, architecture
stig	UI developer	Interface patterns, layout, interaction flows
dudley	Server developer	Server-side systems, data flow, ECS
paula	Narrative	Story, dialogue, character, political depth
araminta	Visual design	Art direction, visual treatment, aesthetics
nigel	Replayability	Emergent stories, second-playthrough, sandbox
gore	Themes/endgame	What the game is about, philosophical questions
mellanie	Copywriter	In-game text, voice, tone
miri	Worldbuilder	Setting, factions, lore, consistency
inigo	Sound design	Audio, soundscape, spatial audio
troblum	Tech consultant	Second opinion on architecture/tech choices
hoshe	QA/testing	Test plans, verification, quality