@qball-inc/the-bulwark 1.0.0

package/skills/create-skill/references/decision-framework.md

@@ -0,0 +1,124 @@
+# Decision Framework
+
+Interview questions and classification logic for the create-skill pipeline. The orchestrator uses this at Stage 0 (Pre-Flight) and Stage 1 (Classify).
+
+---
+
+## Stage 0: Adaptive Interview
+
+### Core Questions (Always Ask)
+
+Present all 5 questions to the user via AskUserQuestion. These determine the skill type, context mode, and supporting file needs.
+
+| # | Question | What It Reveals |
+|---|----------|-----------------|
+| Q1 | What does this skill do? Give 2-3 concrete examples of how someone would invoke it. | Scope, trigger patterns, invocation style |
+| Q2 | Does it need conversation history, or can it run in complete isolation? | Context mode (inline vs fork) |
+| Q3 | Does it orchestrate multiple distinct operations or analyses? | Sub-agent pattern (none, sequential, parallel) |
+| Q4 | How much domain-specific reference content does it need? (None / Some / Extensive) | Supporting file structure (vanilla vs references/) |
+| Q5 | Does it produce structured output that must match a specific format? | Templates directory need |
+
+### Follow-Up Questions (Conditional)
+
+Ask follow-ups when Q1-Q5 answers indicate complexity. Trigger conditions:
+
+| Trigger | Follow-Up Questions |
+|---------|-------------------|
+| Q3 = "yes, multiple operations" | Q6: Do the operations depend on each other's output? (sequential vs parallel) |
+| Q3 = "yes, multiple operations" | Q7: Do workers need to communicate with each other directly? (Task tool vs Agent Teams) |
+| Q3 = "yes" AND Q2 = "isolation" | Q8: What error handling is needed between stages? (retry, fallback, abort) |
+| Q4 = "extensive" | Q9: Is the reference content static (loaded once) or dynamic (computed per run)? |
+| Q5 = "yes, structured" | Q10: Is the output format YAML, Markdown with sections, or something else? |
+
+### Interview Behavior
+
+- Present Q1-Q5 in a single AskUserQuestion call (not one-at-a-time)
+- If answers are ambiguous, ask 1-2 clarifying follow-ups (do not over-interview)
+- If the user provides a `--doc` requirements document, extract Q1-Q5 answers from it and present for confirmation instead of asking fresh
+- Total interview: 1-2 AskUserQuestion rounds maximum
+
+---
+
+## Stage 1: Three-Decision Classification
+
+After the interview, make three independent decisions. Each decision is self-contained — they don't depend on each other.
+
+### Decision A: Context Mode
+
+Determines whether the skill runs inline (access to conversation) or forked (isolated context).
+
+```
+Q2 = "needs conversation history"    → inline (no fork)
+Q2 = "can run in isolation"
+  AND Q3 = "multiple operations"     → context: fork
+Q2 = "can run in isolation"
+  AND Q3 = "no"                      → inline (no fork)
+  NOTE: Warn if user requests fork for a simple guideline/knowledge skill.
+        Fork adds overhead with no benefit for inline knowledge.
+```
+
+**Default**: inline (no fork). Fork is rare — only 2 of 21 Bulwark skills use it.
+
+### Decision B: Sub-Agent Pattern
+
+Determines how the skill orchestrates work.
+
+```
+Q3 = "no, single operation"          → no sub-agents
+Q3 = "yes" AND Q6 = "dependent"      → sequential Task tool sub-agents
+Q3 = "yes" AND Q6 = "independent"    → parallel Task tool sub-agents
+Q3 = "yes" AND Q7 = "direct comms"   → Agent Teams (experimental)
+  NOTE: Include env var gating (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)
+        and experimental warning in generated skill.
+```
+
+**Default**: no sub-agents. Only add orchestration when the skill genuinely needs multiple distinct passes.
+
+### Decision C: Supporting Files
+
+Determines the file structure beyond SKILL.md.
+
+```
+Q4 = "none" AND Q5 = "no"            → vanilla SKILL.md only
+Q4 = "some" or "extensive"           → add references/ directory
+Q5 = "yes, structured output"        → add templates/ directory
+Q3 = "yes" AND needs scripts         → add scripts/ directory
+  NOTE: scripts/ is for deterministic code execution (AST analysis,
+        data transforms). Not needed for LLM-only workflows.
+```
+
+### Decision → Template Mapping
+
+| Classification | Template | File Structure |
+|----------------|----------|----------------|
+| No sub-agents, no references, no templates | `template-simple.md` | `SKILL.md` only |
+| References needed, no sub-agents | `template-reference-heavy.md` | `SKILL.md` + `references/` |
+| Sequential or parallel sub-agents | `template-pipeline.md` | `SKILL.md` + `references/` + `templates/` |
+| Deterministic scripts required | `template-script-driven.md` | `SKILL.md` + `scripts/` + `references/` |
+| Multi-agent research/brainstorm | `template-research.md` | `SKILL.md` + `references/` + `templates/` |
+
+### Classification Output
+
+After classification, present the three decisions to the user for confirmation before proceeding to Stage 2:
+
+```
+Classification:
+- Context: {inline/fork} — {one-line reason}
+- Sub-agents: {none/sequential/parallel/Agent Teams} — {one-line reason}
+- Supporting files: {list} — {one-line reason}
+- Template: {template name}
+
+Proceed with generation? [Yes / Adjust]
+```
+
+---
+
+## Edge Cases
+
+| Scenario | Resolution |
+|----------|------------|
+| User requests fork for simple knowledge skill | Warn: "Fork adds overhead with no benefit for inline knowledge skills. Recommend inline." Allow override. |
+| User requests Agent Teams | Include experimental warning + env var check. Note: Agent Teams requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. |
+| Skill type doesn't clearly map to one template | Pick the closest match, note the mismatch in post-generation summary. |
+| User provides conflicting Q2/Q3 answers | Ask one clarifying question to resolve. |
+| Very large skill (>500 lines estimated) | Warn about token budget. Suggest splitting into multiple skills. |

