Agent Blueprint

A Claude Code framework for building, editing, and improving AI agents that run on OpenClaw. Adopt it into a new agent project (greenfield) or an existing one — same toolkit either way.

Sister framework to @insynq/app-blueprint, reframed for OpenClaw agent dev. Built and maintained by Insynq. Source: github.com/Insynq/agent-blueprint.

Philosophy

Agent projects fail differently from app projects. Skills go stale, MCP configs silently break, model routing drifts, prompts truncate at character caps no one is watching. This framework encodes the runtime assumptions of OpenClaw so a discovery-first workflow can stay grounded in what the gateway actually loads, what mcporter actually parses, and what launchd actually runs.

The greenfield sequence:

install → /preflight → /kickoff → /orchestrate (per phase) → /ship

The existing-repo sequence:

install → /preflight → /adopt → /orchestrate (per phase) → /ship

Updates ship via /update-framework — pull canonical changes with per-file review and assisted merge for any customizations you've made.

Getting Started

1. Install (existing or new agent project)

From inside the project directory you want to install into:

npx @insynq/agent-blueprint init

The installer:

• Refuses to run on a dirty git working tree (so changes are reviewable)
• Asks before overwriting any file you've already authored
• Stages all downloads in ./.framework-install-staging/ and only commits to disk after every file succeeds
• Stamps .framework-version at the repo root for /update-framework to use later
• Prints clear next steps when done

If your repo isn't a git repo, the installer offers to git init for you. Recovery from any install issue is a git diff away.

2. Open in your editor with an AI agent

Open the folder in VS Code (or your editor of choice). Any of these agents work: Claude Code, Codex, Cursor, Aider, Continue, Cline.

3. Run preflight

A one-time, sub-minute setup that records which agent + OS you're on into CLAUDE.md so future sessions don't have to re-figure it out, and confirms your project-level commands aren't being shadowed by user-global ones.

• Claude Code: type /preflight
• Other agents: paste "Read and follow the instructions in .claude/commands/preflight.md"

4. Run kickoff (greenfield) OR adopt (existing repo)

Greenfield (/kickoff): Discovery session that defines your agent's identity, capabilities, MCP integrations, model routing, and deploy story from scratch.

Existing repo (/adopt): Reads your existing agent project, drafts proposed populations for project-state KBs (architecture, current state), audits any existing user KBs against current code for stale references, and assists merging an existing CLAUDE.md if you have one. Always shows drafts before writing — never silently overwrites your content.

# greenfield
/kickoff

# existing repo
/adopt

/adopt has a --minimal flag for users who just want commands installed without the discovery flow.

Note for non-Claude-Code agents: The .md files in .claude/commands/ are instruction documents, not commands you need to install. When the user types /<name>, just read the corresponding file and follow its steps inline. Don't copy them anywhere global.

Multi-Agent Workflow (PM / Worker)

This framework is built around a PM/worker phase loop driven by /orchestrate. One PM context window holds the strategic view; workers execute focused slices in their own contexts (subagents, or separate Claude Code sessions for context-heavy work).

The loop walks 10 phases per piece of work: pivot review → brainstorm → holistic plan + audit-code → worker dispatch (granular audit round) → reconciliation → worker dispatch (implementation round) → PM verification + integration → smoke handoff → ship.

Worker plan docs are single living artifacts that PM and worker both write to — no handoff drift. See docs/MULTI_AGENT_WORKFLOW.md for the full methodology.

Command Library

Orchestrators

Command	Purpose
/preflight	One-time per clone — captures agent + OS into CLAUDE.md, verifies commands are project-local
/kickoff	Discovery session — greenfield agent projects
/adopt	Discovery session — existing agent repos. Inventories skills, drafts KBs, audits existing user KBs, merges CLAUDE.md
/update-framework	Pull canonical framework updates with per-file review and assisted merge
/orchestrate	PM phase loop — pivot → brainstorm → plan + audit → workers → reconcile → implement → smoke → ship
/audit-full	Full review (code + infrastructure) in parallel

