0xhoneyjar/butterfreezone

BUTTERFREEZONE Generation Skill

<objective> Generate and validate BUTTERFREEZONE.md — the agent-grounded README that provides token-efficient, provenance-tagged, checksum-verified project context for AI agents. Every claim cites its source. No butter, no hype. </objective>

<zone_constraints>

• READ: .loa.config.yaml (configuration)
• READ: grimoires/loa/ground-truth/ (Tier 1 input)
• READ: package.json, Cargo.toml, etc. (Tier 2 input)
• WRITE: BUTTERFREEZONE.md (output)
• EXECUTE: .claude/scripts/butterfreezone-gen.sh
• EXECUTE: .claude/scripts/butterfreezone-validate.sh </zone_constraints>

<input_guardrails>

• danger_level: safe
• No PII or secrets in output (redaction enforced by gen script)
• No network access required </input_guardrails>

<constraints> - C-BFZ-001: ALWAYS run validation after generation - C-BFZ-002: NEVER skip provenance tagging - C-BFZ-003: ALWAYS respect word budget (3200 total, 800 per section) - C-BFZ-004: NEVER include secrets in output (redaction is enforced) - C-BFZ-005: ALWAYS preserve manual sections (sentinel markers) </constraints> <workflow> ## Phase 1: Configuration Check

# Check if butterfreezone is enabled
enabled=$(yq '.butterfreezone.enabled // true' .loa.config.yaml 2>/dev/null || echo "true")
if [[ "$enabled" != "true" ]]; then
    echo "BUTTERFREEZONE is disabled in config. Enable with butterfreezone.enabled: true"
    exit 0
fi

Phase 2: Generation

Default Mode (generate + validate)

# Generate BUTTERFREEZONE.md
.claude/scripts/butterfreezone-gen.sh --verbose --json

# Check exit code
# 0 = success
# 2 = config error
# 3 = Tier 3 bootstrap (limited output)

Validate-Only Mode

# Validate existing file
.claude/scripts/butterfreezone-validate.sh --file BUTTERFREEZONE.md --json

Dry-Run Mode

# Preview without writing
.claude/scripts/butterfreezone-gen.sh --dry-run

Phase 3: Validation

# Always validate after generation
.claude/scripts/butterfreezone-validate.sh --file BUTTERFREEZONE.md

# With strict mode if requested
.claude/scripts/butterfreezone-validate.sh --file BUTTERFREEZONE.md --strict

Phase 4: Report

Report results to user:

• Generation tier used (1/2/3)
• Word count vs budget
• Validation results (pass/warn/fail per check)
• Any redacted content warnings
• Staleness status </workflow>

<error_handling> | Error | Cause | Resolution | |-------|-------|------------| | Exit 2 from gen | Config error | Check .loa.config.yaml | | Exit 3 from gen | Tier 3 bootstrap | Add package.json or run /ride first | | Validation FAIL | Structure issues | Review and fix reported issues | | Validation WARN | Advisory issues | Regenerate or accept advisory | </error_handling>