butterfreezone

name	butterfreezone
description	BUTTERFREEZONE Generation Skill
role	implementation
capabilities	{"schema_version":1,"read_files":true,"search_code":true,"write_files":false,"execute_commands":{"allowed":[{"command":".claude/scripts/butterfreezone-gen.sh","args":["*"]},{"command":".claude/scripts/butterfreezone-validate.sh","args":["*"]}],"deny_raw_shell":true},"web_access":false,"user_interaction":false,"agent_spawn":false,"task_management":false}
cost-profile	lightweight
parallel_threshold	3000
timeout_minutes	5
zones	{"system":{"path":".claude","permission":"read"},"state":{"paths":["grimoires/loa"],"permission":"read"},"app":{"paths":["src","lib","app"],"permission":"none"}}

BUTTERFREEZONE Generation Skill

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.

<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>

- 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) ## 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

<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>