scaffolding

claude-scaffolding

Spec-driven multi-agent orchestration for Claude Code — pure markdown, zero backend, runs on the stock runtime. 13 agents, 39 skills, 21 commands, 20 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 — 18 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.

• /specs:run command: executes the workflows/workflow.yaml step graph end-to-end via delegated agents, implementing the complexity gate, IMPL/REVIEW issue graph, retry loops, and integration review (experimental).
• 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 (any case) / 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.

To enable any flag, choose one of two methods:

Per-project (persistent, recommended): Add an env block to your project's settings.json:

{
  "env": {
    "SCAFFOLDING_AUTOFORMAT": "1",
    "SCAFFOLDING_NOTIFY": "1"
  }
}

Per-session (temporary): Export from your shell before starting Claude Code:

export SCAFFOLDING_AUTOFORMAT=1
export SCAFFOLDING_NOTIFY=1
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Available flags:

📹 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.

Agent memory

Agents share a file-based, 3-tier memory protocol — all plain markdown under .scaffolding/ of the project. Agents read the files on demand at task start (shared tier, their own agent tier, and the conversation tier when a conversation_id is provided); nothing injects them automatically. Each file is capped at 200 lines. Read-only agents (reviewer, gitops) 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).

Requirements

• git
• node >= 22 (the hooks use it for JSON handling; without it they fail open and print a notice)
• Claude Code CLI (https://claude.ai/code)

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/         39 skills (api-design, error-handling, necessity-first, pattern-recognition,
│                    skill-authoring, spec-*, mui-styling, python-patterns,
│                    sofa-search, testing-strategy, ...)
├── commands/       21 slash commands: 10 top-level (context, create-skill,
│                    init-openspec, init-rules, init-scaffolding, learn, memory,
│                    doctor, sofa, worktree-gc) + 11 in `commands/specs/` (apply, archive,
│                    bulk-archive, continue, explore, ff, new, onboard, run, sync,
│                    verify) — namespaced OpenSpec commands
├── hooks/          17 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-frontmatter, validate-agent-output, validate-skill)
├── output-styles/  output-frontmatter definition
├── workflows/      `workflow.yaml` — declarative step graph executed by `/specs:run`
├── 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-mcp can persist embeddings to a vector store. 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 skill 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