Build Kit Locally

Skill: Build and Publish Kit

Build a Bottlerocket kit (core-kit or kernel-kit) and publish it to a local OCI registry for development testing and validation.

Roles

You (reading this file) are the orchestrator.

⚠️ You do NOT read files in phases/ — pass them to subagents via context_files. Subagents read their phase file and execute it.

Orchestrator Loop

workspace = f"planning/build-kit-{kit_name}"
bash(f"mkdir -p {workspace}",

input_data = {"kit_name": kit_name, "arch": arch}
write("create", f"{workspace}/input.json", file_text=json.dumps(input_data))

while True:
    result = bash(f"python3 skills/build-kit-locally/next-step.py {workspace}",
    action = json.loads(result)
    
    if action["type"] == "done":
        verify = fs_read("Line", f"{workspace}/04-verify.md", 1, 100)
        break
    
    if action["type"] == "gate_failed":
        log(f"Gate failed: {action['reason']}")
        break
    
    if action["type"] == "spawn":
        r = spawn(
            action["prompt"],
            context_files=action["context_files"],
            context_data=action["context_data"],
            allow_tools=True
        )
        write("create", f"{workspace}/{action['output_file']}", file_text=r.response)

Handling Exceptions

The state machine handles the happy path. When things go wrong, exercise judgment:

Don't silently advance past failures. Either retry, fail explicitly, or document gaps.

Anti-Patterns

Phases

1. SETUP: Ensure local registry is running and configure Infra.toml
2. BUILD: Build the kit for specified architecture
3. PUBLISH: Publish built kit to local OCI registry
4. VERIFY: Verify kit was successfully published

Inputs

Create {{workspace}}/input.json with:

• kit_name: Name of the kit (e.g., "bottlerocket-core-kit")
• arch: Architecture to build (default: "x86_64", or "aarch64")

Outputs

• {{workspace}}/01-setup.md: Registry and Infra.toml configuration status
• {{workspace}}/02-build.md: Build artifacts and status
• {{workspace}}/03-publish.md: Published tags and registry info
• {{workspace}}/04-verify.md: Verification results and next steps

When to Use

• Making changes to kit packages and testing them in variants
• Iterative development on kits
• Before building a variant image that depends on kit changes

Prerequisites

• Docker installed and running
• Kit repository cloned in kits/ directory
• FOREST_ROOT environment variable set

Common Issues

Registry not running:

Error: connection refused

Solution: The SETUP phase will start the registry automatically

Infra.toml not configured:

Error: vendor 'local' not found

Solution: The SETUP phase creates Infra.toml if missing

Docker permission denied: Solution: Ensure user is in docker group and Docker daemon is running

Next Steps

After the skill completes:

1. Update variant's Twoliter.toml to reference the new kit version
2. Run make update in the variant repo
3. Build the variant with cargo make