ClawScaffold

Spec-first target lifecycle manager for OpenClaw agents, skills, and pipelines.

Features

• Interactive interviews — guided create/adopt/extend workflows for agents, skills, and pipelines
• Spec-first paradigm — canonical YAML specs define targets; runtime artifacts are compiled output
• 8 audit checks — automated readiness assessment before deployment
• Pipeline registry — track managed targets with lifecycle status
• Dual-format skills — 7 SKILL.md files for both OpenClaw and Claude Code
• Plugin hooks — abstract interfaces for governance, outbound gate, and MCP integrations

Installation

pip install clawscaffold

With optional spec validation:

pip install clawscaffold[spec]

Quick Start

# Initialize a project
clawscaffold init

# Create a new agent spec
clawscaffold create --name sales/coach --kind agent

# Adopt an existing agent
clawscaffold adopt --name sales/coach --source agents/sales/coach/SOUL.md --kind agent

# Audit a target
clawscaffold audit --name sales/coach

# Render spec to runtime files
clawscaffold render --id sales/coach

Install Skills

# For Claude Code
./scripts/install-skills.sh claude-code

# For OpenClaw
./scripts/install-skills.sh openclaw

CLI Commands

Command	Description
init	Initialize a clawscaffold project (creates .clawscaffold marker)
create	Create a new target spec
adopt	Adopt an existing runtime artifact into managed scope
audit	Run readiness checks against a target
interview	Start an interactive interview for target creation/adoption
render	Compile spec to runtime files
validate	Validate spec structure and content
promote	Promote a target to managed status
enforce	Enforce managed registry consistency
install-skills	Install SKILL.md files to Claude Code or OpenClaw
sync-paperclip	Sync agents to Paperclip for org chart and task management

Paperclip Adapter (Optional)

ClawScaffold includes an optional adapter for Paperclip that bulk-registers agents with hierarchy, generates API keys, and keeps agent instructions in sync.

The adapter activates only when Paperclip is detected (PAPERCLIP_API_URL env var or pnpm paperclipai CLI available). No Python Paperclip dependencies are added.

# Preview what would be imported (no changes made)
clawscaffold sync-paperclip --dry-run

# Bulk-register all catalog agents to Paperclip
PAPERCLIP_COMPANY_ID=<uuid> clawscaffold sync-paperclip

# Filter to a department
clawscaffold sync-paperclip --filter "executive/*"

# Register and generate API keys
clawscaffold sync-paperclip --generate-keys

# Sync a single agent after create/adopt
clawscaffold create --kind agent --id sales/coach --sync-paperclip

What it does:

• Generates .paperclip.yaml portable format from catalog/agents/ specs
• Converts SOUL.md files to Paperclip AGENTS.md with frontmatter
• Shells out to pnpm paperclipai company import for bulk registration
• Generates API keys via pnpm paperclipai agent local-cli
• Stores keys at ~/.openclaw/workspace/paperclip-agent-keys/<key>.json

Using with ClawSpec

ClawSpec is the contract-first QA framework for OpenClaw. When used together, ClawScaffold auto-generates ClawSpec test scenarios during adoption and creation workflows.

Install both:

pip install clawscaffold[spec]   # includes clawspec as optional dependency

When ClawSpec is installed, clawscaffold adopt and clawscaffold create automatically generate:

• tests/scenarios.yaml — smoke, negative, and identity test contracts
• tests/handoffs/*.yaml — handoff contracts for multi-agent delegation
• Coverage ledger entries for the adopted target

Without ClawSpec installed, these steps are skipped gracefully — the scaffolder works standalone for spec management and auditing.

# Adopt an agent — ClawSpec scenarios auto-generated
clawscaffold adopt --name sales/coach --source agents/sales/coach/SOUL.md --kind agent

# Verify the generated tests
clawspec validate agents/sales/coach
clawspec run agents/sales/coach --dry-run

Related Projects

• ClawSpec — Contract-first QA for OpenClaw skills and agents (29 assertion types, Opik observability, regression baselines)
• ClawWrap — Spec-first outbound message routing gate (policy enforcement, audit trail)
• OpenClaw — Local-first AI agent framework (LLM + chat channels + Markdown skills)
• Paperclip — AI agent orchestration platform (org chart, task management, conversations)

Development

git clone https://github.com/austinmao/clawscaffold.git
cd clawscaffold
pip install -e ".[dev]"
pytest

OpenClaw Gateway Plugin

ClawScaffold ships with a gateway plugin (scaffold-planner) that registers scaffold interview tools directly in the OpenClaw gateway. The plugin provides four tools: scaffold_analyze, scaffold_next_question, scaffold_answer, and scaffold_finalize.

Installation

1. Copy the extensions/scaffold-planner/ directory into your OpenClaw workspace:

cp -r extensions/scaffold-planner/ ~/.openclaw/extensions/scaffold-planner/

2. Register the plugin in your ~/.openclaw/openclaw.json:

{
  "extensions": {
    "scaffold-planner": {
      "repoRoot": "/path/to/your/workspace",
      "timeoutMs": 30000
    }
  }
}

3. Restart the gateway:

openclaw gateway restart

Plugin Configuration

Option	Type	Default	Description
repoRoot	string	$OPENCLAW_WORKSPACE or cwd	Workspace root containing the clawscaffold package
pythonBin	string	python3	Path to Python binary
timeoutMs	integer	30000	CLI execution timeout in milliseconds

Registered Tools

scaffold_analyze, scaffold_next_question, scaffold_answer, scaffold_finalize

See the openclaw.plugin.json for the full config schema.

ClawSuite

This package is part of ClawSuite — the OpenClaw agent infrastructure toolkit.

Package	Description	Repo
ClawPipe	Config-driven pipeline orchestration	austinmao/clawpipe
ClawSpec	Contract-first testing for skills & agents	austinmao/clawspec
ClawWrap	Outbound policy & conformance engine	austinmao/clawwrap
ClawAgentSkill	Skill discovery, scanning & adoption	austinmao/clawagentskill
ClawScaffold	Agent/skill scaffold interviews	austinmao/clawscaffold
ClawInterview	Pipeline interview compilation & execution	(coming soon)

All packages include OpenClaw gateway plugins for autonomous agent access.

License

MIT