package/skills/create-skill/references/template-pipeline.md

@@ -0,0 +1,217 @@
+# Template: Pipeline Skill
+
+Use this template when the skill orchestrates multiple distinct operations using sub-agents. Typical for review pipelines, audit workflows, and multi-stage analysis.
+
+**When to use**: Decision B = sequential or parallel Task tool sub-agents.
+
+---
+
+## File Structure
+
+Pipeline skills generate both an orchestrating skill AND dedicated sub-agent files:
+
+```
+skills/{skill-name}/
+├── SKILL.md                              (orchestrating skill)
+├── references/
+│   ├── {stage-specific-reference-1}.md
+│   └── {stage-specific-reference-N}.md
+└── templates/
+    ├── {output-template}.md
+    └── diagnostic-output.yaml
+
+.claude/agents/
+├── {skill-name}-{stage1-name}.md         (sub-agent for stage 1)
+├── {skill-name}-{stage2-name}.md         (sub-agent for stage 2)
+└── {skill-name}-{stageN-name}.md         (sub-agent for stage N)
+```
+
+**Why dedicated sub-agent files**: Sub-agents defined in `.claude/agents/*.md` have deterministic behavior locked into their system prompts — consistent across invocations. Inline sub-agent definitions in skill references produce variable behavior because the orchestrator interprets the reference content differently per run.
+
+**Naming convention**: Sub-agent files are prefixed with the skill name to avoid collisions (e.g., `code-review-security-reviewer.md`, `code-review-type-safety-reviewer.md`).
+
+## Generated SKILL.md Structure
+
+```markdown
+---
+name: {skill-name}
+description: {single-line, trigger-specific, "Use when..." framing}
+user-invocable: true
+skills:
+  - subagent-prompting
+---
+
+# {Skill Title}
+
+{One-paragraph summary describing the pipeline and its purpose.}
+
+---
+
+## When to Use This Skill
+
+{Trigger pattern table + DO NOT use for section.}
+
+---
+
+## Dependencies
+
+| Category | Files | Requirement | When to Load |
+|----------|-------|-------------|--------------|
+| **Stage references** | `references/{name}.md` | **REQUIRED** | Load before spawning stage agent |
+| **Output templates** | `templates/{name}.md` | **REQUIRED** | Include in sub-agent prompt |
+| **Diagnostics** | `templates/diagnostic-output.yaml` | **REQUIRED** | Write at pipeline completion |
+| **Prompting** | `subagent-prompting` skill | **REQUIRED** | Load before spawning any sub-agent |
+| **Sub-agents** | `.claude/agents/{skill-name}-{stage}.md` | **REQUIRED** | Invoked via Task tool per stage |
+
+---
+
+## Usage
+
+```
+/{skill-name} {arguments} [flags]
+```
+
+---
+
+## Pre-Flight Gate (BLOCKING)
+
+**STOP. Before ANY work, you MUST acknowledge what this skill requires.**
+
+This skill uses a **multi-stage pipeline with dedicated sub-agents**. You are the orchestrator, NOT the executor.
+
+### What You MUST Do
+
+1. Load all required dependencies
+2. Execute stages in order (or parallel where specified)
+3. Spawn dedicated sub-agents for each stage via Task tool — do NOT perform their work yourself
+4. Write intermediate stage outputs to `$PROJECT_DIR/logs/`
+5. Write final deliverables (synthesis, reports) to `$PROJECT_DIR/artifacts/`
+6. Write diagnostic YAML to `$PROJECT_DIR/logs/diagnostics/`
+
+### What You MUST NOT Do
+
+- Do NOT skip stages
+- Do NOT perform sub-agent work yourself
+- Do NOT return to user until all log files are written
+- Do NOT spawn sub-agents with run_in_background: true (SA5)
+
+---
+
+## Pipeline
+
+```fsharp
+// {skill-name} pipeline
+Stage0_PreFlight(args)
+|> Stage1_{Name}(input)        // {skill-name}-{stage1} sub-agent — {purpose}
+|> Stage2_{Name}(stage1_output) // {skill-name}-{stage2} sub-agent — {purpose}
+|> Stage3_{Name}(stage2_output) // {skill-name}-{stage3} sub-agent — {purpose}
+|> Diagnostics(all_outputs)
+```
+
+---
+
+## Stage Definitions
+
+### Stage 0: Pre-Flight (Orchestrator)
+
+```
+Stage 0: Pre-Flight
+├── Parse arguments
+├── Load dependencies
+├── Validate inputs exist
+└── Token budget check
+```
+
+### Stage 1: {Name} (Dedicated sub-agent)
+
+```
+Construct prompt using 4-part template:
+├── GOAL: {what this stage achieves}
+├── CONSTRAINTS: {boundaries}
+├── CONTEXT: {input data, reference files to read}
+└── OUTPUT: Write to $PROJECT_DIR/logs/{skill-name}/{stage1-name}-{timestamp}.{ext}
+
+Spawn: Task(subagent_type="{skill-name}-{stage1-name}", prompt=...)
+Read output from $PROJECT_DIR/logs/{skill-name}/
+```
+
+### Stage 2: {Name} (Dedicated sub-agent)
+
+{Same structure as Stage 1, reading Stage 1 output as input.}
+
+### Stage N: Diagnostics (REQUIRED)
+
+Write to `$PROJECT_DIR/logs/diagnostics/{skill-name}-{YYYYMMDD-HHMMSS}.yaml`
+
+---
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Sub-agent returns empty output | Re-spawn once. If still empty, STOP with error. |
+| Stage fails validation | {retry/abort/skip with warning} |
+| Token budget exceeded | Stop, present partial output with explanation. |
+
+---
+
+## Completion Checklist
+
+- [ ] All stages executed
+- [ ] Intermediate stage outputs written to `$PROJECT_DIR/logs/{skill-name}/`
+- [ ] Final deliverables written to `$PROJECT_DIR/artifacts/{skill-name}/{slug}/`
+- [ ] Diagnostic YAML written to `$PROJECT_DIR/logs/diagnostics/`
+- [ ] Results presented to user
+```
+
+## Generated Sub-Agent Structure
+
+Each pipeline stage gets a dedicated agent file at `.claude/agents/{skill-name}-{stage-name}.md`. Use the `references/agent-template.md` structure and follow `references/agent-conventions.md` conventions.
+
+Key requirements for generated sub-agents:
+
+- **System-prompt register**: The agent body defines WHO the agent IS, not step-by-step instructions
+- **Identity reflects stage role**: "You are a security reviewer" not "You are Stage 2"
+- **Single-purpose**: Each sub-agent does one thing well
+- **SA2 compliant**: All intermediate output goes to `$PROJECT_DIR/logs/`, deliverables to `$PROJECT_DIR/artifacts/`
+- **Permissions Setup section**: Documents required tool permissions
+- **150-250 lines each**: Keep sub-agents focused
+
+### Sub-Agent Naming
+
+```
+{skill-name}-{stage-role}.md
+```
+
+Examples:
+- `code-review-security-reviewer.md`
+- `code-review-type-safety-reviewer.md`
+- `test-audit-classifier.md`
+- `test-audit-deep-analyzer.md`
+
+### Sub-Agent Model Selection
+
+| Stage Purpose | Model | Rationale |
+|---------------|-------|-----------|
+| Quick lookups, classification | haiku | Fast, low-cost |
+| Analysis, review, research | sonnet | Balanced capability |
+| Implementation, architecture | opus | Highest quality |
+
+Default to **Sonnet** for most pipeline stages.
+
+## Guidance for Generator
+
+- Generate BOTH the orchestrating SKILL.md AND the sub-agent `.md` files
+- The orchestrating skill references sub-agents by `Task(subagent_type="{name}")`, not inline definitions
+- Every sub-agent stage needs a 4-part prompt (GOAL/CONSTRAINTS/CONTEXT/OUTPUT) in the orchestrating skill
+- Include the `subagent-prompting` skill in the orchestrating skill's frontmatter `skills:` dependency
+- Use the Pre-Flight Gate pattern — without it, Claude skips sub-agent spawning (DEF-P4-005)
+- Model selection per stage: Haiku for lookups, Sonnet for analysis, Opus for writing
+- Each stage writes to `$PROJECT_DIR/logs/{skill-name}/` — the next stage reads from there (SA2/SA4 compliance)
+- Final deliverables (synthesis, reports) go to `$PROJECT_DIR/artifacts/{skill-name}/{slug}/` — NOT to `logs/`
+- **IMPORTANT**: `$PROJECT_DIR` is the project root (where `.claude/` lives). All paths MUST use this prefix. Do NOT write to the skill directory, CWD, or `.claude/skills/`.
+- Include F# pipeline notation for visual workflow documentation
+- Orchestrating skill is typically 200-400 lines
+- Each sub-agent is typically 150-250 lines
+- Read `references/agent-template.md` for the sub-agent file structure
+- Read `references/agent-conventions.md` for system-prompt register and frontmatter conventions

