claude-scaffolding
Spec-driven multi-agent orchestration for Claude Code — pure markdown, zero backend,
runs on the stock runtime. 13 agents, 36 skills, 19 commands, 15 hooks, per-phase model
tiers, opt-in lifecycle hooks, optional cross-device semantic memory.
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
Pure markdown, zero backend, runs on stock Claude Code.
Everything is markdown files — agents, skills, commands, hooks. No database, no backend service, no long-running process. All orchestration logic runs in Claude Code's built-in environment. Optional (not required) semantic-memory backend for cross-device recall; gracefully degrades without it.
Multi-agent orchestration purpose-built for software engineering.
- 13 specialized agents — analyst, architect, developer, reviewer, debugger, prompt-engineer, mcp-builder, and more, each with a focused role.
- Spec-driven workflows — OpenSpec-style specs keep work grounded and reproducible.
- Parallel multi-agent coordination — fan out work across agents and route results via peer-to-peer comms.
- Opinionated guardrails — 15 safety and lifecycle hooks block destructive commands, hard-deny disallowed subagents, and enforce per-phase conventions.
- Extensible —
/create-skill scaffolds your own orchestration-compatible skills; /learn distills insights into reusable skills and memory entries.
Highlights
Everything below is opt-in or default-safe — existing installs behave exactly
as before until you set a flag or invoke a new agent. See the CHANGELOG
for full release history and current version.
- Two new agents (roster 11 → 13):
prompt-engineer (system prompts,
guardrail rules, prompt evals, LLM-judge rubrics, injection defense) and
mcp-builder (design/build/test MCP servers, tool schemas, transport, auth
launchers).
- Six new hooks: soft auto-init advice (
auto-init-check), opt-in
auto-format (post-edit-format), opt-in desktop/terminal notifications
(notify), opt-in completion nudge (completion-nudge), a hard block on the
general-purpose/explore subagents (block-subagent), and a warn-only
500-line file check (file-size-warn).
- Per-phase model tiers:
analyst, architect, and reviewer declare
model: opus + effort: high; developer stays inherit. The reviewer on a
higher tier breaks same-model self-review and records a cross_model flag in
its report. The plugin emits only literal sonnet/opus/haiku; backend
mapping lives on the aiproxy/litellm side — see docs/model-tiers.md.
/init-rules command: scaffolds opt-in, path-scoped nested CLAUDE.md
rule files so per-area conventions lazy-load only where relevant, while routing
stays always-loaded.- Lighter routing prompt: critical rules emphasized with
<important>, and
forced delegation softened so trivial Q&A may be answered directly while real
engineering work is still delegated.
- Skill performance:
context: fork on four heavy skills (ui-ux-pro-max,
mui-styling, logging-standards, monitoring-observability) and
!`command` dynamic injection in the git/worktree/context-engineering skills.
- Experimental agent-teams mode behind
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
— see docs/agent-teams.md.
Opt-in flags
All flags are off by default; the plugin's behavior is unchanged unless you set them.
| Flag | Default | Effect |
|---|
SCAFFOLDING_AUTOFORMAT | off | =1 enables post-edit-format.sh — auto-formats the single edited file (ruff/black, prettier, dotnet format); never blocks. |
SCAFFOLDING_NOTIFY | off | =1 enables notify.sh — desktop/terminal notification on turn-finish or input-needed. |
SCAFFOLDING_COMPLETION_NUDGE | off | =1 advisory nudge to finish the delegation chain; =block enforces it (loop-guarded). |
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS | off | =1 enables the experimental agent-teams mode (see docs/agent-teams.md). |
📹 Demo: (asciinema/GIF coming soon)
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 |
Requirements
What's inside
claude-scaffolding/
├── agents/ 13 agents (analyst, architect, coordinator, developer,
│ debugger, devops, gitops, mcp-builder, optimizer,
│ prompt-engineer, researcher, reviewer, tech-writer)
├── skills/ 36 skills (api-design, error-handling, pattern-recognition,
│ skill-authoring, spec-*, mui-styling, python-patterns,
│ sofa-search, testing-strategy, ...)
├── commands/ 19 slash commands: 9 top-level (context, create-skill,
│ init-openspec, init-rules, init-scaffolding, learn, memory,
│ doctor, sofa) + 10 in `commands/specs/` (apply, archive,
│ bulk-archive, continue, explore, ff, new, onboard, sync,
│ verify) — namespaced OpenSpec commands
├── hooks/ 15 safety + lifecycle hooks (block-destructive-rm,
│ block-subagent, block-env-write, pre-commit-validation,
│ post-edit-format, completion-nudge, file-size-warn, notify,
│ session-start-protocol, auto-init-check, memory-project-id, ...)
├── templates/ Shared agent reference docs (output-frontmatter schema,
│ agents/skills overview, responsibility matrix)
├── validators/ Validation scripts (circuit-breaker, validate-agent-output)
├── output-styles/ output-frontmatter definition
├── workflows/ YAML workflow and coordinate definitions
├── CLAUDE.md Main project prompt
└── settings.json Hooks + statusline + permissions
Optional backend-dependent features
A few skills have optional features that can use an external backend if one is
available — for example, semantic-memory-store can persist embeddings to a
vector store, and ui-ux-pro-max can draw on a local dataset. When no such
backend is present, these skills degrade gracefully: the agent skips the
relevant section rather than crashing, and all core functionality continues to
work as pure markdown.
Cross-device semantic memory (/memory)
The semantic-memory-mcp / semantic-memory-store skills can be backed by a
self-hosted mem0 service (PostgreSQL + pgvector,
with a local LLM and embeddings via Ollama). When enabled,
agents persist and recall insights across sessions and devices through
semantic_search / semantic_recall / semantic_store, on top of the always-on
file-based memory.
It is opt-in and personal:
/memory enable # wire the backend into Claude Code (user scope) — run once per device
/memory disable # disconnect this device (stored memories are kept)
/memory status # show whether it's wired and reachable
- Off by default. Nothing connects until you run
/memory enable. Installing
the plugin without a backend simply runs without semantic memory.
- Token-gated. Auth uses a personal bearer token (
MEMORY_MCP_TOKEN); the
endpoint defaults to your own backend and is overridable via MEMORY_MCP_URL.
- Per-project isolation. The
memory-project-id SessionStart hook derives a
stable project_id from the git remote, so each repository has its own memory
namespace, shared across your devices.
- Graceful fallback. If the backend is unreachable, skills fall back to the
file-based
.scaffolding/agent-memory/ — agents never block.
Hosting the backend (LXC/VM, Docker compose, Ollama, network egress policy) is
outside the plugin; the plugin only consumes the MCP endpoint.
Updating
/plugin update scaffolding@komluk-scaffolding
/reload-plugins
Re-run /init-scaffolding in projects where you want the latest CLAUDE.md
and hooks copied in.
Documentation
Versioning
The project follows SemVer 2.0.0.
| Bump | When |
|---|
| MAJOR (X.0.0) | Breaking changes: removing an agent/skill/command, incompatible plugin.json schema changes, install path changes |
| MINOR (x.Y.0) | New agent/skill/command/hook, new feature in CI (backward compatible) |
| PATCH (x.y.Z) | Bug fix, typo, documentation tweaks |
Source of truth for the version: .claude-plugin/plugin.json (version field).
The git tag MUST match (v${version}) — enforced by release.yml in GitHub
Actions.
Version history: CHANGELOG.md.
License
MIT — see LICENSE.