Planning & Review

Command	Purpose
/brainstorm	Deep research + options before committing to an approach
/research	Deep web research with synthesized report saved to .research/
/investigate	Deep codebase exploration — trace data flows, find all usages
/plan	Create implementation plan from investigation findings
/plan-review	Gap analysis on a spec doc before implementing

Implementation

Command	Purpose
/implement	Execute a validated plan (parallel agents + post-batch audit)
/debug	Diagnose a bug — characterize symptom, investigate, form hypothesis, confirm before fixing
/unify	Consolidate duplicate/similar skills or scripts into one normalized form
/ship	Update KBs, commit, push (deploy fires via webhook on push)
/changelog	Generate or update CHANGELOG.md from git history

Auditing

Command	Purpose
/audit-code	Review code/plans for elegance, reuse, anti-patterns
/audit-infra	Infrastructure review — gateway config, mcporter config, plist env vars, deploy script, rsync excludes

Generators

Command	Purpose
/gen-skill	Scaffold a new SKILL.md at workspace/skills/<name>/ with correct frontmatter and 5-section skeleton
/gen-test	Generate tests following project patterns
/visualize	Generate ASCII diagrams (architecture, data flows, agent state)
/update-kb	Update knowledge base documents without committing

Updating

When canonical ships a new version, run from your project directory:

/update-framework

The command:

• Fetches canonical at install-version + target-version (immutable GitHub release tarballs, not raw URLs)
• Detects which framework files you've customized (compares local against canonical-at-install-version)
• Presents a four-category review: 🟥 files you customized (decision required), 🟢 unchanged locally (safe to apply), 🟡 new from canonical (consider), 🔵 deprecated (migration notes)
• For customized files, offers per-file: skip (keep yours), overwrite (with backup), or three-way merge via git merge-file
• Backs up to .framework-backup/[file]@[old-version] before any write
• Refuses downgrades by default; --allow-downgrade for legitimate rollback

Pass --dry-run to see the four-category report without writing anything. Pass --target-version=0.2.0 to pin to a specific version.

Security Assumptions (V1)

The npx installer and /update-framework operate under these assumptions, documented so you know what you're trusting:

• The @insynq npm scope is secure (signed packages deferred to V2)
• The canonical GitHub repo at Insynq/agent-blueprint is not compromised at install/update time
• Networks are not actively hostile (no MITM verification — but installer prints SHA256 of the downloaded tarball pre-extraction so you can verify if you choose)
• The canonical repo is public in V1 (private-repo support deferred to V2)
• Windows-without-WSL is not supported in V1 (/update-framework shells out to tar); WSL or Mac/Linux only

What Adopt Produces (Existing Agent Repos)

File	Auto-derived	User-confirmed	Left as TODO
CLAUDE.md	OpenClaw runtime block, build commands	Project overview, current phase	Roles, preferences (judgment-required)
docs/KB_1_Architecture.md	Skills inventory, MCP servers, scripts, model routing	Architecture decisions	Open questions
docs/KB_8_Current_State.md	—	—	User-authored
docs/APP_CONCEPT.md	—	—	Always user-authored (kickoff-style mini-session optional)
docs/SCOPE.md	—	—	Same

/adopt always shows drafts before writing project content. The auto-populate is just to seed the draft, not to ship final content.

Knowledge Base Conventions

File	Contains
docs/APP_CONCEPT.md	Problem, users, use cases
docs/SCOPE.md	V1 scope, out-of-scope, known unknowns
docs/KB_1_Architecture.md	Architecture decisions, runtime model, agent shape
docs/KB_8_Current_State.md	Active phase, session notes, changelog

The OpenClaw stack-reference KBs live at docs/OpenClaw KBs/ and are read-mostly: runtime model, skills, MCP tools, bootstrap files, models & prompts, cron & scripts, deploy & ops, observability, and an aspirational evals shape. Open OC_KB_00_Index.md to route into the right file for the task at hand.

