@qball-inc/the-bulwark 1.0.0

package/skills/continuous-feedback/references/specialize-general.md

@@ -0,0 +1,98 @@
+# Specialization: General
+
+This reference guides the general Analyzer on what improvement patterns to look for in collected learnings. The general Analyzer is the catch-all — it processes learnings that don't fit neatly into test-audit or code-review, plus any items tagged with "general" skill_relevance.
+
+## Target Scope
+
+The general Analyzer examines improvements for ANY skill or agent in the project, including:
+
+- Skill authoring patterns (frontmatter, structure, instructions)
+- Sub-agent behavior and prompt engineering
+- Pipeline orchestration patterns
+- Hook system configuration and behavior
+- Session workflow and handoff patterns
+- Token management and context window optimization
+- Template and reference document conventions
+
+## What to Look For
+
+### Instruction Hardening (DEF-P4-005 Pattern)
+
+Learnings about LLM compliance with skill/agent instructions:
+
+- Cases where the LLM ignored or reinterpreted instructions
+- Missing BINDING language (MUST/MUST NOT/MANDATORY/REQUIRED)
+- Pre-Flight Gate gaps that allowed invalid inputs through
+- SC1-SC3 compliance issues (skill instructions treated as advisory)
+
+**Action**: Propose instruction strengthening for affected skills with specific MUST/MUST NOT language. Reference DEF-P4-005 as the canonical example.
+
+### Workflow Improvements
+
+Learnings about process efficiency:
+
+- Pipeline stage ordering improvements
+- Parallel vs sequential execution discoveries
+- Token budget management techniques
+- Error handling and retry patterns that worked well
+- Pre-flight alignment patterns that reduced post-synthesis iterations
+
+**Action**: Propose workflow updates to affected skill SKILL.md files or pipeline templates.
+
+### Sub-Agent Behavior Patterns
+
+Learnings about how sub-agents behave:
+
+- Prompt patterns that produce better/worse agent output
+- Model selection insights (when Haiku/Sonnet/Opus is appropriate)
+- Agent output quality patterns (verbosity, hallucination, instruction compliance)
+- Context window management for sub-agents
+
+**Action**: Propose sub-agent prompt improvements or model selection updates.
+
+### Configuration and Convention Updates
+
+Learnings about project configuration:
+
+- Frontmatter field discoveries (what works, what silently breaks)
+- File naming conventions that improve or degrade discoverability
+- Hook configuration patterns
+- Sync and portability requirements
+
+**Action**: Propose configuration or convention updates to affected files.
+
+### Template and Reference Improvements
+
+Learnings about document templates:
+
+- Output template fields that are missing or unused
+- Reference document gaps (missing guidance for common scenarios)
+- Diagnostic output improvements
+- Cross-skill reference patterns
+
+**Action**: Propose template or reference updates with specific field additions or removals.
+
+### Tool and Platform Behaviors
+
+Learnings about Claude Code platform behaviors:
+
+- Framework observations (FW-OBS-NNN patterns)
+- Tool quirks and workarounds
+- Platform limitations that affect skill design
+- New platform features that enable improvements
+
+**Action**: Propose skill updates that account for discovered platform behaviors.
+
+## Analysis Output Structure
+
+For each improvement identified, produce:
+
+1. **What was learned** — the specific learning item(s) driving this
+2. **What it affects** — which file(s) and section(s) in the target project
+3. **Proposed improvement** — specific enough for the Proposer to create a copy-paste-ready change
+4. **Priority** — High (causes real failures or blocks workflows), Medium (improves quality), Low (nice to have)
+5. **Evidence** — reference the source learning item IDs (L-NNN)
+
+## Catch-All Responsibility
+
+The general Analyzer MUST process any learning items that were not fully covered by specialized Analyzers. If an item has `skill_relevance: ["test-audit", "general"]`, the test-audit Analyzer handles the test-audit angle, but the general Analyzer should still examine it for broader implications (e.g., instruction hardening patterns that apply across all skills).

package/skills/continuous-feedback/references/specialize-test-audit.md

