scaffolding

claude-scaffolding

Portable Claude Code configuration: 11 agents, 32 skills, 15 commands, 8 hooks, spec-driven workflows. Installs as a Claude Code plugin.

Overview

claude-scaffolding is a portable, markdown-only Claude Code configuration. It provides multi-agent orchestration, a library of reusable skills, guardrail hooks, and spec-driven workflows — everything ships as plain markdown and runs entirely on the Claude Code runtime, with no backend, database, or long-running process required.

Why use this

• Spec-driven workflows — OpenSpec-style specs keep work grounded and reproducible.
• 11 specialized agents — analyst, architect, developer, reviewer, debugger, and more, each with a focused role.
• Parallel multi-agent orchestration — fan out work across agents and coordinate results.
• Opinionated guardrail hooks — 8 safety and lifecycle hooks block destructive commands and enforce conventions.
• Extensible & self-improving — /create-skill scaffolds your own scaffolding-compatible skills, and /learn closes the loop by distilling reusable insights from finished conversations.
• Zero backend required — pure markdown and Claude Code runtime; no database, server, or process to run.

Install

1. /plugin marketplace add komluk/scaffolding
2. /plugin install scaffolding@komluk-scaffolding
3. /reload-plugins                       ← REQUIRED: Claude Code does not hot-reload the agent registry

Optionally, run /init-scaffolding once per project to create .scaffolding/ and copy CLAUDE.md into the repo (see Per-project setup). Then start delegating: Task(subagent_type="scaffolding:developer", prompt="...").

Without /reload-plugins the subagent_type registry is not refreshed after install — Task(subagent_type="scaffolding:developer") will return Agent type not found. Restarting claude works as an alternative.

The installed plugin lives under ~/.claude/plugins/ — primarily in the versioned cache/komluk-scaffolding/ subtree, with marketplaces/komluk-scaffolding/ as the marketplace clone. Default values (pytest, npm test, (project), etc.) are baked in. To override per-project, edit the rendered CLAUDE.md after running /init-scaffolding.

Per-project setup: /init-scaffolding

After the plugin is installed, run /init-scaffolding from the project root. It creates the .scaffolding/ directory structure (agent memory, conversations, worktrees, OpenSpec specs, reports), adds .scaffolding/ to .gitignore, and copies CLAUDE.md + settings.json + hooks/ into the project. Idempotent — safe to re-run; CLAUDE.md and settings.json are always overwritten with the latest plugin version, hook scripts are always copied.

Scenario	Run init?
Solo project	Optional — the plugin's SessionStart hook injects the routing protocol on every session
Team repo (others clone without the plugin)	Yes — CLAUDE.md in-repo means the protocol travels with the code
CI / automation reads the repo	Yes — a committed CLAUDE.md gives reproducible context

Agent memory

Agents share a file-based, 3-tier memory protocol — all plain markdown under .scaffolding/ of the project. Memory is auto-injected into an agent's context when a task starts: shared tier always, agent tier when the agent name is known, conversation tier when a conversation_id is provided. Each file is capped at 200 lines. Read-only agents (architect, reviewer) cannot write memory — they report findings in their output instead. This protocol is the always-on default; an optional cross-device semantic memory backend adds vector recall on top — enable it per device with /memory enable (see Optional backend-dependent features).

Tier	File	Scope
Shared	.scaffolding/agent-memory/shared/KNOWLEDGE.md	Whole-project facts, written/read by any agent
Agent	.scaffolding/agent-memory/agents/{agent-name}/MEMORY.md	Per-agent domain knowledge
Conversation	.scaffolding/conversations/{conversation_id}/agent-memory/context.md	Per-conversation context and handoffs

Common gotchas