Maintenance rules:

• Completed phases: collapse to 2–3 line summaries. Full history in git.
• KB_8 session notes: only for active blockers. Clear after resolution.
• Changelog: one-liner entries only.
• Always update CLAUDE.md phase status when updating KBs.

What Framework Owns vs. What You Own

The .framework-manifest.json at canonical declares this explicitly. Five categories:

• framework-managed — .claude/commands/, docs/OpenClaw KBs/, MULTI_AGENT_WORKFLOW.md, KB_INDEX.md. These get refreshed on /update-framework.
• hybrid — CLAUDE.md, KB_1, KB_8, .claude/settings.json, workspace/, deploy/, _dev/. Framework provides scaffolding; you fill content. /update-framework uses three-way merge for these.
• project-owned — APP_CONCEPT.md, SCOPE.md, CHANGELOG.md, LESSONS.md, smoke-tests-pending.md, docs/plans/, .claude/memory/MEMORY.md. Never touched by installer or updater.
• installer_generated — .framework-version. Created by installer.
• excluded — README.md, LICENSE, CONTRIBUTING.md, .gitignore, .vscode/. Framework artifacts that don't ship to adopters.

If /update-framework finds a file in canonical not in the manifest, it surfaces it for your decision rather than installing silently.

OpenClaw Runtime Assumptions

This framework is opinionated for OpenClaw. Adopters are expected to be running:

• The openclaw gateway as a long-lived service (typically launchd on macOS).
• Agent code as markdown — bootstrap files at workspace/<NAME>.md (SOUL, AGENTS, TOOLS, SCHEMA, MEMORY, HEARTBEAT, NOTIFICATIONS, TASK-QUEUE, INDEX) loaded at gateway start with a per-file character cap.
• Skills as workspace/skills/<name>/SKILL.md, loaded on demand by the router. Folder name MUST equal the frontmatter name.
• Tools exclusively via MCP registered in workspace/config/mcporter.json (top-level key mcpServers — not servers). ${ENV_VAR} substitution reads from process.env, which on macOS means the launchd plist EnvironmentVariables dict.
• Anthropic Claude as the LLM, with prompt caching configured under agents.defaults.models["<id>"].params.cacheRetention (PLURAL models, easy to misplace).
• GitOps deploy: webhook receiver → HMAC verify → git pull → rsync --delete workspace/ → ~/.openclaw/workspace/ on the runtime host.

If your stack diverges from this, this is the wrong framework. Consider @insynq/app-blueprint for general application projects.

Autonomy contract

By default, the framework allows the agent to edit files, write code, run installs/builds, and stage commits without prompting. The agent pauses for approval on:

• git commit, push, reset, rebase, checkout, merge, tag
• npm publish
• rm -rf
• OpenClaw cron mutations and openclaw message send
• any destructive or shared-state operation

Force-pushes (git push --force, git push -f), git reset --hard, rm -rf /, rm -rf ~, and sudo are denied outright.

The contract lives in .claude/settings.json (a hybrid file — your customizations are preserved on update). Override locally in .claude/settings.local.json if your workflow needs different boundaries — for instance, allowing openclaw cron list only and asking for everything else, or allowing gh and rsync for your specific deploy tooling.

Who This Is For

Anyone building OpenClaw agents who wants to work systematically with Claude Code. The framework provides the methodology, command library, and OpenClaw-specific KBs. You bring the agent identity and integrations.

Especially valuable for:

• Solo builders running one or more OpenClaw agents who want PM/worker rigor
• Teams maintaining a fleet of agents that need shared workflow vocabulary
• Existing agent projects that have grown organically and need methodology imposed gently
• Projects that span multiple phases over weeks/months and need cross-session continuity

---

Agent Blueprint is by Insynq — operations-focused software design. Found this useful? A star on the repo helps others discover it.