package/skills/create-skill/references/template-reference-heavy.md

@@ -0,0 +1,111 @@
+# Template: Reference-Heavy Skill
+
+Use this template when the skill needs domain-specific reference content that would bloat SKILL.md if inlined. Typical for data-driven skills, pattern libraries, and knowledge bases.
+
+**When to use**: Decision C = references needed, no sub-agents.
+
+---
+
+## File Structure
+
+```
+skills/{skill-name}/
+├── SKILL.md
+└── references/
+    ├── {domain-1}.md
+    ├── {domain-2}.md
+    └── {domain-N}.md
+```
+
+## Generated SKILL.md Structure
+
+```markdown
+---
+name: {skill-name}
+description: {single-line, trigger-specific, "Use when..." framing}
+user-invocable: {true/false}
+---
+
+# {Skill Title}
+
+{One-paragraph summary.}
+
+---
+
+## When to Use This Skill
+
+{Trigger pattern table + DO NOT use for section.}
+
+---
+
+## Dependencies
+
+| Category | Files | Requirement | When to Load |
+|----------|-------|-------------|--------------|
+| **{Category 1}** | `references/{domain-1}.md` | **REQUIRED** | {loading condition} |
+| **{Category 2}** | `references/{domain-2}.md` | **REQUIRED** | {loading condition} |
+
+**Fallback behavior:**
+- If a reference file is missing: {what to do — note in log, continue with available data, or stop}
+
+---
+
+## Usage
+
+{Invocation syntax, arguments, flags.}
+
+---
+
+## Workflow
+
+{Step-by-step instructions referencing the loaded reference files.}
+
+### Step 1: Load References
+
+Read the applicable reference files from the Dependencies table.
+
+### Step 2: {Core Operation}
+
+{Apply the reference data to the user's request.}
+
+### Step 3: {Output}
+
+{Present results to the user.}
+
+---
+
+## Completion Checklist
+
+- [ ] All required reference files loaded
+- [ ] {Domain-specific outcome achieved}
+- [ ] {Output matches expected format}
+```
+
+## Generated Reference File Structure
+
+Each reference file in `references/` should follow this pattern:
+
+```markdown
+# {Domain Name}
+
+{Brief description of what this reference contains and when to use it.}
+
+---
+
+## {Section 1}
+
+{Content organized by how it will be consumed — tables for lookup,
+lists for iteration, prose for context.}
+
+## {Section 2}
+
+{Additional content sections as needed.}
+```
+
+## Guidance for Generator
+
+- Reference files should be 50-150 lines each — enough to be useful, not so much they consume token budget
+- The SKILL.md should NOT duplicate reference content — it should instruct WHEN and HOW to load it
+- Reference files are the domain knowledge; SKILL.md is the workflow
+- Name reference files by domain concept, not by step number (e.g., `security-patterns.md` not `step-2-data.md`)
+- Include a Dependencies table in SKILL.md — this is how consumers know what to load

