@qball-inc/the-bulwark 1.0.0

package/skills/create-skill/references/template-script-driven.md

@@ -0,0 +1,172 @@
+# Template: Script-Driven Skill
+
+Use this template when the skill requires deterministic code execution (AST analysis, data transforms, file processing) alongside LLM stages. Typical for analysis tools that combine static tooling with LLM judgment.
+
+**When to use**: Decision C = scripts needed for deterministic execution.
+
+---
+
+## File Structure
+
+```
+skills/{skill-name}/
+├── SKILL.md
+├── scripts/
+│   ├── {script-1}.ts (or .sh, .py)
+│   └── {script-N}.ts
+└── references/
+    ├── {reference-1}.md
+    └── {reference-N}.md
+```
+
+## Generated SKILL.md Structure
+
+```markdown
+---
+name: {skill-name}
+description: {single-line, trigger-specific, "Use when..." framing}
+user-invocable: true
+skills:
+  - subagent-prompting  # If sub-agents used
+---
+
+# {Skill Title}
+
+{One-paragraph summary. Mention both deterministic (script) and LLM stages.}
+
+---
+
+## When to Use This Skill
+
+{Trigger pattern table + DO NOT use for section.}
+
+---
+
+## Dependencies
+
+| Category | Files | Requirement | When to Load |
+|----------|-------|-------------|--------------|
+| **Scripts** | `scripts/{name}.ts` | **REQUIRED** | Run at Stage 0 before LLM stages |
+| **References** | `references/{name}.md` | **REQUIRED** | Load for LLM stage context |
+
+**Script execution**: Scripts run via the project task runner (e.g., `just {recipe-name} {args}`). Do NOT run scripts via `npx` or `node` directly unless no task runner recipe exists.
+
+---
+
+## Usage
+
+```
+/{skill-name} {arguments} [flags]
+```
+
+---
+
+## Pre-Flight Gate (BLOCKING)
+
+**STOP. Scripts MUST run before any LLM analysis.**
+
+### What You MUST Do
+
+1. Run all required scripts first — they produce deterministic metadata
+2. Read script output before proceeding to LLM stages
+3. LLM stages consume script output as structured input
+
+### What You MUST NOT Do
+
+- Do NOT skip script execution
+- Do NOT substitute LLM judgment for script output
+- Do NOT proceed to LLM stages if scripts fail
+
+---
+
+## Pipeline
+
+```fsharp
+// {skill-name} pipeline
+Stage0_Scripts(args)           // Deterministic — run scripts via task runner
+|> Stage1_{Name}(script_data)  // LLM stage — {purpose}
+|> Stage2_{Name}(stage1_output) // LLM stage — {purpose}
+|> Diagnostics(all_outputs)
+```
+
+---
+
+## Stage Definitions
+
+### Stage 0: Script Execution (Deterministic)
+
+Run scripts and capture output:
+
+```
+Scripts:
+├── `just {recipe-1} {target}` → {output-path-1}
+├── `just {recipe-2} {target}` → {output-path-2}
+└── Read all script outputs before proceeding
+```
+
+**Script output format**: Scripts produce JSON or YAML to a known path. The orchestrator reads this structured data and passes it to LLM stages.
+
+### Stage 1: {Name} (LLM Stage)
+
+{LLM analysis that consumes script output as structured input.}
+
+### Stage N: Diagnostics (REQUIRED)
+
+Write to `$PROJECT_DIR/logs/diagnostics/{skill-name}-{YYYYMMDD-HHMMSS}.yaml`
+
+---
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Script fails to execute | Check: Is the script executable? Is the task runner recipe defined? Report error and STOP. |
+| Script produces empty output | Report: "Script {name} produced no output for {target}." STOP. |
+| Script output malformed | Report the parse error. Do NOT proceed with LLM stages on bad data. |
+
+---
+
+## Completion Checklist
+
+- [ ] All scripts executed successfully
+- [ ] Script output consumed by LLM stages
+- [ ] All log files written
+- [ ] Diagnostic YAML written
+- [ ] Results presented to user
+```
+
+## Generated Script Structure
+
+Scripts should be self-contained and produce structured output:
+
+```typescript
+// scripts/{name}.ts
+// Purpose: {what this script does}
+// Input: {command-line args}
+// Output: {JSON/YAML to stdout or file}
+
+import { /* minimal deps */ } from '...';
+
+// Parse args
+const target = process.argv[2];
+if (!target) {
+  console.error('Usage: {script-name} <target>');
+  process.exit(1);
+}
+
+// Process
+const result = analyze(target);
+
+// Output structured data
+console.log(JSON.stringify(result, null, 2));
+```
+
+## Guidance for Generator
+
+- Scripts must be self-contained — no imports from project-specific modules
+- Scripts produce structured output (JSON/YAML) that LLM stages consume
+- The task runner recipe is the execution interface — scripts are not invoked directly
+- Stage 0 (scripts) must complete before any LLM stages start
+- If the skill needs a Justfile recipe, include it in the post-generation summary as a manual setup step
+- Script-driven skills are the most complex type — expect 200-400 lines for SKILL.md plus script files
+- Consider whether a simpler approach (LLM-only) would work before committing to scripts

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