@@ -0,0 +1,81 @@
+# Specialization: Test Audit
+
+This reference guides the test-audit Analyzer on what improvement patterns to look for in collected learnings.
+
+## Target Skill Structure
+
+The test-audit skill (`skills/test-audit/` or `.claude/skills/test-audit/`) typically contains:
+
+| Component | Purpose |
+|-----------|---------|
+| `SKILL.md` | Main skill document with pipeline stages and instructions |
+| `references/mock-detection-patterns.md` | Mock detection heuristics and violation examples |
+| `references/deep-mode-detection.md` | Deep mode analysis prompt for LLM-based classification |
+| `references/test-classification.md` | Test type classification rules (unit/integration/e2e) |
+| `references/assertion-patterns.md` | Real behavior verification patterns |
+| AST scripts (`scripts/`) | TypeScript AST analysis for mock detection |
+
+## What to Look For
+
+### Mock Detection Gaps
+
+Learnings that reveal mock patterns the current detection misses:
+
+- New violation patterns not covered in `mock-detection-patterns.md`
+- Property-access chains (e.g., `mockOrder.id` used in new objects)
+- Framework-specific mock patterns (e.g., new testing libraries)
+- Edge cases where AST scripts produce false positives or false negatives
+- Scale vs Deep mode disagreements that reveal detection blind spots
+
+**Action**: Propose additions to `references/mock-detection-patterns.md` with specific violation examples.
+
+### Assertion Pattern Additions
+
+Learnings about how real behavior should be verified:
+
+- New component types that need verification approaches
+- Patterns where `toHaveBeenCalled` should be replaced with output checks
+- File system, network, or process verification patterns discovered during debugging
+
+**Action**: Propose additions to assertion patterns references with concrete before/after examples.
+
+### AST Script Coverage
+
+Learnings about AST analysis accuracy:
+
+- Cases where AST scripts miss violations that LLM deep mode catches
+- Cases where AST scripts flag false positives
+- New TypeScript/JavaScript patterns that need AST support
+- Performance observations (files where AST analysis is slow or times out)
+
+**Action**: Propose specific AST pattern additions or corrections. Include the code pattern that should be detected.
+
+### Classification Improvements
+
+Learnings about test type classification:
+
+- Tests misclassified as unit when they're integration (or vice versa)
+- New heuristics for distinguishing test types
+- Section-boundary detection improvements (where one file has multiple test types)
+
+**Action**: Propose classification rule updates with examples of correct vs incorrect classification.
+
+### Instruction Hardening
+
+Learnings about LLM compliance with test-audit instructions:
+
+- Cases where the LLM re-classified AST findings (DEF-P4-005 pattern)
+- Missing BINDING language that allowed instruction drift
+- Pre-Flight Gate gaps or missing threshold checks
+
+**Action**: Propose instruction strengthening with specific MUST/MUST NOT language.
+
+## Analysis Output Structure
+
+For each improvement identified, produce:
+
+1. **What was learned** — the specific learning item(s) driving this
+2. **What it affects** — which test-audit component (reference file, AST script, SKILL.md section)
+3. **Proposed improvement** — specific enough for the Proposer to create a copy-paste-ready change
+4. **Priority** — High (current misses cause real failures), Medium (improves coverage), Low (nice to have)
+5. **Evidence** — reference the source learning item IDs (L-NNN)

