Hermetic SpecKit Skill

This skill provides hermetic, isolated development environments using Dagger container-use with GitHub SpecKit workflow for spec-driven development.

Architecture

User Prompt → Main Claude (Orchestrator)
                    │
                    ├─► Create container-use environment
                    │
                    └─► Spawn subagents for SpecKit phases:
                        1. /speckit.specify → spec.md
                        2. /speckit.clarify → (orchestrator responds)
                        3. /speckit.plan → plan.md
                        4. /speckit.tasks → tasks.md
                        5. /speckit.analyze → validation
                        │
                        └─► Report to user for approval
                              │
                              └─► Fan out implementation to parallel envs

Variables

• •REPO_SOURCE: The absolute path to the current repository
• •ENVIRONMENT_PREFIX: speckit- (prefix for environment names)

Prerequisites

container-use MCP server must be configured:

claude mcp add container-use -- container-use stdio

MCP Tools (container-use)

Critical Rules

1. •ALWAYS use container-use MCP for ALL file/code operations - Never use local filesystem tools
2. •DO NOT use git CLI - container-use handles git automatically
3. •Capture environment ID - Store in context, use for all subsequent operations
4. •Report access commands - Always tell user: container-use checkout <env_id>

Workflow

Phase 1: Environment Setup

When user requests a complex build task:

1. •

   Create environment:

   code

   environment_create(
       environment_source=REPO_SOURCE,
       title="<descriptive task name>"
   )
   

2. •

   Configure for Python (if needed):

   code

   environment_config(
       environment_id=<env_id>,
       config={
           "base_image": "python:3.12-slim",
           "setup_commands": ["pip install --upgrade pip"]
       }
   )
   

3. •

   Capture the environment ID in your context

Phase 2: SpecKit Specification

Spawn a subagent (or run inline) to execute SpecKit phases:

Step 2.1: Specify

• •Generate .specify/spec.md with the feature specification
• •Include: What, Why, User Stories, Success Metrics
• •Write using environment_file_write

Step 2.2: Clarify (Self-Response)

• •Read the spec and identify ambiguities
• •Generate clarifying questions
• •Orchestrator responds to questions (not user)
• •Update spec with clarifications

Step 2.3: Plan

• •Generate .specify/plan.md with implementation plan
• •Include: Architecture, Data Model, API Contracts, File Structure
• •Reference the constitution if it exists

Step 2.4: Tasks

• •Generate .specify/tasks.md with atomic tasks
• •Mark parallel-safe tasks with [P]
• •Ensure each task is < 4 hours of work
• •Include file paths and dependencies

Step 2.5: Analyze

• •Cross-check spec.md, plan.md, tasks.md for consistency
• •Flag any gaps or conflicts
• •Update artifacts as needed

Phase 3: User Checkpoint

STOP and report to user:

SpecKit artifacts ready for review:

Environment: <env_id>
Branch: container-use/<env_id>

To review:
- container-use checkout <env_id>
- container-use diff <env_id>

Generated artifacts:
- .specify/spec.md - Feature specification
- .specify/plan.md - Implementation plan
- .specify/tasks.md - Task breakdown

Proceed with implementation? [Y/n]

Wait for user approval before implementation.

Phase 4: Implementation (Fan-Out)

For each task in tasks.md:

1. •

   Identify parallel tasks (marked with [P])

2. •

   Create environment per task:

   code

   environment_create(
       environment_source=REPO_SOURCE,
       title="Task: <task description>"
   )
   

3. •

   Execute task via subagent:

   • •Read task details from tasks.md
   • •Write code using environment_file_write
   • •Run tests using environment_run_cmd
   • •Iterate until tests pass
4. •

   Mark complete in tasks.md when tests pass

5. •

   Report environment to user:

   code

   Task complete: <task description>
   View: container-use checkout <task_env_id>
   

Phase 5: Final Report

After all tasks complete:

Implementation complete!

Environments created:
- <main_env_id> (SpecKit artifacts)
- <task1_env_id> (Task 1 implementation)
- <task2_env_id> (Task 2 implementation)
...

To merge all work:
1. container-use checkout <main_env_id>
2. Review each task branch
3. Merge as desired

To clean up:
- Environments persist until manually deleted

Examples

Example 1: Build a REST API

User: "Build a REST API for user authentication with JWT"

Orchestrator:

1. •Creates environment: speckit-auth-api
2. •Spawns subagent for SpecKit phases
3. •Generates spec.md, plan.md, tasks.md
4. •Reports to user for approval
5. •Fans out to: task-1-models, task-2-routes, task-3-jwt
6. •Each subagent implements in parallel
7. •Reports all environments to user

Example 2: Refactor a Module

User: "Refactor the payment module to use the strategy pattern"

Orchestrator:

1. •Creates environment: speckit-payment-refactor
2. •Reads existing code via environment_file_read
3. •Generates refactoring spec and plan
4. •Tasks breakdown by component
5. •Implements with tests

Troubleshooting

"Container not found":

• •Verify environment exists: environment_list
• •Re-create if needed: environment_create

"Python not found":

• •Configure base image: environment_config with python:3.12-slim

"Changes not showing":

• •All changes auto-commit to branch
• •Use container-use checkout <env_id> to view

References

• •Container-Use Architecture
• •Architecting Robust Agentic Systems
• •dagger/container-use
• •github/spec-kit