@@ -0,0 +1,80 @@
+# Template: Simple Skill
+
+Use this template when the skill is a vanilla SKILL.md with no supporting files. Typical for guideline skills, knowledge layers, and single-purpose utilities.
+
+**When to use**: Decision C = no references, no templates, no scripts.
+
+---
+
+## File Structure
+
+```
+skills/{skill-name}/
+└── SKILL.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 of what this skill does and why it exists.}
+
+---
+
+## When to Use This Skill
+
+**Load this skill when the user request matches ANY of these patterns:**
+
+| Trigger Pattern | Example User Request |
+|-----------------|---------------------|
+| {pattern-1} | "{example request 1}" |
+| {pattern-2} | "{example request 2}" |
+| {pattern-3} | "{example request 3}" |
+
+**DO NOT use for:**
+- {anti-trigger 1} (use {alternative} instead)
+- {anti-trigger 2}
+
+---
+
+## Usage
+
+{If user-invocable: invocation syntax and arguments.}
+{If not user-invocable: how consuming skills/agents reference this.}
+
+---
+
+## Instructions
+
+{Core skill content. For simple skills this is the main body:
+guidelines, rules, patterns, or knowledge that Claude should apply.}
+
+{Use numbered steps for procedural skills.}
+{Use tables for rule-based skills.}
+{Use sections for knowledge skills.}
+
+---
+
+## Completion Checklist
+
+Before returning to the user, verify:
+
+- [ ] {Outcome 1 achieved}
+- [ ] {Outcome 2 achieved}
+- [ ] {No unintended side effects}
+```
+
+## Guidance for Generator
+
+- Keep the skill under 150 lines for simple skills
+- The Instructions section is the heart — make it specific and actionable
+- Do NOT add references/ or templates/ directories — this is a vanilla skill
+- Do NOT add diagnostic output unless the skill performs multi-step work
+- If the skill is `user-invocable: false`, it's consumed by other skills — describe the consumer interface