package/skills/create-skill/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: create-skill
+description: Generates Claude Code skills from requirements using adaptive interview, complexity classification, and iterative validation. Use when creating new skills, scaffolding skill structure, or generating skills with sub-agent orchestration.
+disable-model-invocation: true
+argument-hint: "<description-or-name> [--doc <requirements-path>]"
+skills:
+  - subagent-prompting
+---
+
+# Create Skill
+
+Generates a complete Claude Code skill from a description or requirements document. Conducts an adaptive interview to understand the skill's purpose, classifies it into one of 5 structural types, spawns a Sonnet sub-agent to generate the files, validates with anthropic-validator, and presents the scaffold with architectural decisions.
+
+---
+
+## When to Use This Skill
+
+**Load this skill when the user request matches ANY of these patterns:**
+
+| Trigger Pattern | Example User Request |
+|-----------------|---------------------|
+| Skill creation | "Create a new skill", "Make a skill for X" |
+| Scaffolding | "Scaffold a skill", "Set up a new skill" |
+| Generation | "Generate a skill that does X" |
+| Skill design | "Design a skill for X", "I need a skill that does X" |
+
+**DO NOT use for:**
+- Editing existing skills (edit directly)
+- Creating standalone sub-agents (use `create-subagent`)
+- Debugging skill issues (use `issue-debugging`)
+- Validating existing skills (use `anthropic-validator`)
+
+---
+
+## Dependencies
+
+| Category | Files | Requirement | When to Load |
+|----------|-------|-------------|--------------|
+| **Decision framework** | `references/decision-framework.md` | **REQUIRED** | Load at Stage 0 for interview + classification |
+| **Content guidance** | `references/content-guidance.md` | **REQUIRED** | Include in Stage 2 generator prompt |
+| **Skill templates** | `references/template-*.md` | **REQUIRED** | Load the matching template at Stage 2 |
+| **Agent template** | `references/agent-template.md` | **REQUIRED** | Include in Stage 2 prompt when template = pipeline |
+| **Agent conventions** | `references/agent-conventions.md` | **REQUIRED** | Include in Stage 2 prompt when template = pipeline |
+| **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 a template file is missing: Use the closest available template, note mismatch in diagnostics
+- If content-guidance is missing: Proceed without it, note in diagnostics (output quality will be lower)
+
+---
+
+## Usage
+
+```
+/create-skill <description-or-name>
+/create-skill --doc <requirements-document>
+```
+
+**Arguments:**
+- `<description-or-name>` — Free-text description of the desired skill, or a skill name to start from
+- `--doc <path>` — Path to a requirements document. Extracts interview answers from it instead of asking fresh.
+
+**Examples:**
+- `/create-skill a skill that audits dependency versions` — Start from description
+- `/create-skill --doc plans/task-briefs/P5.4-create-skill.md` — Start from requirements doc
+- `/create-skill changelog-generator` — 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 and content guidance loaded
+- [ ] **Stage 0 — Pre-Flight**: Adaptive interview conducted (1-2 rounds via AskUserQuestion)
+- [ ] **Stage 1 — Classify**: Three decisions made (context mode, sub-agent pattern, supporting files)
+- [ ] **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 files yourself)
+- [ ] **Stage 2 — Generate**: Generated files verified to exist in working directory
+- [ ] **Stage 2 — Generate**: If pipeline template — sub-agent files generated in {working-directory}/agents/
+- [ ] **Stage 3 — Validate**: `/anthropic-validator` invoked via Skill tool (manual review is NOT a substitute)
+- [ ] **Stage 3 — Validate**: If pipeline template — `/anthropic-validator` invoked on each sub-agent file
+- [ ] **Stage 3 — Validate**: Validator output read and findings counted
+- [ ] **Stage 3 — Validate**: Manual checks completed (single-line description, no unnecessary files)
+- [ ] **Stage 4 — Refine**: If validation found critical/high issues, Sonnet sub-agent spawned to fix (max 2 retries)
+- [ ] **Stage 5 — Deploy**: Skill files deployed from working directory to target directory
+- [ ] **Stage 5 — Deploy**: If pipeline template — sub-agent files deployed to `.claude/agents/`
+- [ ] **Stage 5 — Deploy**: Working directory cleaned up
+- [ ] **Stage 5 — Present**: Post-generation summary presented with architectural decisions
+- [ ] **Stage 5 — Present**: If pipeline template — sub-agent permissions 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-skill pipeline
+PreFlight(args)                              // Stage 0: Orchestrator — parse input, adaptive interview
+|> Classify(interview_answers)               // Stage 1: Orchestrator — three independent decisions
+|> Generate(classification, template, examples) // Stage 2: Sonnet sub-agent — produce skill files
+|> 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/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 does this skill do? (concrete invocation examples)
+│       ├── Q2: Needs conversation history, or can run in isolation?
+│       ├── Q3: Orchestrates multiple distinct operations?
+│       ├── Q4: How much domain-specific reference content? (None/Some/Extensive)
+│       └── Q5: Produces structured output matching a specific format?
+├── If complexity detected in answers:
+│   └── AskUserQuestion: Follow-up questions per decision-framework.md
+│       ├── Q6: Do operations depend on each other's output?
+│       ├── Q7: Do workers need direct communication?
+│       ├── Q8: Error handling between stages?
+│       └── Q9-Q10: Context-specific follow-ups
+├── Determine target directory for generated skill
+│   └── Default: skills/{skill-name}/ (or user-specified path)
+├── Set working directory: tmp/create-skill/{skill-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 three-decision classification from `references/decision-framework.md`:
+
+```
+Stage 1: Classify
+├── Decision A: Context Mode
+│   ├── Needs conversation history → inline (no fork)
+│   ├── Isolated multi-step work → context: fork
+│   └── Simple guideline/knowledge → inline (warn if fork requested)
+├── Decision B: Sub-Agent Pattern
+│   ├── Single operation → no sub-agents
+│   ├── Multiple dependent operations → sequential Task tool
+│   ├── Multiple independent operations → parallel Task tool
+│   └── Direct worker communication → Agent Teams (experimental warning)
+├── Decision C: Supporting Files
+│   ├── No references, no templates → vanilla SKILL.md
+│   ├── Domain references needed → add references/
+│   ├── Structured output format → add templates/
+│   └── Deterministic code needed → add scripts/
+├── Map decisions → template (1 of 5 from decision-framework.md)
+└── Present classification to user via AskUserQuestion:
+    ├── "Context: {inline/fork} — {reason}"
+    ├── "Sub-agents: {none/sequential/parallel/AT} — {reason}"
+    ├── "Supporting files: {list} — {reason}"
+    ├── "Template: {template name}"
+    └── "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 the selected template from references/template-{type}.md
+├── Construct prompt using 4-part template (GOAL/CONSTRAINTS/CONTEXT/OUTPUT):
+│   ├── GOAL: Generate a complete, structurally correct skill matching the
+│   │   classification. The skill must activate reliably and instruct clearly.
+│   ├── CONSTRAINTS:
+│   │   ├── Follow the template structure exactly
+│   │   ├── Description MUST be a single line (multi-line breaks discovery)
+│   │   ├── Description MUST use "Use when..." trigger framing
+│   │   ├── Include "When to Use" table with ≥3 trigger patterns
+│   │   ├── Include "DO NOT use for" section with ≥2 anti-triggers
+│   │   ├── If skill has sub-agents: include Pre-Flight Gate with MUST/MUST NOT
+│   │   ├── If skill has sub-agents: include subagent-prompting in skills: dependency
+│   │   ├── Do NOT add unnecessary files (no README, CHANGELOG, LICENSE)
+│   │   ├── Do NOT use emojis in generated content
+│   │   └── Keep total SKILL.md under target line count for the type
+│   │       (simple: 150, reference-heavy: 200, pipeline: 400, script: 400, research: 400)
+│   ├── CONTEXT:
+│   │   ├── Classification from Stage 1 (all three decisions + template)
+│   │   ├── User's interview answers (concrete examples from Q1)
+│   │   ├── Selected template: references/template-{type}.md
+│   │   ├── Content guidance: references/content-guidance.md
+│   │   ├── If pipeline template: references/agent-template.md (sub-agent file structure)
+│   │   ├── If pipeline template: references/agent-conventions.md (system-prompt register, frontmatter)
+│   │   ├── Instruction: "Read 1-2 existing skills of the same type from the
+│   │   │   codebase for structural reference (use Glob to find skills/*/SKILL.md)"
+│   │   ├── If pipeline template: "Read 1-2 existing agents from .claude/agents/*.md
+│   │   │   for sub-agent structural reference"
+│   │   ├── Target output directory (final deployment location)
+│   │   └── Working directory: tmp/create-skill/{skill-name}/
+│   └── OUTPUT:
+│       ├── Write SKILL.md to {working-directory}/SKILL.md
+│       ├── Write reference files to {working-directory}/references/ (if applicable)
+│       ├── Write template files to {working-directory}/templates/ (if applicable)
+│       ├── Write script files to {working-directory}/scripts/ (if applicable)
+│       ├── If pipeline template: Write sub-agent files to {working-directory}/agents/
+│       │   ├── One .md file per pipeline stage: {skill-name}-{stage-name}.md
+│       │   ├── Each sub-agent follows agent-template.md structure
+│       │   ├── Each sub-agent uses system-prompt register (agent-conventions.md)
+│       │   └── Orchestrating SKILL.md references sub-agents by Task(subagent_type="{name}")
+│       └── Return summary: list of files created with line counts
+├── Spawn: Task(description="Generate skill files", subagent_type="general-purpose",
+│          model="sonnet", prompt=...)
+├── Read generator output (file list + summary)
+└── Verify files were created (Glob for {working-directory}/**)
+```
+
+### 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}/")
+│   ├── Do NOT substitute manual review for this step
+│   └── Do NOT proceed past this node until the Skill tool has been invoked
+├── If pipeline template: Also validate each sub-agent file in {working-directory}/agents/
+│   └── Run /anthropic-validator on each {skill-name}-{stage-name}.md
+├── 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 SKILL.md, verify no multiline description)
+│   ├── If pipeline template: Check each sub-agent uses system-prompt register
+│   └── Check no unnecessary files (no README.md, CHANGELOG.md, etc.)
+└── 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 skill content and structure
+│   │   └── Description must remain single-line
+│   ├── CONTEXT:
+│   │   ├── Validator findings (critical and high items with descriptions)
+│   │   ├── Current generated files (read from working directory)
+│   │   └── Content guidance: references/content-guidance.md
+│   └── OUTPUT: Edit files in {working-directory}/ 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 skill: Move skill files from {working-directory}/ to {target-directory}/
+│   ├── Copy directory tree preserving structure (SKILL.md, references/, templates/, scripts/)
+│   └── This is the ONLY point where skill files are written to the final location
+├── If pipeline template: Deploy sub-agents
+│   ├── Move {working-directory}/agents/*.md to .claude/agents/
+│   └── Each sub-agent file: .claude/agents/{skill-name}-{stage-name}.md
+├── Clean up: Remove {working-directory}/ after successful copy
+├── Read all generated files for summary
+├── Present to user:
+│   ├── "Generated skill at: {target-directory}/"
+│   ├── If pipeline: "Generated sub-agents at: .claude/agents/"
+│   ├── "Files created:"
+│   │   └── List each file with line count (skill files + sub-agent files)
+│   ├── "Architectural decisions:"
+│   │   ├── "Context: {fork/inline} — {reason}"
+│   │   ├── "Sub-agents: {none/sequential/parallel/AT} — {reason}"
+│   │   └── "Supporting files: {list} — {reason}"
+│   ├── "Skill type: {template used}"
+│   ├── "Validation: {pass/fail with details}"
+│   ├── If caveats: "Unresolved issues: {list}"
+│   ├── If pipeline: "Sub-agent permissions to configure:"
+│   │   └── {List tool permissions for each sub-agent that must be added to settings.json}
+│   └── "Next steps:"
+│       ├── "1. Review and customize the generated instructions"
+│       ├── "2. Test activation by asking Claude to invoke it"
+│       ├── "3. Iterate on trigger patterns until activation is reliable"
+│       ├── "4. Add domain-specific content to reference files"
+│       └── If pipeline: "5. Configure tool permissions for sub-agents in .claude/settings.json"
+└── 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-skill-{YYYYMMDD-HHMMSS}.yaml
+│   └── Use templates/diagnostic-output.yaml schema
+└── Include:
+    ├── Input: description/name/doc path
+    ├── Interview: questions asked, rounds completed
+    ├── Classification: all three decisions + template selected
+    ├── Generation: files created, line counts, model used
+    ├── Validation: pass/fail, findings count, retry count
+    └── Outcome: success/partial/failure
+```
+
+---
+
+## 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). |
+| User requests Agent Teams | Include experimental warning: "Agent Teams requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. This is an experimental feature." |
+| Token budget exceeded | Stop at current stage, present partial output with explanation. |
+| Target directory already exists | AskUserQuestion: "Directory {path} already exists. Overwrite / Choose different name / Cancel?" |
+| Working directory already exists | Silently remove and recreate tmp/create-skill/{skill-name}/ (working dirs are ephemeral) |
+| User rejects classification | Re-classify with user's feedback. Max 2 classification rounds. |
+
+---
+
+## Token Budget Management
+
+| Checkpoint | Threshold | Action |
+|------------|-----------|--------|
+| After Pre-Flight | >30% consumed | Warn: "Pipeline agents will consume significant context." |
+| 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. |
+