feat: initial agent-builder plugin (v0.1.0)
Build complete autonomous agent systems with Claude Code. 7-phase guided workflow: map work, CLAUDE.md, agent team, pipeline, security, deployment, test. Components: - commands/build.md: main guided workflow - agents/builder.md: scaffolding agent - skills/agent-system-design: architecture knowledge + 4 references - scripts/templates: hooks, automation, launchd, systemd Covers 22 OpenClaw capabilities across 4 deployment targets (local, Mac Mini, VPS, Managed Agents). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen
commit
075383990f
17 changed files with 1895 additions and 0 deletions
20
.claude-plugin/plugin.json
Normal file
20
.claude-plugin/plugin.json
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
{
|
||||
"name": "agent-builder",
|
||||
"description": "Build complete autonomous agent systems with Claude Code. Guided workflow that interviews you about your needs, scaffolds agents, skills, hooks, and automation, then configures deployment for your chosen platform. Covers all 22 OpenClaw capabilities.",
|
||||
"version": "0.1.0",
|
||||
"author": {
|
||||
"name": "Kjell Tore Guttormsen",
|
||||
"url": "https://fromaitochitta.com"
|
||||
},
|
||||
"repository": "https://git.fromaitochitta.com/open/agent-builder",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"agent",
|
||||
"autonomous",
|
||||
"pipeline",
|
||||
"automation",
|
||||
"hooks",
|
||||
"security",
|
||||
"deployment"
|
||||
]
|
||||
}
|
||||
7
.gitignore
vendored
Normal file
7
.gitignore
vendored
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
node_modules/
|
||||
.env
|
||||
.env.*
|
||||
*.log
|
||||
.DS_Store
|
||||
*.local.md
|
||||
*.local.json
|
||||
26
CLAUDE.md
Normal file
26
CLAUDE.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
# Agent Builder Plugin
|
||||
|
||||
Plugin that helps users build complete autonomous agent systems
|
||||
using Claude Code. Installed via `/install` or `--plugin-dir`.
|
||||
|
||||
## What this plugin does
|
||||
|
||||
Guides users through building their own multi-agent system:
|
||||
agents, skills, hooks, automation, and deployment config.
|
||||
The `/agent-builder:build` command runs a 7-phase guided workflow.
|
||||
|
||||
## Plugin structure
|
||||
|
||||
- `commands/` -- 4 user-invoked slash commands
|
||||
- `agents/` -- 2 plugin agents (builder, deployment-advisor)
|
||||
- `skills/` -- 2 auto-triggering knowledge skills
|
||||
- `scripts/templates/` -- file templates the builder copies
|
||||
into the user's project
|
||||
|
||||
## Rules
|
||||
|
||||
- Never write files outside the user's project directory
|
||||
- Always ask before overwriting existing files
|
||||
- Hook templates must be bash 3.2 compatible (Intel Mac)
|
||||
- Generated agents must have valid YAML frontmatter
|
||||
- Use `${CLAUDE_PLUGIN_ROOT}` for all intra-plugin paths
|
||||
21
LICENSE
Normal file
21
LICENSE
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) 2026 Kjell Tore Guttormsen
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
67
README.md
Normal file
67
README.md
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
# Agent Builder
|
||||
|
||||
Build complete autonomous agent systems with Claude Code.
|
||||
|
||||
OpenClaw gives you a pre-built agent. This plugin helps you
|
||||
build your own, tailored to your work and deployed where you
|
||||
choose.
|
||||
|
||||
## Install
|
||||
|
||||
```
|
||||
/install agent-builder
|
||||
```
|
||||
|
||||
Or for local development:
|
||||
|
||||
```
|
||||
claude --plugin-dir /path/to/agent-builder
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | What it does |
|
||||
|---------|-------------|
|
||||
| `/agent-builder:build` | Guided 7-phase workflow to build a complete agent system |
|
||||
| `/agent-builder:deploy` | Configure deployment for your chosen platform |
|
||||
| `/agent-builder:evaluate` | Assess your setup against 22 agent capabilities |
|
||||
| `/agent-builder:status` | Quick status check of your agent infrastructure |
|
||||
|
||||
## What `/agent-builder:build` creates
|
||||
|
||||
The build command walks you through 7 phases:
|
||||
|
||||
1. **Map your work** -- identify recurring tasks and agent roles
|
||||
2. **Operating manual** -- generate a CLAUDE.md tailored to your domain
|
||||
3. **Agent team** -- scaffold specialized agents in `.claude/agents/`
|
||||
4. **Pipeline** -- create skills that orchestrate your agents
|
||||
5. **Security** -- add hooks for command blocking and audit logging
|
||||
6. **Deployment** -- configure for your platform (local, Mac Mini, VPS, or Managed Agents)
|
||||
7. **Test** -- run on real work and iterate
|
||||
|
||||
Each phase produces files in your project. You can stop after any
|
||||
phase and resume later.
|
||||
|
||||
## Deployment targets
|
||||
|
||||
| Platform | Best for | Always-on |
|
||||
|----------|---------|-----------|
|
||||
| Local (cron/launchd) | Development, testing | With tmux |
|
||||
| Mac Mini (launchd + channels) | Personal agent | Yes |
|
||||
| VPS (systemd + cron) | Server agent, teams | Yes |
|
||||
| Managed Agents (Anthropic API) | Production, scaling | Yes (cloud) |
|
||||
|
||||
## What this covers
|
||||
|
||||
Maps all 22 OpenClaw capabilities to Claude Code equivalents:
|
||||
13 full matches, 8 different approaches, 1 gap (Canvas/A2UI).
|
||||
Run `/agent-builder:evaluate` to see your current coverage.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Claude Code v2.1.86 or later (for full feature coverage)
|
||||
- The `plugin-dev` plugin (recommended for agent/skill creation)
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
164
agents/builder.md
Normal file
164
agents/builder.md
Normal file
|
|
@ -0,0 +1,164 @@
|
|||
---
|
||||
name: builder
|
||||
description: |
|
||||
Use this agent when the user wants to create, scaffold, or generate agent system components. Examples:
|
||||
|
||||
<example>
|
||||
Context: User wants to create an agent file
|
||||
user: "Create a researcher agent for my project"
|
||||
assistant: "I'll use the builder agent to scaffold the agent file."
|
||||
<commentary>
|
||||
Agent creation request triggers the builder.
|
||||
</commentary>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
Context: User wants a complete pipeline
|
||||
user: "Set up a weekly report pipeline with agents"
|
||||
assistant: "I'll use the builder agent to create the agent team and pipeline skill."
|
||||
<commentary>
|
||||
Pipeline creation request triggers the builder.
|
||||
</commentary>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
Context: User wants security hooks
|
||||
user: "Add safety hooks to my agent setup"
|
||||
assistant: "I'll use the builder agent to generate hook scripts and settings."
|
||||
<commentary>
|
||||
Security setup request triggers the builder.
|
||||
</commentary>
|
||||
</example>
|
||||
model: sonnet
|
||||
color: green
|
||||
tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash", "AskUserQuestion"]
|
||||
---
|
||||
|
||||
## How you work
|
||||
|
||||
You are a builder agent specializing in scaffolding autonomous agent systems for Claude Code. Your job is to generate ready-to-use files that the user can drop directly into their project.
|
||||
|
||||
Before generating any file, read the relevant template from `${CLAUDE_PLUGIN_ROOT}/scripts/templates/` if one exists. Templates define the canonical structure — do not deviate from them without a reason.
|
||||
|
||||
**What you build:**
|
||||
|
||||
- `.claude/agents/*.md` — subagent definitions (frontmatter + system prompt)
|
||||
- `.claude/skills/*.md` or `.claude/skills/<name>/SKILL.md` — knowledge skills and pipeline skills
|
||||
- `hooks/*.sh` — pre/post tool use hook scripts
|
||||
- `.claude/settings.json` — permissions and hook configuration
|
||||
- Automation scripts (launchd plists, systemd units, shell runners)
|
||||
|
||||
**How you gather requirements:**
|
||||
|
||||
Use `AskUserQuestion` when the intent is ambiguous. Ask one focused question at a time. Typical questions:
|
||||
|
||||
- What domain is this agent working in? (content, engineering, research, ops...)
|
||||
- What tools does it need? (Read, Write, Bash, WebSearch, MCP tools...)
|
||||
- What model? (sonnet for execution, opus for reasoning-heavy tasks)
|
||||
- Does this replace a human role or augment one?
|
||||
- Are there files or directories it must never touch?
|
||||
|
||||
Once you have enough to proceed, generate the file without further ceremony.
|
||||
|
||||
## Rules
|
||||
|
||||
- Never overwrite an existing file without first reading it and asking the user to confirm
|
||||
- All hook scripts must be bash 3.2 compatible: no associative arrays (`declare -A`), no `mapfile`, no `readarray`, no `|&` operator
|
||||
- Always `chmod +x` hook scripts after creation
|
||||
- Agent frontmatter must include: `name`, `description` (with at least one `<example>`), `model`, `tools` (array)
|
||||
- Skill frontmatter must include: `name`, `description`, `version`
|
||||
- Hook scripts must read JSON input from stdin and use `python3` for JSON parsing
|
||||
- settings.json hooks use `PreToolUse` and `PostToolUse` — verify the matcher pattern is specific enough to avoid false triggers
|
||||
- When creating agents, write descriptions that trigger reliably: include concrete user phrases, not just abstract capability descriptions
|
||||
- Do not expand scope beyond what was requested. One file per request unless the user explicitly asks for a bundle
|
||||
|
||||
## Output format
|
||||
|
||||
For each file generated:
|
||||
|
||||
1. State the file path
|
||||
2. Write the file using the Write tool
|
||||
3. For hook scripts: run `chmod +x <path>` immediately after
|
||||
4. Confirm what was created and what the user should do next (e.g., "Add this hook to your settings.json under `hooks.PreToolUse`")
|
||||
|
||||
If multiple files are needed (e.g., a full agent + skill + hook bundle), list all paths upfront before writing any of them, so the user can redirect before you begin.
|
||||
|
||||
### Agent file format
|
||||
|
||||
```
|
||||
---
|
||||
name: <slug>
|
||||
description: |
|
||||
<one sentence capability summary>
|
||||
|
||||
<example>
|
||||
Context: <situation>
|
||||
user: "<typical user message>"
|
||||
assistant: "<how Claude responds>"
|
||||
<commentary>
|
||||
<why this triggers the agent>
|
||||
</commentary>
|
||||
</example>
|
||||
model: sonnet|opus
|
||||
color: <color>
|
||||
tools: ["Read", "Write", ...]
|
||||
---
|
||||
|
||||
## How you work
|
||||
<step-by-step operating procedure>
|
||||
|
||||
## Rules
|
||||
<constraints and guardrails>
|
||||
|
||||
## Output format
|
||||
<what the agent produces and how>
|
||||
```
|
||||
|
||||
### Skill file format
|
||||
|
||||
```
|
||||
---
|
||||
name: <slug>
|
||||
description: |
|
||||
<trigger phrases — what the user says to activate this skill>
|
||||
version: <semver>
|
||||
---
|
||||
|
||||
## <Topic>
|
||||
<knowledge content>
|
||||
|
||||
## Getting started
|
||||
<first action>
|
||||
```
|
||||
|
||||
### Hook script format
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# <description>
|
||||
# Reads JSON from stdin via Claude Code hook protocol
|
||||
|
||||
INPUT=$(cat)
|
||||
TOOL=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_name',''))" 2>/dev/null || echo "")
|
||||
|
||||
# logic here
|
||||
|
||||
exit 0 # allow | exit 2 # block with message
|
||||
```
|
||||
|
||||
### settings.json hook entry format
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{ "type": "command", "command": "bash hooks/<script>.sh" }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
390
commands/build.md
Normal file
390
commands/build.md
Normal file
|
|
@ -0,0 +1,390 @@
|
|||
---
|
||||
description: Build a complete autonomous agent system. Guided 7-phase workflow that interviews you, scaffolds agents, skills, hooks, and configures deployment.
|
||||
argument-hint: Optional focus area (e.g., "marketing pipeline" or "research agent")
|
||||
allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash", "Agent", "AskUserQuestion"]
|
||||
---
|
||||
|
||||
You are running `/agent-builder:build` — a guided 7-phase workflow for building a complete autonomous agent system with Claude Code.
|
||||
|
||||
If $ARGUMENTS is provided, use it as context for the system being built. Tailor every phase to that domain.
|
||||
|
||||
Work through phases sequentially. After completing each phase, tell the user what files were created or modified and offer to continue to the next phase or stop. The user can resume any time by invoking this command again.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Map Your Work
|
||||
|
||||
Goal: Understand the user's actual workflows before designing anything.
|
||||
|
||||
Ask the user the following questions using AskUserQuestion. Ask them one at a time, wait for each answer before proceeding.
|
||||
|
||||
**Question 1 — Repeating tasks:**
|
||||
"What weekly tasks do you do that follow a pattern? List 3-5 specific tasks. For each one, describe: what triggers it, what inputs it needs, what processing happens, and what the output looks like."
|
||||
|
||||
**Question 2 — Roles:**
|
||||
"If you could hire 2-3 assistants for these tasks, what roles would they fill? For each role, describe: what expertise they'd have, what they'd produce, and how you'd know they did a good job."
|
||||
|
||||
**Question 3 — Hard limits:**
|
||||
"What must NEVER happen automatically? List actions that always need your approval, things that should never be logged, and any systems or files that are off-limits."
|
||||
|
||||
After collecting all three answers, produce a design sketch in this format:
|
||||
|
||||
```
|
||||
PIPELINE DESIGN
|
||||
===============
|
||||
Trigger: [what starts the pipeline]
|
||||
Stage 1: [Role A] takes [input] → produces [output]
|
||||
Stage 2: [Role B] takes [Stage 1 output] → produces [output]
|
||||
Stage 3: [Role C] takes [Stage 2 output] → produces [final output]
|
||||
|
||||
Hard limits enforced by hooks:
|
||||
- [limit 1]
|
||||
- [limit 2]
|
||||
|
||||
Files to create in Phase 3:
|
||||
- .claude/agents/[role-a].md
|
||||
- .claude/agents/[role-b].md
|
||||
- .claude/agents/[role-c].md
|
||||
```
|
||||
|
||||
Show this sketch to the user and confirm before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Operating Manual
|
||||
|
||||
Goal: Create or improve CLAUDE.md so agents have accurate context.
|
||||
|
||||
Interview the user across 5 categories. Use AskUserQuestion. Ask one category at a time.
|
||||
|
||||
**Category 1 — Who you are:**
|
||||
"Describe yourself and your role. What's your job, your domain, and your main focus right now?"
|
||||
|
||||
**Category 2 — How you communicate:**
|
||||
"How do you prefer Claude to communicate with you? Language, tone, format, things you want Claude to never say or do?"
|
||||
|
||||
**Category 3 — What you're working on:**
|
||||
"What are your active projects right now? What's the current priority and what does 'done' look like?"
|
||||
|
||||
**Category 4 — Tools and environment:**
|
||||
"What tools, APIs, and systems do you use regularly? Any platform constraints (OS, shell version, paths)?"
|
||||
|
||||
**Category 5 — Hard rules:**
|
||||
"What should Claude never do? Any actions, files, systems, or topics that are strictly off-limits?"
|
||||
|
||||
Generate CLAUDE.md in the project root. Structure it with these sections:
|
||||
- Who I am
|
||||
- How I communicate
|
||||
- What I'm working on
|
||||
- Tools and environment
|
||||
- What you must never do
|
||||
- Memory (leave blank for now — the pipeline will populate this)
|
||||
|
||||
Validate against 5 criteria before writing:
|
||||
1. Specific enough — no vague phrases like "be helpful"
|
||||
2. Priorities are current — reflects what the user said, not generic goals
|
||||
3. Boundaries are clear — hard limits are explicit and actionable
|
||||
4. Tools are documented — includes versions or paths where relevant
|
||||
5. Format preferences stated — language, length, tone are specified
|
||||
|
||||
If any criterion fails, ask a follow-up question before writing.
|
||||
|
||||
Tell the user: "Created CLAUDE.md. Review it and edit freely — this is your operating manual, not mine."
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Agent Team
|
||||
|
||||
Goal: Create .claude/agents/*.md files for each role identified in Phase 1.
|
||||
|
||||
Read the design sketch from Phase 1. Create one agent file per role.
|
||||
|
||||
Default starting roles (adapt to the user's domain from Phase 1):
|
||||
- researcher.md — gathers information, verifies sources, produces research briefs
|
||||
- writer.md — produces first drafts from research briefs
|
||||
- reviewer.md — evaluates quality, flags issues, requests revisions
|
||||
|
||||
Read ${CLAUDE_PLUGIN_ROOT}/scripts/templates/pre-tool-use.sh for reference on the security patterns used — agents should be scoped to avoid the same dangerous patterns.
|
||||
|
||||
Each agent file must follow this structure:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: [role name]
|
||||
description: [one sentence — what this agent does and when to invoke it]
|
||||
tools: [comma-separated list of tools this agent needs]
|
||||
model: claude-sonnet-4-5
|
||||
---
|
||||
|
||||
You are [role name] for [user's domain].
|
||||
|
||||
## How you work
|
||||
|
||||
[3-5 bullet points describing the agent's process]
|
||||
|
||||
## Rules
|
||||
|
||||
- [rule 1 — specific to this role]
|
||||
- [rule 2]
|
||||
- [rule 3 — include at least one "never do" rule]
|
||||
|
||||
## Output format
|
||||
|
||||
[Describe the exact output format: headings, length, structure]
|
||||
```
|
||||
|
||||
Create the directory .claude/agents/ if it does not exist.
|
||||
|
||||
After creating each agent file, tell the user: "Created .claude/agents/[name].md — [one-line summary of what it does]."
|
||||
|
||||
After all agents are created, test each one individually:
|
||||
- Run each agent on a simple representative task from the user's domain
|
||||
- Ask the user: "Does [agent name]'s output look right? What would you change?"
|
||||
- Make adjustments before moving to Phase 4.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Pipeline
|
||||
|
||||
Goal: Create a skill that chains the agents into an end-to-end pipeline.
|
||||
|
||||
Ask the user using AskUserQuestion:
|
||||
"What should we name this pipeline? This becomes the slash command: /[name]"
|
||||
|
||||
Create .claude/skills/[pipeline-name].md with a 9-step structure:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: [One sentence describing what this pipeline produces]
|
||||
argument-hint: [What to pass as input, e.g., "topic or URL"]
|
||||
allowed-tools: ["Read", "Write", "Edit", "Bash", "Agent"]
|
||||
---
|
||||
|
||||
Run this pipeline end-to-end. $ARGUMENTS is the input.
|
||||
|
||||
**Step 1 — Load context**
|
||||
Read CLAUDE.md. Read memory state if it exists (look for a Memory section in CLAUDE.md or a separate memory file). Summarize current priorities in one sentence before proceeding.
|
||||
|
||||
**Step 2 — Research**
|
||||
Use the researcher agent: pass $ARGUMENTS and the current context. The agent produces a research brief. Save it to pipeline-output/research-[date].md.
|
||||
|
||||
**Step 3 — Draft**
|
||||
Use the writer agent: pass the research brief. The agent produces a first draft. Save it to pipeline-output/draft-[date].md.
|
||||
|
||||
**Step 4 — Review**
|
||||
Use the reviewer agent: pass the draft. The agent produces a scored evaluation with specific revision requests. Save it to pipeline-output/review-[date].md.
|
||||
|
||||
**Step 5 — Revision loop**
|
||||
If the reviewer flagged issues:
|
||||
- Pass the draft and review back to the writer agent with instruction to revise
|
||||
- Re-run the reviewer
|
||||
- Repeat up to 2 times
|
||||
- If still below threshold after 2 revisions, stop and report to the user
|
||||
|
||||
**Step 6 — Save output**
|
||||
Write the final draft to pipeline-output/final-[date].md.
|
||||
|
||||
**Step 7 — Update memory**
|
||||
Update the Memory section in CLAUDE.md with:
|
||||
- Date of last run
|
||||
- Topic processed
|
||||
- Quality score from reviewer
|
||||
- Any recurring issues to watch for
|
||||
|
||||
**Step 8 — Confirm**
|
||||
Report to the user:
|
||||
- What was produced (file path)
|
||||
- Reviewer score
|
||||
- Time taken (approximate)
|
||||
- Any issues encountered
|
||||
|
||||
**Evaluation rubric:**
|
||||
- Level 4 (send as-is): Meets all quality criteria, no changes needed
|
||||
- Level 3 (minor edits): Good structure and content, needs 10 minutes of editing
|
||||
- Level 2 (rework): Structure is right, content needs significant work
|
||||
- Level 1 (not usable): Does not meet minimum quality threshold — escalate to user
|
||||
```
|
||||
|
||||
Tell the user: "Created .claude/skills/[pipeline-name].md. Run it with /[pipeline-name] [your topic]."
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Security
|
||||
|
||||
Goal: Add hooks that enforce the hard limits from Phase 1.
|
||||
|
||||
Read the user's "hard limits" from Phase 1.
|
||||
|
||||
Read the template at ${CLAUDE_PLUGIN_ROOT}/scripts/templates/pre-tool-use.sh.
|
||||
Read the template at ${CLAUDE_PLUGIN_ROOT}/scripts/templates/post-tool-use.sh.
|
||||
|
||||
Create the .claude/hooks/ directory if it does not exist.
|
||||
|
||||
**Pre-tool-use hook:**
|
||||
Copy pre-tool-use.sh from the template into .claude/hooks/pre-tool-use.sh.
|
||||
Customize the blocked_patterns array to include:
|
||||
- All patterns from the template (keep the safe defaults)
|
||||
- One pattern per hard limit the user specified in Phase 1
|
||||
- Any file paths or systems the user marked as off-limits (e.g., blocking rm on those paths)
|
||||
|
||||
**Post-tool-use hook:**
|
||||
Copy post-tool-use.sh from the template into .claude/hooks/post-tool-use.sh.
|
||||
Keep the default audit logging behavior.
|
||||
Change the log_file path to .claude/hooks/audit.log.
|
||||
|
||||
**Settings file:**
|
||||
Create .claude/settings.json:
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(git *)",
|
||||
"Bash(npm *)",
|
||||
"Read(*)",
|
||||
"Write(.claude/*)",
|
||||
"Write(pipeline-output/*)"
|
||||
],
|
||||
"deny": [
|
||||
"Bash(rm -rf *)"
|
||||
]
|
||||
},
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "*",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "bash .claude/hooks/pre-tool-use.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "*",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "bash .claude/hooks/post-tool-use.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Customize permissions.deny to match the user's hard limits from Phase 1.
|
||||
|
||||
Ask the user using AskUserQuestion before writing settings.json:
|
||||
"I'm about to create .claude/settings.json with these permissions. Does this match what you want? [show the deny list]"
|
||||
|
||||
Tell the user: "Created hooks and settings.json. The audit log will be written to .claude/hooks/audit.log after each tool call."
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Deployment
|
||||
|
||||
Goal: Configure automated scheduling for the pipeline.
|
||||
|
||||
Ask the user using AskUserQuestion:
|
||||
"Where will this pipeline run? Choose one:
|
||||
1. Local — your own machine, cron schedule
|
||||
2. Mac Mini — dedicated Mac, launchd + tmux
|
||||
3. VPS — Linux server, systemd
|
||||
4. Managed Agents — Anthropic API (no local scheduling needed)"
|
||||
|
||||
Create the automation/ directory if it does not exist.
|
||||
|
||||
**Option 1 — Local (cron):**
|
||||
Read ${CLAUDE_PLUGIN_ROOT}/scripts/templates/automation.sh.
|
||||
Copy it to automation/run-pipeline.sh.
|
||||
Replace SKILL_NAME with the pipeline name from Phase 4.
|
||||
Replace OUTPUT_DIR with pipeline-output.
|
||||
Ask the user: "What time should this run, and how often? (e.g., daily at 07:00)"
|
||||
Generate a cron entry and show it to the user with instructions:
|
||||
```
|
||||
# Add to crontab with: crontab -e
|
||||
0 7 * * * /bin/bash /path/to/your-project/automation/run-pipeline.sh >> /tmp/claude-pipeline.log 2>&1
|
||||
```
|
||||
|
||||
**Option 2 — Mac Mini (launchd):**
|
||||
Read ${CLAUDE_PLUGIN_ROOT}/scripts/templates/launchd.plist.
|
||||
Copy it to automation/com.yourdomain.claude-pipeline.plist.
|
||||
Ask the user: "What time should this run? (e.g., 07:00)" and "What is your reverse-DNS label? (e.g., com.yourname)"
|
||||
Customize Label, ProgramArguments, and log paths.
|
||||
Copy automation.sh template to automation/run-pipeline.sh and customize it.
|
||||
Provide setup instructions:
|
||||
```
|
||||
cp automation/com.yourdomain.claude-pipeline.plist ~/Library/LaunchAgents/
|
||||
launchctl load ~/Library/LaunchAgents/com.yourdomain.claude-pipeline.plist
|
||||
launchctl list | grep claude
|
||||
```
|
||||
|
||||
**Option 3 — VPS (systemd):**
|
||||
Read ${CLAUDE_PLUGIN_ROOT}/scripts/templates/systemd-service.unit.
|
||||
Copy it to automation/claude-pipeline.service.
|
||||
Ask the user: "What Linux user runs the agent?" and "What is the absolute path to your project?"
|
||||
Customize User, WorkingDirectory, ExecStart, and EnvironmentFile.
|
||||
Copy automation.sh template to automation/run-pipeline.sh and customize it.
|
||||
Provide setup instructions including the timer unit from the template comments.
|
||||
|
||||
**Option 4 — Managed Agents:**
|
||||
Use the deployment-advisor agent to generate API code.
|
||||
Pass the pipeline name, agent list, and any relevant context from previous phases.
|
||||
Save generated code to automation/managed-agents-client.ts (TypeScript) or automation/managed-agents-client.py (Python) based on user preference.
|
||||
|
||||
Tell the user what files were created and provide the exact commands needed to activate the schedule.
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: Test and Iterate
|
||||
|
||||
Goal: Run the pipeline on real work and calibrate based on results.
|
||||
|
||||
Ask the user using AskUserQuestion:
|
||||
"Give me a real task from your actual week — something you'd normally spend time on — so we can test the pipeline end-to-end."
|
||||
|
||||
Run the pipeline skill on that task. Use the evaluation rubric from Phase 4:
|
||||
- Level 4 (send as-is): No changes needed. Tell the user: "Pipeline is working well."
|
||||
- Level 3 (needs 10 min editing): Identify the specific gaps. Ask: "Want me to adjust the writer or reviewer agent to close these gaps?"
|
||||
- Level 2 (structure right, content off): Diagnose which stage broke down. Suggest targeted changes to that agent's prompt.
|
||||
- Level 1 (not usable): Stop. Ask the user to describe what a good output would look like. Revise the agents based on that description, then re-run.
|
||||
|
||||
After the test, provide a day-by-day plan for the first week:
|
||||
|
||||
```
|
||||
Day 1: Run the pipeline manually on 2-3 tasks. Note what needs editing.
|
||||
Day 2: Review audit.log. Identify the most common edit you made.
|
||||
Day 3: Update the agent prompt that caused that edit. Re-run one task.
|
||||
Day 4: Let the automation schedule run. Check the output.
|
||||
Day 5: Review the week. What worked? What still needs manual work?
|
||||
```
|
||||
|
||||
Ask the user using AskUserQuestion:
|
||||
"Based on the test run, what one thing would make this pipeline most useful to you right now?"
|
||||
|
||||
Implement that one change before closing the session.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
After all phases are complete (or the user stops early), print a summary:
|
||||
|
||||
```
|
||||
AGENT SYSTEM BUILT
|
||||
==================
|
||||
Agents: .claude/agents/[list]
|
||||
Pipeline: .claude/skills/[name].md
|
||||
Hooks: .claude/hooks/pre-tool-use.sh, post-tool-use.sh
|
||||
Settings: .claude/settings.json
|
||||
Schedule: automation/[script or config]
|
||||
|
||||
Run your pipeline: /[pipeline-name] [your topic]
|
||||
Review logs: .claude/hooks/audit.log
|
||||
```
|
||||
|
||||
If the user stopped early, tell them which phase to continue from and remind them that this command can be re-invoked at any time.
|
||||
22
scripts/templates/automation.sh
Executable file
22
scripts/templates/automation.sh
Executable file
|
|
@ -0,0 +1,22 @@
|
|||
#!/bin/bash
|
||||
# Headless Claude Code automation wrapper.
|
||||
#
|
||||
# Schedule this script with cron, launchd, or systemd to run
|
||||
# a skill or prompt on a recurring schedule.
|
||||
#
|
||||
# Customize:
|
||||
# - SKILL_NAME: the skill to run (e.g., /weekly-report)
|
||||
# - OUTPUT_DIR: where to save output files
|
||||
# - MAX_TURNS: safety ceiling on autonomous turns
|
||||
|
||||
SKILL_NAME="/YOUR-SKILL-NAME"
|
||||
OUTPUT_DIR="pipeline-output"
|
||||
MAX_TURNS=15
|
||||
|
||||
cd "$(dirname "$0")/.."
|
||||
|
||||
mkdir -p "$OUTPUT_DIR"
|
||||
|
||||
claude -p "Run $SKILL_NAME and save output to $OUTPUT_DIR/$(date +%Y-%m-%d).md" \
|
||||
--output-format text \
|
||||
--max-turns "$MAX_TURNS"
|
||||
48
scripts/templates/launchd.plist
Normal file
48
scripts/templates/launchd.plist
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
|
||||
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<!-- CUSTOMIZE: Change to your reverse-DNS label -->
|
||||
<key>Label</key>
|
||||
<string>com.example.claude-agent</string>
|
||||
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/bin/bash</string>
|
||||
<!-- CUSTOMIZE: Absolute path to your automation script -->
|
||||
<string>/path/to/your-project/automation/run-pipeline.sh</string>
|
||||
</array>
|
||||
|
||||
<!-- Run daily at 07:00. Adjust Hour/Minute as needed. -->
|
||||
<key>StartCalendarInterval</key>
|
||||
<dict>
|
||||
<key>Hour</key>
|
||||
<integer>7</integer>
|
||||
<key>Minute</key>
|
||||
<integer>0</integer>
|
||||
</dict>
|
||||
|
||||
<!-- CUSTOMIZE: Log paths -->
|
||||
<key>StandardOutPath</key>
|
||||
<string>/tmp/claude-agent.log</string>
|
||||
<key>StandardErrorPath</key>
|
||||
<string>/tmp/claude-agent.err</string>
|
||||
|
||||
<key>RunAtLoad</key>
|
||||
<false/>
|
||||
</dict>
|
||||
</plist>
|
||||
|
||||
<!--
|
||||
SETUP:
|
||||
1. Copy to ~/Library/LaunchAgents/com.example.claude-agent.plist
|
||||
2. Customize Label, ProgramArguments path, and log paths
|
||||
3. Load: launchctl load ~/Library/LaunchAgents/com.example.claude-agent.plist
|
||||
4. Verify: launchctl list | grep claude
|
||||
|
||||
UNLOAD:
|
||||
launchctl unload ~/Library/LaunchAgents/com.example.claude-agent.plist
|
||||
|
||||
NOTE: The claude binary must be in PATH or use its full path.
|
||||
-->
|
||||
19
scripts/templates/post-tool-use.sh
Executable file
19
scripts/templates/post-tool-use.sh
Executable file
|
|
@ -0,0 +1,19 @@
|
|||
#!/bin/bash
|
||||
# PostToolUse hook: Log all tool executions to an audit trail.
|
||||
#
|
||||
# Appends a timestamped entry to hooks/audit.log for every tool call.
|
||||
# Useful for reviewing what Claude Code did during a session.
|
||||
#
|
||||
# Customize: Change log_file path or add filtering logic.
|
||||
|
||||
input=$(cat)
|
||||
tool_name=$(echo "$input" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null)
|
||||
tool_input=$(echo "$input" | python3 -c "import sys,json; d=json.load(sys.stdin).get('tool_input',{}); print(d.get('command', d.get('file_path', d.get('pattern', str(d)[:100])))" 2>/dev/null)
|
||||
|
||||
timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
|
||||
log_dir="$(dirname "$0")"
|
||||
log_file="$log_dir/audit.log"
|
||||
|
||||
echo "$timestamp | $tool_name | $tool_input" >> "$log_file"
|
||||
|
||||
exit 0
|
||||
50
scripts/templates/pre-tool-use.sh
Executable file
50
scripts/templates/pre-tool-use.sh
Executable file
|
|
@ -0,0 +1,50 @@
|
|||
#!/bin/bash
|
||||
# PreToolUse hook: Block dangerous shell commands before execution.
|
||||
#
|
||||
# How it works:
|
||||
# - Claude Code calls this script BEFORE executing any Bash command
|
||||
# - If the script exits with code 2, the command is BLOCKED
|
||||
# - Exit 0 allows the command to proceed
|
||||
#
|
||||
# Customize: Add or remove patterns in the blocked_patterns array.
|
||||
# All patterns are matched case-insensitively against the full command.
|
||||
|
||||
input=$(cat)
|
||||
tool_name=$(echo "$input" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null)
|
||||
command=$(echo "$input" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null)
|
||||
|
||||
# Only check Bash commands
|
||||
if [ "$tool_name" != "Bash" ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Blocked patterns -- customize this list for your use case
|
||||
blocked_patterns=(
|
||||
"rm -rf /"
|
||||
"rm -rf ~"
|
||||
"rm -rf \$HOME"
|
||||
"mkfs"
|
||||
"dd if="
|
||||
":(){:|:&};:"
|
||||
"chmod -R 777 /"
|
||||
"curl.*|.*bash"
|
||||
"wget.*|.*bash"
|
||||
"curl.*|.*sh"
|
||||
"wget.*|.*sh"
|
||||
"> /dev/sda"
|
||||
"sudo rm"
|
||||
"shutdown"
|
||||
"reboot"
|
||||
"init 0"
|
||||
"init 6"
|
||||
)
|
||||
|
||||
for pattern in "${blocked_patterns[@]}"; do
|
||||
if echo "$command" | grep -qi "$pattern"; then
|
||||
echo '{"decision": "block", "reason": "Blocked by security hook: command matches dangerous pattern '"'$pattern'"'"}'
|
||||
exit 2
|
||||
fi
|
||||
done
|
||||
|
||||
# Allow everything else
|
||||
exit 0
|
||||
40
scripts/templates/systemd-service.unit
Normal file
40
scripts/templates/systemd-service.unit
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
[Unit]
|
||||
Description=Claude Code Agent Pipeline
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
# CUSTOMIZE: User that runs the agent
|
||||
User=deploy
|
||||
# CUSTOMIZE: Working directory (your project root)
|
||||
WorkingDirectory=/home/deploy/my-agent-project
|
||||
# CUSTOMIZE: Path to your automation script
|
||||
ExecStart=/bin/bash /home/deploy/my-agent-project/automation/run-pipeline.sh
|
||||
# Environment variables (API keys etc.)
|
||||
EnvironmentFile=/home/deploy/.env
|
||||
# Timeout for the pipeline run
|
||||
TimeoutStartSec=600
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
|
||||
# SETUP:
|
||||
# 1. Copy to /etc/systemd/system/claude-agent.service
|
||||
# 2. Customize User, WorkingDirectory, ExecStart, EnvironmentFile
|
||||
# 3. Enable: sudo systemctl enable claude-agent
|
||||
#
|
||||
# For recurring runs, create a timer:
|
||||
# /etc/systemd/system/claude-agent.timer
|
||||
#
|
||||
# [Unit]
|
||||
# Description=Run Claude agent pipeline daily
|
||||
#
|
||||
# [Timer]
|
||||
# OnCalendar=*-*-* 07:00:00
|
||||
# Persistent=true
|
||||
#
|
||||
# [Install]
|
||||
# WantedBy=timers.target
|
||||
#
|
||||
# Then: sudo systemctl enable --now claude-agent.timer
|
||||
115
skills/agent-system-design/SKILL.md
Normal file
115
skills/agent-system-design/SKILL.md
Normal file
|
|
@ -0,0 +1,115 @@
|
|||
---
|
||||
name: agent-system-design
|
||||
description: |
|
||||
This skill should be used when the user asks about "building an agent",
|
||||
"autonomous agent system", "agent architecture", "OpenClaw alternative",
|
||||
"always-on agent", "personal AI agent", "complete agent system",
|
||||
"agent that runs itself", "agent pipeline design", "multi-agent system",
|
||||
"how to build an agent with Claude Code"
|
||||
version: 0.1.0
|
||||
---
|
||||
|
||||
## What is an autonomous agent system
|
||||
|
||||
An autonomous agent system is a set of Claude Code components that work together to execute multi-step workflows with minimal human intervention. The system runs on a schedule, responds to triggers, processes inputs, and produces outputs — all orchestrated through Claude Code's native primitives.
|
||||
|
||||
You do not need a separate orchestration framework. Claude Code provides everything required: subagents, skills, hooks, and automation scripts.
|
||||
|
||||
## Core architecture pattern
|
||||
|
||||
The foundational pattern is a three-agent pipeline with a skill that chains them:
|
||||
|
||||
```
|
||||
Trigger (launchd/cron/manual)
|
||||
→ Pipeline skill
|
||||
→ Agent 1: Researcher (gather and structure inputs)
|
||||
→ Agent 2: Writer (produce primary output)
|
||||
→ Agent 3: Reviewer (evaluate and approve or revise)
|
||||
→ Save outputs
|
||||
→ Update memory
|
||||
```
|
||||
|
||||
The pipeline skill is a `.claude/skills/<name>/SKILL.md` file with step-by-step instructions. Each step invokes an agent using the `Agent` tool. Agents are defined in `.claude/agents/*.md`.
|
||||
|
||||
This pattern scales from simple (one agent, one step) to complex (six agents, branching logic, parallel execution).
|
||||
|
||||
## System components
|
||||
|
||||
A complete agent system has seven components:
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| CLAUDE.md | project root | Context, rules, and memory pointers for the project |
|
||||
| Agents | `.claude/agents/*.md` | Specialized subagents with defined roles and tool access |
|
||||
| Pipeline skills | `.claude/skills/*/SKILL.md` | Orchestration sequences that chain agents |
|
||||
| Knowledge skills | `.claude/skills/*/SKILL.md` | Reference knowledge auto-injected by topic |
|
||||
| Hooks | `hooks/*.sh` | Pre/post tool use guards for automated safety |
|
||||
| Settings | `.claude/settings.json` | Permissions, tool allowlists, and hook wiring |
|
||||
| Automation | `scripts/` + `launchd/` | Scheduled execution (Mac: launchd, Linux: systemd/cron) |
|
||||
| Memory | `memory/` or `data/` | Persistent state files updated each run |
|
||||
|
||||
Not all components are required for every system. Start with agents + one pipeline skill. Add hooks and automation when you move to scheduled/unattended operation.
|
||||
|
||||
## Design principles
|
||||
|
||||
**Start with 2-3 agents.** A researcher and a writer cover most content workflows. A reviewer adds quality gates. Resist the urge to create more agents than you need — each agent adds latency and cost.
|
||||
|
||||
**Pipeline skills chain agents.** The skill file is the orchestrator. It contains the sequencing logic, error handling instructions, and output routing. Keep agents dumb and focused; put the workflow intelligence in the skill.
|
||||
|
||||
**Hooks protect automated runs.** When Claude runs unattended, hooks are your circuit breakers. Use `PreToolUse` hooks to block writes to sensitive paths, enforce naming conventions, or validate inputs before destructive operations. Without hooks, an unattended run has no guardrails.
|
||||
|
||||
**Memory persists state between runs.** Agents cannot remember previous sessions by default. A memory file (e.g., `memory/MEMORY.md` or `data/run-state.json`) gives the system continuity. Update it at the end of every pipeline run.
|
||||
|
||||
**One concern per agent.** Agents that do too many things are hard to tune and debug. A researcher should research. A writer should write. Mixing concerns makes prompt engineering harder and output quality lower.
|
||||
|
||||
## Deployment options
|
||||
|
||||
| Platform | Best for | Notes |
|
||||
|----------|----------|-------|
|
||||
| Local workstation | Development, on-demand runs | Use launchd (Mac) or cron (Linux) for scheduling |
|
||||
| Mac Mini (always-on) | Personal production pipelines | Runs overnight; launchd + wake schedule |
|
||||
| VPS (Hetzner, DO) | Server-side automation, webhooks | systemd service; pair with SSH access |
|
||||
| Managed Agents | High-volume, API-driven workflows | Claude API `/v1/agents` endpoint; no local shell needed |
|
||||
|
||||
For most personal or small-team use cases, a Mac Mini or VPS running launchd/systemd is sufficient and much cheaper than Managed Agents at scale.
|
||||
|
||||
## OpenClaw capability coverage
|
||||
|
||||
This architecture covers 22 OpenClaw capabilities. 13 are a full match via native Claude Code primitives. 8 use a different approach but achieve the same outcome. 1 gap remains.
|
||||
|
||||
For the detailed mapping, see:
|
||||
`${CLAUDE_PLUGIN_ROOT}/skills/agent-system-design/references/feature-map.md`
|
||||
|
||||
## Agent frontmatter fields
|
||||
|
||||
```yaml
|
||||
name: <slug> # required, used for routing
|
||||
description: | # required, must include <example> blocks
|
||||
...
|
||||
model: sonnet|opus # required
|
||||
tools: [...] # required, explicit allowlist
|
||||
color: <color> # optional, UI hint
|
||||
```
|
||||
|
||||
The `description` field is what triggers agent selection. Write it with concrete user phrases, not abstract capability descriptions.
|
||||
|
||||
## Common mistakes
|
||||
|
||||
- **No examples in agent description** — Claude cannot reliably select the agent without seeing what user messages should trigger it
|
||||
- **Hooks skipped in automation** — unattended runs need guards; add hooks before scheduling
|
||||
- **Memory not updated** — next run starts blind; always write state at the end of a pipeline
|
||||
- **One giant agent** — harder to tune, harder to debug; split by role
|
||||
- **Wrong model for the job** — opus for synthesis and narrative, sonnet for retrieval and transformation
|
||||
|
||||
## Getting started
|
||||
|
||||
Run `/agent-builder:build` for the guided 7-phase workflow. It interviews you about your use case, selects the right pattern, and generates all files.
|
||||
|
||||
For pipeline design patterns and agent role templates, see:
|
||||
`${CLAUDE_PLUGIN_ROOT}/skills/agent-system-design/references/pipeline-patterns.md`
|
||||
|
||||
For scheduling and deployment configuration, see:
|
||||
`${CLAUDE_PLUGIN_ROOT}/skills/agent-system-design/references/deployment-config.md`
|
||||
|
||||
For the OpenClaw feature map, see:
|
||||
`${CLAUDE_PLUGIN_ROOT}/skills/agent-system-design/references/feature-map.md`
|
||||
189
skills/agent-system-design/references/deployment-targets.md
Normal file
189
skills/agent-system-design/references/deployment-targets.md
Normal file
|
|
@ -0,0 +1,189 @@
|
|||
# Deployment Targets
|
||||
|
||||
Reference for the agent-system-design skill. Covers the four deployment platforms
|
||||
available for Claude Code agents. Use this to guide target selection and scaffold
|
||||
the correct infrastructure files.
|
||||
|
||||
---
|
||||
|
||||
## 1. Local (cron/launchd)
|
||||
|
||||
**How it works:** Claude Code CLI invoked by the host scheduler. No persistent process;
|
||||
each run starts a fresh Claude Code session and exits.
|
||||
|
||||
**Setup files to scaffold:**
|
||||
- `automation.sh` -- wrapper script that sets env vars and invokes `claude`
|
||||
- Cron entry comment block in README, or `launchd.plist` for macOS
|
||||
|
||||
**Cron pattern:**
|
||||
```
|
||||
0 5 * * * /path/to/project/automation.sh >> /var/log/agent.log 2>&1
|
||||
```
|
||||
|
||||
**launchd pattern (macOS):**
|
||||
```xml
|
||||
<key>StartCalendarInterval</key>
|
||||
<dict>
|
||||
<key>Hour</key><integer>5</integer>
|
||||
<key>Minute</key><integer>0</integer>
|
||||
</dict>
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- Simple setup, no infrastructure cost
|
||||
- Full tool access (filesystem, shell, MCP)
|
||||
- Easy to test locally before any deployment
|
||||
|
||||
**Cons:**
|
||||
- Not always-on between scheduled runs
|
||||
- No mobile access without a channel plugin
|
||||
- Log rotation must be managed manually
|
||||
|
||||
**Best for:** Development, testing, personal daily pipelines (nightly batch, ecosystem pulse).
|
||||
|
||||
---
|
||||
|
||||
## 2. Mac Mini (launchd + channels)
|
||||
|
||||
**How it works:** A dedicated Mac runs Claude Code inside a persistent `tmux` session.
|
||||
`launchd` ensures the session restarts on reboot. Channel plugins (iMessage, Telegram)
|
||||
provide mobile access.
|
||||
|
||||
**Setup files to scaffold:**
|
||||
- `launchd.plist` -- keeps the tmux session alive across reboots
|
||||
- `tmux-start.sh` -- creates/attaches the named session
|
||||
- `.mcp.json` -- channel MCP server (Telegram or iMessage)
|
||||
- `channels-guide.md` -- instructions for mobile interaction
|
||||
|
||||
**tmux session pattern:**
|
||||
```bash
|
||||
tmux new-session -d -s agent -x 220 -y 50
|
||||
tmux send-keys -t agent "claude --model claude-sonnet-4-6" Enter
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- Always-on between scheduled runs
|
||||
- Native iMessage support (macOS-only feature)
|
||||
- Full GUI access for Computer Use (Desktop app)
|
||||
- Local hardware, no cloud dependency
|
||||
|
||||
**Cons:**
|
||||
- Requires dedicated physical hardware
|
||||
- iMessage and Computer Use are macOS-only
|
||||
- Single machine; no horizontal scaling
|
||||
|
||||
**Best for:** Personal always-on agent with phone access, Computer Use workflows,
|
||||
home automation pipelines.
|
||||
|
||||
---
|
||||
|
||||
## 3. VPS (systemd + cron)
|
||||
|
||||
**How it works:** Linux server runs Claude Code headless. `systemd` manages the service
|
||||
lifecycle. Cron handles scheduled tasks. Telegram or Slack provides the channel layer.
|
||||
|
||||
**Setup files to scaffold:**
|
||||
- `systemd/agent.service` -- service unit for the agent process
|
||||
- `systemd/agent.timer` -- timer unit for scheduled runs (alternative to cron)
|
||||
- `automation.sh` -- invocation wrapper
|
||||
- `.mcp.json` -- Telegram or Slack MCP server
|
||||
- `channels-guide.md` -- instructions for team interaction
|
||||
|
||||
**systemd service pattern:**
|
||||
```ini
|
||||
[Service]
|
||||
ExecStart=/path/to/automation.sh
|
||||
Restart=on-failure
|
||||
User=agent
|
||||
Environment=HOME=/home/agent
|
||||
```
|
||||
|
||||
**systemd timer pattern:**
|
||||
```ini
|
||||
[Timer]
|
||||
OnCalendar=*-*-* 05:00:00
|
||||
Persistent=true
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- True always-on with automatic restart on failure
|
||||
- Scalable: multiple agents on one server or across servers
|
||||
- Team access via shared Telegram/Slack channel
|
||||
- No hardware to manage locally
|
||||
|
||||
**Cons:**
|
||||
- No iMessage (Linux)
|
||||
- No Computer Use (no display server in headless mode)
|
||||
- Requires server management (security patches, disk, logs)
|
||||
|
||||
**Best for:** Server-side agents, team pipelines, production workloads, nightly batch
|
||||
that must run reliably even when the developer's laptop is off.
|
||||
|
||||
---
|
||||
|
||||
## 4. Managed Agents (Anthropic API)
|
||||
|
||||
**How it works:** Anthropic hosts the agent runtime. The builder deploys via the
|
||||
`/v1/agents` and `/v1/sessions` REST API, or uses `@anthropic-ai/sdk` in TypeScript/Python.
|
||||
No local Claude Code installation required.
|
||||
|
||||
**Setup files to scaffold:**
|
||||
- `agent.ts` or `agent.py` -- SDK code defining the agent
|
||||
- `sessions.ts` -- session management helpers
|
||||
- `.env.template` -- API key template
|
||||
- `README.md` -- deployment and configuration instructions
|
||||
|
||||
**TypeScript pattern:**
|
||||
```typescript
|
||||
import Anthropic from "@anthropic-ai/sdk";
|
||||
const client = new Anthropic();
|
||||
const session = await client.sessions.create({ agent_id: "ag_..." });
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- Cloud-native, zero infrastructure to manage
|
||||
- Scales automatically across sessions
|
||||
- Persistent sessions via the API
|
||||
- Integrates directly into SaaS products or APIs
|
||||
|
||||
**Cons:**
|
||||
- Different architecture from Claude Code CLI (no local filesystem by default)
|
||||
- API costs per token, no flat rate
|
||||
- Less direct filesystem access than CLI agents
|
||||
- Feature set tied to what the Managed Agents API exposes
|
||||
|
||||
**Best for:** Production deployment at scale, SaaS product integration, agents that
|
||||
must be accessible to end users without CLI access.
|
||||
|
||||
---
|
||||
|
||||
## Comparison Matrix
|
||||
|
||||
| Dimension | Local (cron) | Mac Mini | VPS | Managed API |
|
||||
|-----------|-------------|----------|-----|-------------|
|
||||
| Always-on | No | Yes | Yes | Yes |
|
||||
| Computer Use | No | Yes (Desktop) | No | No |
|
||||
| iMessage | No | Yes | No | No |
|
||||
| Telegram/Slack | Via MCP | Via MCP | Via MCP | Via integration |
|
||||
| Infrastructure cost | Zero | Hardware | VPS fee | API token cost |
|
||||
| Setup complexity | Low | Medium | Medium | Low (SDK) |
|
||||
| Team access | No | Limited | Yes | Yes |
|
||||
| Filesystem access | Full | Full | Full | Limited |
|
||||
| Horizontal scaling | No | No | Manual | Automatic |
|
||||
| Best environment | Dev/test | Personal | Team/prod | SaaS/prod |
|
||||
|
||||
## Scaffold Decision Guide
|
||||
|
||||
1. **Is this a personal agent for one developer?** Start with Local. Upgrade to Mac Mini
|
||||
if always-on or iMessage is required.
|
||||
|
||||
2. **Does the agent need Computer Use?** Mac Mini with Claude Code Desktop is the only
|
||||
option today. Document this constraint if the user is on Linux or Windows.
|
||||
|
||||
3. **Is this a team or production workload?** VPS with systemd. Add Telegram/Slack channel.
|
||||
|
||||
4. **Is this going into a product or SaaS?** Managed API. Scaffold TypeScript SDK code,
|
||||
not a CLAUDE.md agent.
|
||||
|
||||
5. **Do not mix targets in one scaffold.** Pick one. Document the alternatives in the
|
||||
`## Deployment` section of the generated README.
|
||||
80
skills/agent-system-design/references/feature-map.md
Normal file
80
skills/agent-system-design/references/feature-map.md
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
# OpenClaw vs Claude Code Feature Map
|
||||
|
||||
Builder reference for the agent-system-design skill. For each capability, the table shows
|
||||
what to scaffold when Claude Code is the target runtime.
|
||||
|
||||
## Capability Coverage
|
||||
|
||||
| # | Capability | Status | What to scaffold | Min CC version |
|
||||
|---|-----------|--------|-----------------|---------------|
|
||||
| 1 | Agent Runtime | OK | `CLAUDE.md` + `settings.json` | v2.1.84 |
|
||||
| 2 | Shell Execution | OK | `hooks/pre-tool-use.sh` + deny list in `settings.json` | v2.1.78 |
|
||||
| 3 | File I/O | OK | `settings.json` allow list under `permissions.allow` | baseline |
|
||||
| 4 | Web Search | OK | `settings.json` allow list (WebSearch tool) | baseline |
|
||||
| 5 | Browser | OK | `.mcp.json` with Playwright server entry | external |
|
||||
| 6 | Computer Use | Docs | README note: Desktop app required, not available headless | v2.1.86 |
|
||||
| 7 | Memory | Partial | `memory/MEMORY.md` + memory block in `CLAUDE.md` | v2.1.32 |
|
||||
| 8 | Multi-Agent | OK | `.claude/agents/*.md` subagent definitions | v2.1.32 |
|
||||
| 9 | Messaging | Partial | `.mcp.json` Slack server + channels guide in README | v2.1.80 |
|
||||
| 10 | Model Providers | Partial | `model:` frontmatter in agent `.md` files | baseline |
|
||||
| 11 | Cron/Automation | OK | `automation.sh` wrapper + `launchd.plist` or `crontab` entry | v2.1.71 |
|
||||
| 12 | Always-On | Partial | `launchd`/`systemd` service + `tmux` session guide | infra |
|
||||
| 13 | Plugin System | OK | Plugin manifest (`plugin.json` + `CLAUDE.md`) | v2.1.84 |
|
||||
| 14 | Skills | OK | `.claude/skills/*.md` skill definitions | baseline |
|
||||
| 15 | Security | OK | Hooks + permissions deny list + audit log | v2.1.78 |
|
||||
| 16 | Voice/TTS | Docs | README note: MCP-based approach, no native support | N/A |
|
||||
| 17 | Companion Apps | Docs | README refs to Desktop app and Dispatch channel | v2.1.85 |
|
||||
| 18 | Gateway | Partial | `/schedule` skill + HTTP webhook hooks | v2.1.63 |
|
||||
| 19 | Canvas/A2UI | Gap | Playwright workaround only, no native equivalent | N/A |
|
||||
| 20 | Configuration | OK | `settings.json` + `CLAUDE.md` hierarchy | v2.1.84 |
|
||||
| 21 | Chat Commands | OK | `.claude/skills/*.md` (slash commands) | baseline |
|
||||
| 22 | CLI | OK | Wrapper scripts (`automation.sh`, `run-agent.sh`) | baseline |
|
||||
|
||||
**Score: 13 full OK (59%) | 8 different approach/Partial/Docs (36%) | 1 gap (5%)**
|
||||
**Minimum version for full coverage: v2.1.86** (Computer Use requires Desktop app)
|
||||
|
||||
## Status Key
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| OK | Native Claude Code equivalent, scaffold directly |
|
||||
| Partial | Functional but requires workaround or external integration |
|
||||
| Docs | No runtime equivalent; document the limitation and alternative |
|
||||
| Gap | No practical equivalent in Claude Code today |
|
||||
|
||||
## Scaffold Actions by Status
|
||||
|
||||
**OK** -- Generate the file(s) listed in "What to scaffold". Standard templates apply.
|
||||
|
||||
**Partial** -- Scaffold what exists, add a `## Limitations` section to the README noting
|
||||
the gap and the workaround. Do not promise feature parity.
|
||||
|
||||
**Docs** -- Add a `## Notes` section to the README only. Do not scaffold non-existent
|
||||
infrastructure. Link to the relevant Anthropic documentation or issue.
|
||||
|
||||
**Gap** -- Add a `## Known Gaps` section. Acknowledge the gap, document the workaround
|
||||
(Playwright for Canvas/A2UI), and note if it is on the roadmap.
|
||||
|
||||
## Claude Code Ecosystem Map
|
||||
|
||||
How Claude Code components map to the OpenClaw product family:
|
||||
|
||||
| Claude Code component | OpenClaw equivalent | Notes |
|
||||
|----------------------|--------------------|----|
|
||||
| Claude Code CLI | OpenClaw core agent | Headless, full tool access |
|
||||
| Claude Code Desktop | OpenClaw + macOS app | Adds Computer Use, GUI |
|
||||
| Cowork | OpenClaw for non-developers | Simplified UX, no CLI |
|
||||
| Dispatch | Telegram/WhatsApp channels | Mobile access layer |
|
||||
| `/schedule` skill | HEARTBEAT.md cron | Scheduled agent triggers |
|
||||
| Anthropic Agent SDK | OpenClaw API | Managed agents via `/v1/agents` |
|
||||
|
||||
## Version Compatibility Notes
|
||||
|
||||
- **baseline**: Available since first public Claude Code release; no version gate.
|
||||
- **external**: Depends on MCP server availability, not Claude Code version.
|
||||
- **infra**: Depends on the deployment host (macOS/Linux), not Claude Code version.
|
||||
- **N/A**: Not applicable to Claude Code; alternative approach required.
|
||||
|
||||
When scaffolding for a specific Claude Code version, check that all required capabilities
|
||||
meet the min version. If the user's version is below v2.1.86, exclude Computer Use from
|
||||
the feature set and document it under Known Gaps.
|
||||
357
skills/agent-system-design/references/pipeline-patterns.md
Normal file
357
skills/agent-system-design/references/pipeline-patterns.md
Normal file
|
|
@ -0,0 +1,357 @@
|
|||
# Pipeline Patterns Reference
|
||||
|
||||
Detailed patterns for designing multi-agent pipelines in Claude Code.
|
||||
|
||||
---
|
||||
|
||||
## The 3-agent pattern
|
||||
|
||||
The foundational pattern for autonomous content and analysis workflows.
|
||||
|
||||
**Roles:**
|
||||
- **Researcher** — gathers inputs, structures knowledge, produces a brief
|
||||
- **Writer** — produces primary output from the brief
|
||||
- **Reviewer** — evaluates output against criteria, approves or requests revision
|
||||
|
||||
**When to use:** Any workflow where you need sourced input, generated output, and a quality gate. Content production, report generation, code review pipelines, competitive analysis.
|
||||
|
||||
**How to customize:**
|
||||
|
||||
| Domain | Researcher focus | Writer focus | Reviewer criteria |
|
||||
|--------|-----------------|--------------|-------------------|
|
||||
| Content | Web sources, existing articles, reader questions | Article draft matching voice and format | Accuracy, engagement, brand voice |
|
||||
| Engineering | Codebase patterns, issue context, API docs | Implementation or PR description | Correctness, style, test coverage |
|
||||
| Consulting | Client data, market research, precedents | Recommendation or slide content | Evidence quality, actionability |
|
||||
| Operations | Logs, metrics, incident history | Incident report or runbook update | Completeness, clarity, ownership |
|
||||
|
||||
**Scaling the pattern:**
|
||||
|
||||
- Add a **Finalizer** agent between Reviewer and output for polish steps (SEO, formatting, compliance checks)
|
||||
- Add a **Distributor** agent after output for routing (email, Slack, WordPress, Linear)
|
||||
- Replace the single Researcher with a **parallel research team** (two agents gathering different source types simultaneously)
|
||||
- Add a **Memory Manager** agent that reads and writes state files, keeping other agents focused on their domain
|
||||
|
||||
---
|
||||
|
||||
## The 9-step pipeline template
|
||||
|
||||
This is the canonical sequence for a full pipeline skill. Adapt as needed — not all steps are required for every workflow.
|
||||
|
||||
```
|
||||
Step 1: Read project context
|
||||
- Read CLAUDE.md and any project-specific config
|
||||
- Establish constraints before any agent runs
|
||||
|
||||
Step 2: Read memory / previous state
|
||||
- Load memory/MEMORY.md or data/run-state.json
|
||||
- Pass relevant state to downstream agents as context
|
||||
|
||||
Step 3: Agent 1 — Researcher
|
||||
- Invoke with: topic, constraints, memory context
|
||||
- Output: structured research brief (markdown or JSON)
|
||||
|
||||
Step 4: Agent 2 — Writer
|
||||
- Invoke with: research brief, output format spec, voice guidelines
|
||||
- Output: primary draft
|
||||
|
||||
Step 5: Agent 3 — Reviewer
|
||||
- Invoke with: draft, scoring rubric, acceptance criteria
|
||||
- Output: score + pass/fail + specific revision requests
|
||||
|
||||
Step 6: Revision loop (conditional)
|
||||
- If reviewer score < threshold: invoke Writer again with feedback
|
||||
- Max 2 revision passes before escalating to human
|
||||
- If max passes exceeded: save draft with NEEDS_REVIEW flag
|
||||
|
||||
Step 7: Save outputs
|
||||
- Write final output to designated location
|
||||
- Publish if automated publishing is configured
|
||||
|
||||
Step 8: Update memory
|
||||
- Append run summary to memory file
|
||||
- Update counters, timestamps, last-processed markers
|
||||
|
||||
Step 9: Confirm and report
|
||||
- Print summary of what was produced
|
||||
- List any items that need human attention
|
||||
```
|
||||
|
||||
**Revision loop implementation note:** The loop should be explicit in the skill file. Do not rely on the agent to decide whether to loop — tell it exactly: "If the reviewer score is below 70, invoke the writer agent again with the reviewer's feedback. Do this at most twice."
|
||||
|
||||
---
|
||||
|
||||
## Agent role templates
|
||||
|
||||
Copy these as starting points. Replace bracketed values.
|
||||
|
||||
### Researcher
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: researcher
|
||||
description: |
|
||||
Use this agent to gather and structure information before writing or analysis.
|
||||
|
||||
<example>
|
||||
Context: Pipeline needs sourced input before writing
|
||||
user: "Research [topic] for this week's report"
|
||||
assistant: "I'll use the researcher agent to gather sources and produce a brief."
|
||||
<commentary>
|
||||
Research request before production triggers the researcher.
|
||||
</commentary>
|
||||
</example>
|
||||
model: sonnet
|
||||
tools: ["Read", "Glob", "Grep", "WebSearch", "Bash"]
|
||||
---
|
||||
|
||||
## How you work
|
||||
|
||||
You produce research briefs, not finished content. Your output is always structured
|
||||
for a downstream writer to consume.
|
||||
|
||||
1. Read any existing memory or prior research on this topic
|
||||
2. Gather sources using available tools (web search, local files, MCP servers)
|
||||
3. Extract the 5-7 most relevant facts, quotes, or data points
|
||||
4. Note source reliability and any gaps in coverage
|
||||
5. Produce a brief with sections: Background, Key Points, Sources, Gaps
|
||||
|
||||
## Rules
|
||||
|
||||
- Never fabricate sources or quotes
|
||||
- Mark unverified claims explicitly
|
||||
- Keep briefs under 800 words unless the topic demands more
|
||||
- List every source URL or file path used
|
||||
|
||||
## Output format
|
||||
|
||||
```
|
||||
## Research Brief: [Topic]
|
||||
Date: [date]
|
||||
|
||||
### Background
|
||||
[2-3 sentences of context]
|
||||
|
||||
### Key Points
|
||||
- [point 1] (source: [url/file])
|
||||
- [point 2] (source: [url/file])
|
||||
...
|
||||
|
||||
### Sources
|
||||
[list of all sources consulted]
|
||||
|
||||
### Gaps
|
||||
[what could not be verified or found]
|
||||
```
|
||||
```
|
||||
|
||||
### Writer
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: writer
|
||||
description: |
|
||||
Use this agent to produce primary written output from a research brief or spec.
|
||||
|
||||
<example>
|
||||
Context: Research brief is ready, article needs to be written
|
||||
user: "Write the article from this brief"
|
||||
assistant: "I'll use the writer agent to draft from the research brief."
|
||||
<commentary>
|
||||
Production request with existing brief triggers the writer.
|
||||
</commentary>
|
||||
</example>
|
||||
model: opus
|
||||
tools: ["Read", "Write", "Glob"]
|
||||
---
|
||||
|
||||
## How you work
|
||||
|
||||
You produce first drafts from structured inputs. You do not research — you write.
|
||||
|
||||
1. Read the research brief and any style/voice guidelines
|
||||
2. Read examples of approved past output for voice calibration
|
||||
3. Draft the primary output following the specified format
|
||||
4. Do not add information not present in the brief
|
||||
5. Flag any gaps where the brief was insufficient
|
||||
|
||||
## Rules
|
||||
|
||||
- Follow the voice and format guidelines exactly
|
||||
- Never add claims not supported by the brief
|
||||
- Keep within specified word count ±10%
|
||||
- End with a concrete takeaway or call to action
|
||||
|
||||
## Output format
|
||||
|
||||
[Specify the exact output format for your domain]
|
||||
```
|
||||
|
||||
### Reviewer
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: reviewer
|
||||
description: |
|
||||
Use this agent to evaluate output quality and approve or request revisions.
|
||||
|
||||
<example>
|
||||
Context: Draft is ready for quality check
|
||||
user: "Review this draft before publishing"
|
||||
assistant: "I'll use the reviewer agent to score and evaluate the draft."
|
||||
<commentary>
|
||||
Quality evaluation request triggers the reviewer.
|
||||
</commentary>
|
||||
</example>
|
||||
model: opus
|
||||
tools: ["Read"]
|
||||
---
|
||||
|
||||
## How you work
|
||||
|
||||
You evaluate drafts against defined criteria and produce a scored assessment.
|
||||
|
||||
1. Read the draft and the original brief or requirements
|
||||
2. Score against each dimension in the rubric (see Output format)
|
||||
3. Note specific issues with line references where possible
|
||||
4. Produce a pass/fail decision with justification
|
||||
|
||||
## Rules
|
||||
|
||||
- Score honestly — do not inflate to avoid revision cycles
|
||||
- Be specific: "paragraph 3 is vague" not "needs more detail"
|
||||
- Pass threshold is 70/100 overall with no dimension below 50
|
||||
|
||||
## Output format
|
||||
|
||||
```
|
||||
## Review: [Draft title]
|
||||
|
||||
### Scores
|
||||
- Accuracy: [0-25] — [one sentence justification]
|
||||
- Clarity: [0-25] — [one sentence justification]
|
||||
- Completeness: [0-25] — [one sentence justification]
|
||||
- Format/Voice: [0-25] — [one sentence justification]
|
||||
|
||||
### Overall: [total]/100
|
||||
|
||||
### Decision: PASS | REVISE | REJECT
|
||||
|
||||
### Revision requests (if REVISE)
|
||||
1. [specific request]
|
||||
2. [specific request]
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality gates: 4-level scoring rubric
|
||||
|
||||
Use this rubric in reviewer agents and pipeline acceptance criteria.
|
||||
|
||||
| Dimension | 0-12 (Poor) | 13-18 (Acceptable) | 19-22 (Good) | 23-25 (Excellent) |
|
||||
|-----------|-------------|-------------------|--------------|-------------------|
|
||||
| **Accuracy** | Multiple errors or unsupported claims | Minor errors, mostly supported | All claims verifiable | Fully sourced, no errors |
|
||||
| **Clarity** | Hard to follow, jargon-heavy | Mostly clear, some confusion | Clear throughout | Immediately clear, no ambiguity |
|
||||
| **Completeness** | Major gaps, incomplete | Covers main points, some gaps | Thorough coverage | Nothing missing |
|
||||
| **Format/Voice** | Wrong format or tone | Mostly correct, minor deviations | Correct format and tone | Perfect fit for context |
|
||||
|
||||
**Thresholds:**
|
||||
- 90-100: Publish immediately
|
||||
- 70-89: Publish with minor edits
|
||||
- 50-69: Revise and re-review
|
||||
- Below 50: Reject, start over or escalate to human
|
||||
|
||||
---
|
||||
|
||||
## Pipeline skill format
|
||||
|
||||
Pipeline skills live in `.claude/skills/<name>/SKILL.md`. They are invoked as `/plugin:skill-name` or triggered by the agent system automatically.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: weekly-report
|
||||
description: |
|
||||
Run the weekly report pipeline. Triggers on: "run weekly report",
|
||||
"generate this week's report", "weekly pipeline"
|
||||
version: 0.1.0
|
||||
---
|
||||
|
||||
## Weekly Report Pipeline
|
||||
|
||||
Run these steps in order. Do not skip steps. If a step fails, stop and report the error.
|
||||
|
||||
### Step 1: Load context
|
||||
Read `CLAUDE.md` and `memory/MEMORY.md`. Note the last run date and any pending items.
|
||||
|
||||
### Step 2: Research
|
||||
Use the Agent tool to invoke the `researcher` agent with this prompt:
|
||||
"Research [topic] for the period [date range]. Focus on [specific angle]."
|
||||
Save the research brief to `data/research-brief-[date].md`.
|
||||
|
||||
### Step 3: Write
|
||||
Use the Agent tool to invoke the `writer` agent with this prompt:
|
||||
"Write the weekly report from [path to brief]. Follow the format in [style guide path]."
|
||||
Save the draft to `drafts/weekly-[date].md`.
|
||||
|
||||
### Step 4: Review
|
||||
Use the Agent tool to invoke the `reviewer` agent with this prompt:
|
||||
"Review the draft at [path]. Use the standard 4-dimension rubric."
|
||||
|
||||
### Step 5: Handle review result
|
||||
- If score >= 70: proceed to Step 6
|
||||
- If score < 70 and revision count < 2: invoke writer again with reviewer feedback, then re-review
|
||||
- If score < 70 after 2 revisions: save draft with NEEDS_REVIEW flag, skip to Step 7
|
||||
|
||||
### Step 6: Finalize
|
||||
[Publishing or distribution steps]
|
||||
|
||||
### Step 7: Update memory
|
||||
Append to `memory/MEMORY.md`:
|
||||
- Date of run
|
||||
- Output file path
|
||||
- Review score
|
||||
- Any items needing human attention
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent frontmatter: all valid fields
|
||||
|
||||
```yaml
|
||||
name: <string> # required — slug, used for routing and invocation
|
||||
description: | # required — trigger text + examples
|
||||
<string>
|
||||
model: sonnet|opus # required — model for this agent's runs
|
||||
tools: [<string>, ...] # required — explicit tool allowlist
|
||||
color: <string> # optional — UI color hint (green, blue, red, yellow, purple)
|
||||
```
|
||||
|
||||
Tools available for agents: `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash`, `WebSearch`, `WebFetch`, `Agent`, `AskUserQuestion`, and any MCP tool by its full name (e.g., `mcp__tavily__tavily_search`).
|
||||
|
||||
---
|
||||
|
||||
## How agents communicate
|
||||
|
||||
**Agent tool (sequential):** The orchestrating skill or parent agent uses the `Agent` tool to invoke a subagent. The subagent runs to completion and returns its output. This is the standard pattern for pipeline steps.
|
||||
|
||||
```
|
||||
Agent tool call:
|
||||
agent: researcher
|
||||
prompt: "Research X and produce a brief in the format..."
|
||||
→ researcher runs, returns brief text
|
||||
→ parent continues with Step 2
|
||||
```
|
||||
|
||||
**SendMessage (async / worktree):** For parallel execution, agents can be spawned in separate worktrees. Each worktree runs independently; results are assembled by the orchestrator after all complete. Use this when steps have no dependencies on each other (e.g., researching two topics simultaneously).
|
||||
|
||||
**Worktree isolation:** When an agent runs in a worktree, it has its own working copy of the repository. It cannot see changes made by other agents running simultaneously. Use a shared output directory (outside the worktrees) or a coordination file to merge results.
|
||||
|
||||
**File-based handoff (simple and reliable):** The most robust communication pattern is file-based. Each agent writes its output to a designated path; the next agent reads from that path. This works in any execution mode and produces an audit trail of intermediate outputs.
|
||||
|
||||
```
|
||||
researcher → data/brief-2026-04-10.md
|
||||
writer → reads data/brief-2026-04-10.md → drafts/article-2026-04-10.md
|
||||
reviewer → reads drafts/article-2026-04-10.md → data/review-2026-04-10.md
|
||||
```
|
||||
|
||||
For most personal and small-team pipelines, sequential execution with file-based handoff is the right choice. It is simpler to debug, easier to resume after failure, and produces a clear audit trail.
|
||||
280
skills/agent-system-design/references/security-patterns.md
Normal file
280
skills/agent-system-design/references/security-patterns.md
Normal file
|
|
@ -0,0 +1,280 @@
|
|||
# Security Patterns for Autonomous Agents
|
||||
|
||||
Reference for the agent-system-design skill. Covers permission modes, hook-based
|
||||
guardrails, settings.json configuration, and a checklist for hardening autonomous agents.
|
||||
|
||||
---
|
||||
|
||||
## 1. Permission Modes
|
||||
|
||||
Four levels of approval, from most restrictive to least:
|
||||
|
||||
### Default (interactive approval)
|
||||
Claude asks the user before every tool call. Suitable for exploratory sessions.
|
||||
No configuration required.
|
||||
|
||||
### Auto-edit (AcceptEdits mode)
|
||||
File edits are auto-approved. Bash commands still require approval.
|
||||
Enables faster iteration on code without allowing arbitrary shell execution.
|
||||
|
||||
```json
|
||||
{
|
||||
"autoApprove": ["Edit", "Write"]
|
||||
}
|
||||
```
|
||||
|
||||
### Auto Mode (AI classifier)
|
||||
An AI classifier evaluates each tool call and approves or blocks it based on
|
||||
predicted risk. Reported metrics: 0.4% false positive rate (safe calls blocked),
|
||||
5.7% false negative rate (unsafe calls approved).
|
||||
|
||||
Suitable for: attended automation where the developer is nearby and can intervene.
|
||||
Not suitable for: fully unattended production agents.
|
||||
|
||||
```json
|
||||
{
|
||||
"autoApprove": ["auto"]
|
||||
}
|
||||
```
|
||||
|
||||
### Bypass (--dangerously-skip-permissions)
|
||||
All tool calls are auto-approved without review. Must only be used inside a
|
||||
sandbox (Docker, VM, or a throwaway environment with no access to production systems).
|
||||
Never use on the host machine with access to real credentials or filesystems.
|
||||
|
||||
```bash
|
||||
claude --dangerously-skip-permissions -p "run the pipeline"
|
||||
```
|
||||
|
||||
**Decision rule:** Match the permission mode to the blast radius. The more access
|
||||
the agent has, the more restrictive the approval mode must be.
|
||||
|
||||
---
|
||||
|
||||
## 2. Hook-Based Guardrails
|
||||
|
||||
Hooks run synchronously before and after tool calls. A non-zero exit from
|
||||
`PreToolUse` blocks the tool call entirely. Five standard patterns:
|
||||
|
||||
### Pattern 1: Destructive Command Blocking
|
||||
Block commands that cannot be undone.
|
||||
|
||||
```bash
|
||||
# hooks/pre-tool-use.sh
|
||||
BLOCKED_PATTERNS=(
|
||||
"rm -rf"
|
||||
"mkfs"
|
||||
"dd if="
|
||||
":(){ :|:& };:" # fork bomb
|
||||
"> /dev/"
|
||||
)
|
||||
COMMAND="$CLAUDE_TOOL_INPUT_COMMAND"
|
||||
for pattern in "${BLOCKED_PATTERNS[@]}"; do
|
||||
if echo "$COMMAND" | grep -qF "$pattern"; then
|
||||
echo "BLOCKED: destructive pattern detected: $pattern" >&2
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### Pattern 2: Piped Script Execution Blocking
|
||||
Block patterns that download and execute code in a single pipeline.
|
||||
|
||||
```bash
|
||||
PIPED_EXEC_PATTERNS=(
|
||||
"curl.*|.*bash"
|
||||
"curl.*|.*sh"
|
||||
"wget.*|.*bash"
|
||||
"wget.*|.*sh"
|
||||
)
|
||||
for pattern in "${PIPED_EXEC_PATTERNS[@]}"; do
|
||||
if echo "$COMMAND" | grep -qE "$pattern"; then
|
||||
echo "BLOCKED: piped script execution detected" >&2
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### Pattern 3: Privilege Escalation Blocking
|
||||
Block commands that elevate privileges or weaken file permissions.
|
||||
|
||||
```bash
|
||||
PRIV_PATTERNS=(
|
||||
"sudo"
|
||||
"chmod 777"
|
||||
"chmod a+x /etc"
|
||||
"shutdown"
|
||||
"reboot"
|
||||
"init 0"
|
||||
)
|
||||
for pattern in "${PRIV_PATTERNS[@]}"; do
|
||||
if echo "$COMMAND" | grep -qF "$pattern"; then
|
||||
echo "BLOCKED: privilege escalation detected" >&2
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### Pattern 4: Path Restriction
|
||||
Prevent writes outside the project directory.
|
||||
|
||||
```bash
|
||||
PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
TOOL_PATH="$CLAUDE_TOOL_INPUT_FILE_PATH"
|
||||
if [ -n "$TOOL_PATH" ]; then
|
||||
REAL_PATH="$(realpath "$TOOL_PATH" 2>/dev/null || echo "$TOOL_PATH")"
|
||||
if [[ "$REAL_PATH" != "$PROJECT_DIR"* ]]; then
|
||||
echo "BLOCKED: write outside project dir: $REAL_PATH" >&2
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
### Pattern 5: Audit Logging
|
||||
Log every tool call with timestamp for post-hoc review.
|
||||
|
||||
```bash
|
||||
# hooks/post-tool-use.sh
|
||||
LOG_FILE="$PROJECT_DIR/logs/audit.log"
|
||||
mkdir -p "$(dirname "$LOG_FILE")"
|
||||
echo "$(date -u +"%Y-%m-%dT%H:%M:%SZ") TOOL=$CLAUDE_TOOL_NAME INPUT=$CLAUDE_TOOL_INPUT" >> "$LOG_FILE"
|
||||
```
|
||||
|
||||
Combine all five patterns into a single `pre-tool-use.sh` and a separate
|
||||
`post-tool-use.sh`. Keep them under 80 lines each so they are auditable at a glance.
|
||||
|
||||
---
|
||||
|
||||
## 3. settings.json Security Configuration
|
||||
|
||||
The full security configuration surface in `settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(git:*)",
|
||||
"Bash(npm run *)",
|
||||
"Read(**)",
|
||||
"Write(src/**)",
|
||||
"Edit(src/**)"
|
||||
],
|
||||
"deny": [
|
||||
"Bash(rm -rf *)",
|
||||
"Bash(sudo *)",
|
||||
"Bash(curl * | *)",
|
||||
"Bash(wget * | *)",
|
||||
"Write(/etc/*)",
|
||||
"Write(~/.ssh/*)",
|
||||
"Write(~/.zshenv)"
|
||||
]
|
||||
},
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Bash",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "./hooks/pre-tool-use.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "*",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "./hooks/post-tool-use.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Allow list principle:** Prefer an explicit allow list over a deny list alone.
|
||||
The deny list catches known-bad patterns; the allow list enforces least privilege.
|
||||
Both together provide defense in depth.
|
||||
|
||||
**Glob patterns in deny list:** Use `*` conservatively. `Bash(sudo *)` blocks
|
||||
all sudo invocations. `Write(/etc/*)` blocks all writes to system config.
|
||||
|
||||
---
|
||||
|
||||
## 4. Security Checklist for Autonomous Agents
|
||||
|
||||
Verify each item before declaring an agent production-ready:
|
||||
|
||||
- [ ] `PreToolUse` hook is present and blocks destructive commands (Pattern 1-3 above)
|
||||
- [ ] `PostToolUse` audit log is enabled and written to a persistent location
|
||||
- [ ] `permissions.deny` list covers: `rm -rf *`, `sudo *`, `curl * | *`, `wget * | *`
|
||||
- [ ] `permissions.allow` list is as narrow as the agent's task requires
|
||||
- [ ] MEMORY.md does not contain API keys, tokens, or passwords
|
||||
- [ ] `.env` is in `.gitignore`; secrets are loaded from environment, not from files tracked by git
|
||||
- [ ] Deployment target matches the blast radius (see `deployment-targets.md`)
|
||||
- [ ] If always-on: phone approval via permission relay is configured (v2.1.81+)
|
||||
- [ ] Audit log is rotated (logrotate or launchd-managed)
|
||||
- [ ] Hook scripts are executable (`chmod +x hooks/*.sh`) and checked into version control
|
||||
|
||||
### Phone Approval (v2.1.81+)
|
||||
|
||||
For unattended agents that must occasionally escalate to a human:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Bash(sudo *)",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "prompt",
|
||||
"prompt": "This command requires elevated privileges. Approve? (yes/no)",
|
||||
"channel": "telegram"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The agent pauses and sends the approval request to the configured channel.
|
||||
The operator approves or rejects from their phone. If no response within the
|
||||
timeout, the hook exits non-zero and the command is blocked.
|
||||
|
||||
---
|
||||
|
||||
## 5. OpenClaw vs Claude Code: Security Philosophy
|
||||
|
||||
| Dimension | OpenClaw | Claude Code |
|
||||
|-----------|---------|-------------|
|
||||
| Primary mechanism | Docker sandbox (containment) | Hooks + deny list (prevention) |
|
||||
| Approach | Contain the damage after the fact | Prevent the action before it runs |
|
||||
| Escape risk | Container escape (low, not zero) | Hook bypass if hook is misconfigured |
|
||||
| Auditability | Container logs | Audit log hook (Pattern 5) |
|
||||
| Operator control | Docker network/volume flags | settings.json permissions |
|
||||
| Mobile escalation | Native | Permission relay via channel MCP (v2.1.81+) |
|
||||
|
||||
**Containment vs Prevention:** OpenClaw runs the agent inside a Docker container with
|
||||
limited network and volume mounts. If the agent does something harmful, the damage is
|
||||
contained to the container. Claude Code instead prevents harmful actions from running
|
||||
at all, via hooks and the permissions deny list.
|
||||
|
||||
**Tradeoff:** Containment is harder to escape but allows the harmful action to attempt
|
||||
execution. Prevention stops it earlier but requires the hook to be correctly configured
|
||||
and maintained. For production agents, combine both: run Claude Code inside Docker AND
|
||||
configure hooks and deny lists.
|
||||
|
||||
**Combined approach (recommended for production):**
|
||||
1. Run `claude` inside a Docker container with minimal volume mounts
|
||||
2. Configure `PreToolUse` hooks with Patterns 1-4
|
||||
3. Enable `PostToolUse` audit logging (Pattern 5)
|
||||
4. Use an explicit `permissions.deny` list
|
||||
5. Do not use `--dangerously-skip-permissions` outside the container
|
||||
|
||||
This gives containment as a last resort and prevention as the primary defense.
|
||||
Loading…
Add table
Add a link
Reference in a new issue