package/skills/create-skill/references/template-research.md

@@ -0,0 +1,210 @@
+# Template: Research / Multi-Agent Skill
+
+Use this template when the skill spawns multiple agents for parallel or sequential analysis on a topic. Typical for research workflows, brainstorming, and multi-perspective analysis.
+
+**When to use**: Decision B = parallel or sequential multi-agent, AND the skill's purpose is research, exploration, or multi-viewpoint analysis.
+
+---
+
+## File Structure
+
+```
+skills/{skill-name}/
+├── SKILL.md
+├── references/
+│   ├── {viewpoint-or-role-1}.md
+│   ├── {viewpoint-or-role-2}.md
+│   └── {viewpoint-or-role-N}.md
+└── templates/
+    ├── {agent-output-template}.md
+    ├── {synthesis-output-template}.md
+    └── diagnostic-output.yaml
+```
+
+## Generated SKILL.md Structure
+
+```markdown
+---
+name: {skill-name}
+description: {single-line, trigger-specific, "Use when..." framing}
+user-invocable: true
+argument-hint: "<topic, filepath, or directory>"
+skills:
+  - subagent-prompting
+---
+
+# {Skill Title}
+
+{One-paragraph summary: what the skill researches/analyzes, how many agents, parallel vs sequential, what the output is.}
+
+---
+
+## When to Use This Skill
+
+{Trigger pattern table + DO NOT use for section.}
+
+---
+
+## Dependencies
+
+| Category | Files | Requirement | When to Load |
+|----------|-------|-------------|--------------|
+| **Viewpoint/Role definitions** | `references/{name}.md` | **REQUIRED** | Load all before spawning agents |
+| **Agent output template** | `templates/{name}.md` | **REQUIRED** | Include in every agent prompt |
+| **Synthesis template** | `templates/{name}.md` | **REQUIRED** | Use when writing synthesis |
+| **Diagnostics** | `templates/diagnostic-output.yaml` | **REQUIRED** | Write at completion |
+| **Prompting** | `subagent-prompting` skill | **REQUIRED** | Load for 4-part prompt template |
+
+---
+
+## Usage
+
+```
+/{skill-name} <topic> [flags]
+```
+
+---
+
+## Pre-Flight Gate (BLOCKING)
+
+**STOP. This skill spawns multiple sub-agents. You are the orchestrator.**
+
+### What You MUST Do
+
+1. Conduct an iterative interview (AskUserQuestion) to clarify the research topic
+2. Load all viewpoint/role reference files
+3. Spawn agents per the pipeline (parallel or sequential as defined)
+4. Write synthesis from agent outputs
+5. Write diagnostic YAML
+
+### What You MUST NOT Do
+
+- Do NOT analyze the topic yourself — spawn agents
+- Do NOT skip the interview — topic clarity determines agent quality
+- Do NOT skip synthesis — raw agent output is not the deliverable
+
+---
+
+## Pipeline
+
+```fsharp
+// {skill-name} pipeline — {parallel/sequential}
+Interview(topic)
+|> LoadViewpoints(references/)
+|> SpawnAgents([Agent1, Agent2, ..., AgentN])  // {parallel/sequential}
+|> Synthesize(all_agent_outputs)
+|> Present(synthesis)
+|> Diagnostics()
+```
+
+---
+
+## Stage Definitions
+
+### Stage 0: Interview (Orchestrator)
+
+```
+Stage 0: Interview
+├── AskUserQuestion: Clarify topic scope and focus areas
+│   ├── Round 1: 2-3 scoping questions
+│   └── Round 2 (if needed): 1-2 follow-ups for ambiguous answers
+├── Load all viewpoint/role references from references/
+├── Load output templates from templates/
+└── Token budget check
+```
+
+### Stage 1: Agent Spawning ({Parallel/Sequential})
+
+For each viewpoint/role:
+
+```
+Construct prompt using 4-part template:
+├── GOAL: Analyze {topic} from the {viewpoint/role} perspective
+├── CONSTRAINTS: Focus on {viewpoint-specific scope}, read-only analysis
+├── CONTEXT: Topic description, relevant files/codebase areas,
+│   viewpoint definition from references/{name}.md
+└── OUTPUT: Write to $PROJECT_DIR/logs/{skill-name}/{agent-name}.md
+            using templates/{agent-output-template}.md format
+
+Spawn: Task(subagent_type="general-purpose", model="{model}", prompt=...)
+```
+
+**IMPORTANT — output paths**: `$PROJECT_DIR` is the project root directory (where `.claude/` lives). All paths MUST be project-root-relative using this prefix. Do NOT write to the skill directory or CWD.
+
+**Parallel**: Spawn all agents without waiting for each other.
+**Sequential**: Each agent reads previous agent's output before running.
+
+### Stage 2: Synthesis (Orchestrator)
+
+```
+Stage 2: Synthesis
+├── Read all agent outputs from $PROJECT_DIR/logs/{skill-name}/
+├── Identify convergent findings (multiple agents agree)
+├── Identify divergent findings (agents disagree — flag for user)
+├── Write synthesis to $PROJECT_DIR/artifacts/{skill-name}/{topic-slug}/synthesis.md
+│   using templates/{synthesis-output-template}.md format
+└── Present key findings to user
+```
+
+**Note**: Synthesis is a deliverable — it goes to `artifacts/`, not `logs/`. Agent intermediate output stays in `logs/`.
+
+### Stage 3: Diagnostics (REQUIRED)
+
+Write to `$PROJECT_DIR/logs/diagnostics/{skill-name}-{YYYYMMDD-HHMMSS}.yaml`
+
+---
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Agent returns empty output | Re-spawn once. If still empty, note in synthesis and continue with remaining agents. |
+| Agent produces off-topic analysis | Note in synthesis. Do not re-spawn — off-topic output often reveals unexpected angles. |
+| Token budget exceeded mid-pipeline | Complete current agent, skip remaining, synthesize from available outputs. |
+
+---
+
+## Completion Checklist
+
+- [ ] Interview conducted (1-2 rounds)
+- [ ] All agents spawned and completed
+- [ ] All agent outputs in `$PROJECT_DIR/logs/{skill-name}/`
+- [ ] Synthesis written to `$PROJECT_DIR/artifacts/{skill-name}/{topic-slug}/synthesis.md`
+- [ ] Diagnostic YAML written
+- [ ] Key findings presented to user
+```
+
+## Generated Viewpoint/Role File Structure
+
+Each file in `references/` defines one agent's perspective:
+
+```markdown
+# {Viewpoint/Role Name}
+
+## Identity
+
+You are a {role description}. Your analytical focus is {scope}.
+
+## Analytical Lens
+
+When analyzing a topic, you prioritize:
+1. {Priority 1}
+2. {Priority 2}
+3. {Priority 3}
+
+## Output Expectations
+
+- {What findings from this viewpoint typically look like}
+- {Level of specificity expected}
+- {How this viewpoint differs from others in the pipeline}
+```
+
+## Guidance for Generator
+
+- Research/brainstorm skills are the most token-intensive — warn about budget
+- Parallel agents save time but cost more tokens; sequential agents build on each other
+- The synthesis is the deliverable — agent outputs are intermediate artifacts
+- Model selection: Sonnet for research/analysis, Opus for brainstorming/creative
+- 3-5 agents is the sweet spot — fewer lacks diversity, more exceeds token budgets
+- Include `argument-hint` in frontmatter for better UX in the `/` menu
+- Viewpoint/role reference files should be 40-80 lines each