package/skills/create-subagent/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: create-subagent
+description: Generates single-purpose Claude Code sub-agents for use via the Task tool. Use when creating dedicated sub-agents, scaffolding agent definitions, or generating agents with diagnostics and permissions setup.
+user-invocable: true
+argument-hint: "<description-or-name> [--doc <requirements-path>]"
+skills:
+  - subagent-prompting
+  - anthropic-validator
+---
+
+# Create Sub-Agent
+
+Generates a complete single-purpose Claude Code sub-agent from a description or requirements document. Conducts an adaptive interview to understand the agent's identity and mission, determines tool permissions and supporting configuration, spawns a Sonnet sub-agent to generate the agent file, validates with anthropic-validator, and presents the scaffold with architectural decisions.
+
+Sub-agents are invoked via `Task(subagent_type=...)` and run in a forked context. They perform a single focused task and return results. They **cannot** spawn other sub-agents — pipeline orchestration belongs in skills, not agents.
+
+---
+
+## When to Use This Skill
+
+**Load this skill when the user request matches ANY of these patterns:**
+
+| Trigger Pattern | Example User Request |
+|-----------------|---------------------|
+| Sub-agent creation | "Create a sub-agent for X", "Make an agent for X" |
+| Agent scaffolding | "Scaffold an agent", "Set up a new agent" |
+| Agent generation | "Generate an agent that does X" |
+| Dedicated worker | "Create a dedicated agent for this sub-agent role" |
+| Task tool agent | "I need an agent I can invoke via Task tool" |
+
+**DO NOT use for:**
+- Creating pipeline orchestration (use `create-skill` — it generates the orchestrating skill + sub-agent files)
+- Creating Agent Teams leads (use `create-skill` with the research template)
+- Creating skills (use `create-skill`)
+- Editing existing agents (edit directly)
+- Debugging agent issues (use `issue-debugging`)
+- Validating existing agents (use `anthropic-validator`)
+
+---
+
+## Dependencies
+
+| Category | Files | Requirement | When to Load |
+|----------|-------|-------------|--------------|
+| **Decision framework** | `references/decision-framework.md` | **REQUIRED** | Load at Stage 0 for interview + classification |
+| **Agent conventions** | `references/agent-conventions.md` | **REQUIRED** | Include in Stage 2 generator prompt |
+| **Content guidance** | `references/content-guidance.md` | **REQUIRED** | Include in Stage 2 generator prompt |
+| **Agent template** | `references/template-single-agent.md` | **REQUIRED** | Load at Stage 2 |
+| **Diagnostic template** | `templates/diagnostic-output.yaml` | **REQUIRED** | Use at Stage 6 |
+| **Subagent prompting** | `subagent-prompting` skill | **REQUIRED** | Load at Stage 0 for 4-part prompt template |
+
+**Fallback behavior:**
+- If content-guidance is missing: Proceed without it, note in diagnostics (output quality will be lower)
+
+---
+
+## Usage
+
+```
+/create-subagent <description-or-name>
+/create-subagent --doc <requirements-document>
+```
+
+**Arguments:**
+- `<description-or-name>` — Free-text description of the desired agent, or an agent name to start from
+- `--doc <path>` — Path to a requirements document. Extracts interview answers from it instead of asking fresh.
+
+**Examples:**
+- `/create-subagent a code security reviewer that checks for OWASP vulnerabilities` — Start from description
+- `/create-subagent --doc plans/task-briefs/P4.4-implementer.md` — Start from requirements doc
+- `/create-subagent market-analyst` — Start from a name
+
+---
+
+## Mandatory Execution Checklist (BINDING)
+
+**Every item below is mandatory. No deviations. No substitutions. No skipping.**
+
+This skill uses a 6-stage pipeline. You are the orchestrator. Follow every item in order. Do NOT return to the user until all applicable items are checked.
+
+- [ ] **Stage 0 — Pre-Flight**: Arguments parsed (description, name, or --doc)
+- [ ] **Stage 0 — Pre-Flight**: Decision framework, agent conventions, and content guidance loaded
+- [ ] **Stage 0 — Pre-Flight**: Adaptive interview conducted (1-2 rounds via AskUserQuestion)
+- [ ] **Stage 0 — Pre-Flight**: Routing check completed (pipeline/teams → redirect to create-skill and STOP, OR single → proceed)
+- [ ] **Stage 1 — Classify**: Two decisions made (tool permissions, supporting configuration)
+- [ ] **Stage 1 — Classify**: Classification presented to user and confirmed via AskUserQuestion
+- [ ] **Stage 2 — Generate**: Sonnet sub-agent spawned via Task tool (you do NOT generate the file yourself)
+- [ ] **Stage 2 — Generate**: Generated agent file verified to exist in working directory
+- [ ] **Stage 2 — Generate**: Agent uses system-prompt register (identity statement, not task steps)
+- [ ] **Stage 3 — Validate**: `/anthropic-validator` invoked via Skill tool (manual review is NOT a substitute)
+- [ ] **Stage 3 — Validate**: Validator output read and findings counted
+- [ ] **Stage 3 — Validate**: Manual checks completed (single-line description, system-prompt register, permissions section)
+- [ ] **Stage 4 — Refine**: If validation found critical/high issues, Sonnet sub-agent spawned to fix (max 2 retries)
+- [ ] **Stage 5 — Deploy**: Agent file deployed from working directory to `.claude/agents/`
+- [ ] **Stage 5 — Deploy**: Working directory cleaned up
+- [ ] **Stage 5 — Present**: Post-generation summary presented with architectural decisions
+- [ ] **Stage 5 — Present**: Permissions setup steps communicated
+- [ ] **Stage 5 — Present**: Next steps communicated (this is a scaffold, not production-ready output)
+- [ ] **Stage 6 — Diagnostics**: Diagnostic YAML written to `$PROJECT_DIR/logs/diagnostics/`
+
+---
+
+## Pipeline
+
+```fsharp
+// create-subagent pipeline
+PreFlight(args)                              // Stage 0: Orchestrator — parse input, interview, routing check
+|> Classify(interview_answers)               // Stage 1: Orchestrator — two independent decisions
+|> Generate(classification, template, conventions) // Stage 2: Sonnet sub-agent — produce agent file
+|> Validate(generated_output)                // Stage 3: Orchestrator — run anthropic-validator
+|> Refine(validator_findings)                // Stage 4: Sonnet sub-agent (conditional, max 2 retries)
+|> DeployAndPresent(working_dir, target_dir)  // Stage 5: Orchestrator — deploy to target + post-generation summary
+|> Diagnostics()                             // Stage 6: Orchestrator — write YAML
+```
+
+---
+
+## Stage Definitions
+
+### Stage 0: Pre-Flight (Orchestrator)
+
+```
+Stage 0: Pre-Flight
+├── Parse arguments (description, name, or --doc path)
+├── Load references/decision-framework.md
+├── Load references/agent-conventions.md
+├── Load references/content-guidance.md
+├── Load subagent-prompting skill
+├── If --doc provided:
+│   ├── Read the requirements document
+│   ├── Extract answers to Q1-Q5 from the document
+│   └── Present extracted answers to user for confirmation via AskUserQuestion
+├── If no --doc:
+│   └── AskUserQuestion: Present all 5 core questions from decision-framework.md
+│       ├── Q1: What is this agent's identity and mission? (2-3 invocation examples)
+│       ├── Q2: What tools does it need access to?
+│       ├── Q3: Single focused task, or multiple stages/operations?
+│       ├── Q4: Does it need structured diagnostic output?
+│       └── Q5: Restricted permissions or full access?
+├── If complexity detected in answers (Q3 = "multiple stages"):
+│   └── AskUserQuestion: Follow-up questions per decision-framework.md
+│       ├── Q6: Do stages depend on each other's output?
+│       ├── Q7: Do workers need direct communication?
+│       └── Q8-Q10: Additional context-specific follow-ups
+├── ROUTING CHECK (after all interview answers received):
+│   ├── If Q3 = "multiple stages" AND (Q6 = "dependent" OR Q7 = "direct comms"):
+│   │   └── STOP PIPELINE. Present redirect message to user:
+│   │       "This use case requires a pipeline skill that orchestrates multiple sub-agents.
+│   │        Sub-agents are single-purpose — they can't spawn other sub-agents.
+│   │
+│   │        Use /create-skill instead. It will generate:
+│   │        - An orchestrating skill (SKILL.md) with pipeline stages
+│   │        - Dedicated sub-agent files (.claude/agents/*.md) for each stage
+│   │
+│   │        The generated sub-agents will have deterministic behavior locked into their
+│   │        system prompts, and the orchestrating skill handles sequencing, error handling,
+│   │        and synthesis."
+│   │       Do NOT proceed to Stage 1. Return to user.
+│   └── Otherwise: Continue to Stage 1
+├── Determine agent name (from input or derived from description)
+│   └── Target: .claude/agents/{agent-name}.md
+├── Set working directory: tmp/create-subagent/{agent-name}/
+│   └── All generation and refinement happens here to avoid .claude/ edit approval storms
+│       Files are deployed to the target directory only after validation passes (Stage 5)
+└── Token budget check (warn if >30% consumed)
+```
+
+**Interview behavior**: Maximum 2 AskUserQuestion rounds. Present Q1-Q5 together in round 1. Follow-ups (if needed) in round 2. Do NOT ask questions one at a time.
+
+### Stage 1: Classify (Orchestrator)
+
+Apply the two-decision classification from `references/decision-framework.md`:
+
+```
+Stage 1: Classify
+├── Decision A: Tool Permissions
+│   ├── Full access → no tools: list in frontmatter (inherits all)
+│   ├── Restricted → tools: [specific list] in frontmatter
+│   ├── If Write/Edit needed → include quality gate guidance in protocol
+│   └── If Bash needed → include allowed/forbidden command lists in protocol
+├── Decision B: Supporting Configuration
+│   ├── Always: Permissions Setup section
+│   ├── If diagnostics needed (Q4 = yes): diagnostic output section + schema
+│   └── If diagnostics needed: subagent-output-templating in skills: dependency
+└── Present classification to user via AskUserQuestion:
+    ├── "Tool permissions: {full/restricted: [list]} — {reason}"
+    ├── "Configuration: {list} — {reason}"
+    └── "Proceed with generation? [Yes / Adjust]"
+```
+
+**MANDATORY**: Wait for user confirmation before proceeding to Stage 2. If user selects "Adjust", re-classify with their feedback.
+
+### Stage 2: Generate (Sonnet sub-agent)
+
+```
+Stage 2: Generate
+├── Read references/template-single-agent.md
+├── Construct prompt using 4-part template (GOAL/CONSTRAINTS/CONTEXT/OUTPUT):
+│   ├── GOAL: Generate a complete, structurally correct single-purpose sub-agent
+│   │   definition. The agent must use system-prompt register and include all
+│   │   required sections (Pre-Flight, Mission, Protocol, Output, Permissions).
+│   ├── CONSTRAINTS:
+│   │   ├── Write in SYSTEM-PROMPT REGISTER — WHO the agent IS, not WHAT to do
+│   │   ├── Open with identity statement: "You are a..."
+│   │   ├── Use present tense for behavioral descriptions
+│   │   ├── Description MUST be a single line (multi-line breaks discovery)
+│   │   ├── Description MUST use role-based trigger framing
+│   │   ├── Include Pre-Flight Gate with MUST/MUST NOT (binding language)
+│   │   ├── Include DO/DO NOT mission section
+│   │   ├── Include Tool Usage Constraints for every tool in frontmatter
+│   │   ├── Include Permissions Setup section (tool permissions unsolved per #10093)
+│   │   ├── Do NOT add unnecessary files (no README, CHANGELOG, LICENSE)
+│   │   ├── Do NOT use emojis in generated content
+│   │   └── Keep agent under 250 lines
+│   ├── CONTEXT:
+│   │   ├── Classification from Stage 1 (both decisions)
+│   │   ├── User's interview answers (identity, mission, tools from Q1-Q5)
+│   │   ├── Template: references/template-single-agent.md
+│   │   ├── Agent conventions: references/agent-conventions.md
+│   │   ├── Content guidance: references/content-guidance.md
+│   │   ├── Instruction: "Read 1-2 existing agents from the codebase for structural
+│   │   │   reference (use Glob to find .claude/agents/*.md)"
+│   │   ├── Target output path: .claude/agents/{agent-name}.md (final deployment location)
+│   │   └── Working directory: tmp/create-subagent/{agent-name}/
+│   └── OUTPUT:
+│       ├── Write agent file to {working-directory}/{agent-name}.md
+│       └── Return summary: file path with line count
+├── Spawn: Task(description="Generate agent file", subagent_type="general-purpose",
+│          model="sonnet", prompt=...)
+├── Read generator output (file path + summary)
+└── Verify file was created (Read {working-directory}/{agent-name}.md)
+```
+
+### Stage 3: Validate (Orchestrator)
+
+```
+Stage 3: Validate
+├── FIRST: Invoke /anthropic-validator (this is the PRIMARY validation — NOT optional)
+│   ├── Use the Skill tool: Skill(skill="anthropic-validator", args="{working-directory}/{agent-name}.md")
+│   ├── Do NOT substitute manual review for this step
+│   └── Do NOT proceed past this node until the Skill tool has been invoked
+├── Read validator output
+├── Check for critical/high findings:
+│   ├── 0 critical AND 0 high → proceed to Stage 5 (skip Stage 4)
+│   └── Any critical or high → proceed to Stage 4 (refine)
+├── THEN: Manual checks (these supplement the validator, they do NOT replace it)
+│   ├── Check description is single-line (read agent file, verify no multiline description)
+│   ├── Check system-prompt register (body opens with identity, not task steps)
+│   └── Check Permissions Setup section exists
+└── Stage 3 exit gate:
+    ├── [ ] /anthropic-validator was invoked via the Skill tool (not manual review)
+    ├── [ ] Validator output was read and findings counted
+    └── If either is unchecked, Stage 3 is NOT complete — go back and invoke the validator
+```
+
+### Stage 4: Refine (Sonnet sub-agent, conditional, max 2 retries)
+
+This stage only runs if Stage 3 found critical or high issues.
+
+```
+Stage 4: Refine (attempt {N} of 2)
+├── Construct prompt using 4-part template:
+│   ├── GOAL: Fix all critical and high findings from anthropic-validator
+│   ├── CONSTRAINTS:
+│   │   ├── Only fix the specific issues identified — do not restructure
+│   │   ├── Preserve the existing agent content and identity
+│   │   ├── Description must remain single-line
+│   │   └── Must remain in system-prompt register
+│   ├── CONTEXT:
+│   │   ├── Validator findings (critical and high items with descriptions)
+│   │   ├── Current generated file (read from {working-directory}/{agent-name}.md)
+│   │   └── Agent conventions: references/agent-conventions.md
+│   └── OUTPUT: Edit file at {working-directory}/{agent-name}.md to fix findings
+├── Spawn: Task(description="Fix validator findings", subagent_type="general-purpose",
+│          model="sonnet", prompt=...)
+├── Re-run Stage 3 (validate)
+├── If still failing after 2 retries:
+│   └── Proceed to Stage 5 with caveats noted
+└── Token budget check
+```
+
+### Stage 5: Deploy & Present (Orchestrator)
+
+```
+Stage 5: Deploy & Present
+├── Deploy: Move {working-directory}/{agent-name}.md to .claude/agents/{agent-name}.md
+│   ├── This is the ONLY point where the file is written to .claude/
+│   └── Clean up: Remove {working-directory}/ after successful copy
+├── Read generated agent file from .claude/agents/{agent-name}.md for summary
+├── Present to user:
+│   ├── "Generated agent at: .claude/agents/{agent-name}.md"
+│   ├── "Lines: {count}"
+│   ├── "Architectural decisions:"
+│   │   ├── "Tool permissions: {full/restricted: [list]} — {reason}"
+│   │   └── "Configuration: {list} — {reason}"
+│   ├── "Validation: {pass/fail with details}"
+│   ├── If caveats: "Unresolved issues: {list}"
+│   ├── "Permissions to configure:"
+│   │   └── {List tool permissions that must be added to settings.json}
+│   └── "Next steps:"
+│       ├── "1. Review and customize the identity and expertise sections"
+│       ├── "2. Adjust tool permissions in .claude/settings.json"
+│       ├── "3. Test by invoking via Task tool: Task(subagent_type=\"{name}\", prompt=\"...\")"
+│       ├── "4. Add project-specific protocol steps as needed"
+│       └── "5. Configure Stop hook if diagnostic output is needed"
+└── Note: This is a scaffold, not production-ready output (generate-and-customize contract)
+```
+
+### Stage 6: Diagnostics (REQUIRED)
+
+**MANDATORY**: Write diagnostic output after every invocation. This cannot be skipped.
+
+```
+Stage 6: Diagnostics
+├── Write to: $PROJECT_DIR/logs/diagnostics/create-subagent-{YYYYMMDD-HHMMSS}.yaml
+│   └── Use templates/diagnostic-output.yaml schema
+└── Include:
+    ├── Input: description/name/doc path
+    ├── Interview: questions asked, rounds completed
+    ├── Routing: redirected (true/false), reason if redirected
+    ├── Classification: both decisions
+    ├── Generation: file created, line count, model used
+    ├── Validation: pass/fail, findings count, retry count
+    └── Outcome: success/partial/failure/redirected
+```
+
+---
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Generator sub-agent returns empty output | Re-spawn once with reinforced instructions. If still empty, STOP: "Generation failed. Please try with a more detailed description." |
+| anthropic-validator finds critical issues | Stage 4 retry (max 2). After 2 retries, present with caveats. |
+| anthropic-validator unavailable | Skip validation, note in diagnostics, warn user: "Validation skipped — run /anthropic-validator manually." |
+| Interview answers are ambiguous | Ask 1-2 follow-up questions (max 2 AskUserQuestion rounds total). |
+| Pipeline/teams detected in interview | STOP pipeline. Redirect to `/create-skill` with guidance message. Write diagnostic with outcome: redirected. |
+| Token budget exceeded | Stop at current stage, present partial output with explanation. |
+| Agent file already exists at target path | AskUserQuestion: "Agent {name} already exists at .claude/agents/{name}.md. Overwrite / Choose different name / Cancel?" |
+| Working directory already exists | Silently remove and recreate tmp/create-subagent/{agent-name}/ (working dirs are ephemeral) |
+| User rejects classification | Re-classify with user's feedback. Max 2 classification rounds. |
+| Generated agent uses task-instruction register | Stage 4 refine with specific instruction to rewrite in system-prompt register. |
+
+---
+
+## Token Budget Management
+
+| Checkpoint | Threshold | Action |
+|------------|-----------|--------|
+| After Pre-Flight | >30% consumed | Warn: "Remaining budget may limit validation and refinement." |
+| After Generate | >55% consumed | Warn: "Approaching budget. Validation + refinement may be limited." |
+| After Validate | >65% consumed | Skip refinement if needed, present as-is with caveats. |
+