agent-builder/.claude/plans/blueprints/session-1-foundation.md

Session 1: Foundation — Rename and Commands

Steps 1, 2, 3, 4, 5 | Wave 1 | Depends on: none

Dependencies

Entry condition: none (first session, clean repo)

Scope Fence

Touch:

• .claude-plugin/plugin.json
• CLAUDE.md
• README.md
• commands/build.md
• commands/deploy.md (new)
• commands/evaluate.md (new)
• commands/status.md (new)
• agents/deployment-advisor.md (new)
• skills/agent-system-design/SKILL.md (rename reference only)

Never touch:

• scripts/templates/* (except reading existing for reference)
• skills/managed-agents/
• agents/builder.md (content — only read for format reference)
• Any file in scripts/templates/memory/, scripts/templates/heartbeat/, etc.

---

Step 1: Rename plugin from agent-builder to agent-factory

Files to modify

.claude-plugin/plugin.json — Replace content with:

{
  "name": "agent-factory",
  "description": "Build and manage autonomous agent systems with Claude Code. Guided workflow from idea to deployed, self-running agents. Covers all 22 agent capabilities with patterns from OpenClaw and Paperclip.",
  "version": "0.2.0",
  "author": {
    "name": "Kjell Tore Guttormsen",
    "url": "https://fromaitochitta.com"
  },
  "repository": "https://git.fromaitochitta.com/open/agent-factory",
  "license": "MIT",
  "keywords": [
    "agent",
    "autonomous",
    "pipeline",
    "automation",
    "hooks",
    "security",
    "deployment",
    "memory",
    "heartbeat",
    "governance"
  ]
}

CLAUDE.md — Apply these diffs:

• Line 1: # Agent Builder Plugin → # Agent Factory Plugin
• Line 3: Plugin that helps users build complete autonomous agent systems → Plugin that guides users through building complete autonomous agent systems
• Line 8: The /agent-builder:build command → The /agent-factory:build command
• All other occurrences of agent-builder → agent-factory

README.md — Full rewrite for v0.2.0 (will be rewritten again in Step 27 for v1.0):

Replace # Agent Builder with # Agent Factory and update:

• Install command: /install agent-factory or --plugin-dir ./agent-factory
• All /agent-builder: prefixes → /agent-factory:
• Repository URL: https://git.fromaitochitta.com/open/agent-factory
• Add recommendation: "For the best experience, install via ktg-plugin-marketplace which includes Agent Factory plus the ultra-suite (ultraplan, ultraresearch, ultraexecute)."

commands/build.md — Diff:

• Line 7: You are running /agent-builder:build → `You are running `/agent-factory:build

skills/agent-system-design/SKILL.md — Diff:

• Line 106: Run /agent-builder:build → `Run `/agent-factory:build

Verify

grep -r "agent-builder" /Users/ktg/repos/agent-builder/ --include="*.md" --include="*.json" | grep -v ".git/" | grep -v "research/" | grep -v "ultraplan-spec" | grep -v "ultraplan-2026" | grep -v "blueprints/" | grep -v "execution-guide" | wc -l

Expected: 0 (all renamed)

On failure

revert

Checkpoint

git commit -m "feat!: rename plugin from agent-builder to agent-factory"

---

Step 2: Create /agent-factory:deploy command

Files to create

commands/deploy.md:

---
description: Configure deployment for your agent system. Supports /schedule (cloud), Desktop scheduled tasks, cron/launchd, systemd, and Docker.
argument-hint: "Optional: deployment target (schedule, desktop, local, vps, docker)"
allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash", "Agent", "AskUserQuestion"]
---

You are running `/agent-factory:deploy` — a guided deployment configuration for autonomous agent systems.

If $ARGUMENTS specifies a target, skip to that target's section. Otherwise, ask the user to choose.

---

## Step 1: Scan existing system

Read the user's agent system:
- Glob for `.claude/agents/*.md` — list all agents with names and models
- Glob for `.claude/skills/*/SKILL.md` and `.claude/skills/*.md` — list all skills
- Read `.claude/settings.json` if it exists — check hook configuration
- Check for existing automation: `automation/`, `HEARTBEAT.md`, `docker-compose.yml`
- Read `CLAUDE.md` for project context

Summarize what was found before proceeding.

---

## Step 2: Choose deployment target

Ask using AskUserQuestion:
"Where should your agents run? Choose a deployment target:

1. **Cloud (/schedule)** — Runs on Anthropic's cloud. Needs GitHub repo. No local file access. 1-hour minimum interval. Best for: PR reviews, CI triage, repo maintenance.
2. **Desktop scheduled tasks** — Runs on your machine via Claude Code Desktop app. Local file access. 1-minute minimum interval. Best for: local automation, file processing.
3. **Local (cron/launchd)** — Traditional scheduler. Runs headless via `claude -p`. Full local access. Best for: personal daily pipelines, development.
4. **VPS (systemd)** — Linux server with systemd service/timer. Always-on. Best for: team pipelines, production workloads.
5. **Docker** — Containerized agent. Portable, isolated. Best for: reproducible deployments, security isolation."

If `$ARGUMENTS` matches a target name, skip this question.

---

## Step 3: Configure chosen target

### Cloud (/schedule)

1. Check GitHub connection: suggest `/web-setup` if not connected
2. Explain: "Cloud tasks clone your repo on each run. Local files are not accessible. MCP connectors provide external service access."
3. Generate a task prompt from the user's pipeline skills
4. Guide the user through `/schedule` to create the task
5. Note minimum 1-hour interval

### Desktop scheduled tasks

1. Explain: "Desktop tasks run on your machine with full local file access."
2. Guide through the Desktop app's Schedule page
3. Configure permission mode for unattended operation

### Local (cron/launchd)

1. Read `${CLAUDE_PLUGIN_ROOT}/scripts/templates/automation.sh`
2. Copy and customize to `automation/run-pipeline.sh`
3. Replace SKILL_NAME with the user's pipeline name
4. Ask: "What schedule? (e.g., daily at 07:00, every 2 hours)"
5. For macOS: read `${CLAUDE_PLUGIN_ROOT}/scripts/templates/launchd.plist`, customize, save to `automation/`
6. For Linux: generate cron entry
7. Provide exact activation commands

### VPS (systemd)

1. Read `${CLAUDE_PLUGIN_ROOT}/scripts/templates/systemd-service.unit`
2. Ask: "What Linux user runs the agent?" and "Absolute path to project?"
3. Customize and save service + timer units to `automation/`
4. Copy automation.sh template to `automation/run-pipeline.sh`
5. Provide setup instructions including `systemctl enable/start`

### Docker

1. Read `${CLAUDE_PLUGIN_ROOT}/scripts/templates/docker/` templates (created in Session 6)
2. If templates don't exist yet: generate basic Dockerfile + docker-compose.yml inline
3. Customize with project-specific values
4. Save to project root
5. Provide `docker compose up -d` instructions

---

## Step 4: Verify deployment

For each target, provide a verification command:
- Cloud: `/schedule list` → task visible
- Desktop: Check Schedule page in Desktop app
- Local: `crontab -l | grep claude` or `launchctl list | grep claude`
- VPS: `systemctl status claude-agent`
- Docker: `docker compose ps`

Use the `deployment-advisor` agent when the user needs guidance choosing between targets.

---

## Step 5: Next steps

Tell the user:
- "Run `/agent-factory:status` to check your deployment"
- "Run `/agent-factory:evaluate` to assess your system's capability coverage"

Verify

head -3 /Users/ktg/repos/agent-builder/commands/deploy.md | grep -c "description:"

Expected: 1

On failure

revert

Checkpoint

git commit -m "feat(commands): add /agent-factory:deploy command"

---

Step 3: Create deployment-advisor agent

Files to create

agents/deployment-advisor.md:

---
name: deployment-advisor
description: |
  Use this agent when the user needs help choosing or configuring a deployment target for their agent system.

  <example>
  Context: User has built agents and wants to deploy
  user: "How should I deploy my agent system?"
  assistant: "I'll use the deployment-advisor to analyze your setup and recommend a target."
  <commentary>
  Deployment guidance request triggers the advisor.
  </commentary>
  </example>

  <example>
  Context: User wants to switch deployment targets
  user: "Can I move my agents from cron to Docker?"
  assistant: "I'll use the deployment-advisor to plan the migration."
  <commentary>
  Deployment migration request triggers the advisor.
  </commentary>
  </example>

  <example>
  Context: User asks about cloud vs local deployment
  user: "Should I use /schedule or cron for my pipeline?"
  assistant: "I'll use the deployment-advisor to compare the options for your use case."
  <commentary>
  Deployment comparison request triggers the advisor.
  </commentary>
  </example>
model: sonnet
color: blue
tools: ["Read", "Glob", "Grep", "Bash", "AskUserQuestion"]
---

## How you work

You analyze the user's agent system and recommend a deployment target based on their requirements.

1. Scan the project: `.claude/agents/*.md`, `.claude/skills/`, `.claude/settings.json`, `CLAUDE.md`, `automation/`, `HEARTBEAT.md`
2. Assess requirements by asking targeted questions:
   - Does this need to run when your computer is off?
   - Do agents need local filesystem access?
   - Is this for personal use or a team?
   - Any budget constraints for hosting?
   - Do agents need Computer Use (browser interaction)?
3. Read the deployment reference at `${CLAUDE_PLUGIN_ROOT}/skills/agent-system-design/references/deployment-targets.md`
4. Apply the decision guide from that reference
5. Recommend ONE primary target with clear reasoning
6. Generate the deployment configuration files for the chosen target

## Rules

- Never overwrite existing deployment config without asking the user first
- Always verify generated shell scripts with `bash -n` before saving
- Always include rollback instructions (how to undo the deployment)
- If the user's needs span multiple targets, recommend the simplest one that covers all requirements
- For Docker: always include `security_opt: [no-new-privileges:true]` in docker-compose.yml
- For /schedule (cloud): warn that local files are not accessible — only GitHub repo content
- Never recommend `--dangerously-skip-permissions` outside a Docker container or sandboxed environment

## Output format

DEPLOYMENT RECOMMENDATION

Target: [chosen target] Reason: [why this fits]

Files to create:

Activation: [exact commands to activate the deployment]

Verification: [exact commands to verify it's running]

Rollback: [exact commands to undo if needed]

Verify

python3 -c "import yaml; yaml.safe_load(open('/Users/ktg/repos/agent-builder/agents/deployment-advisor.md').read().split('---')[1])" 2>&1 && echo "VALID"

Expected: VALID

On failure

retry — fix YAML syntax, then revert if still failing

Checkpoint

git commit -m "feat(agents): add deployment-advisor agent"

---

Step 4: Create /agent-factory:evaluate command

Files to create

commands/evaluate.md:

---
description: Evaluate your agent system against the 22 agent capabilities. Shows coverage, gaps, and recommendations.
argument-hint: "Optional: focus area (security, deployment, memory, autonomy)"
allowed-tools: ["Read", "Glob", "Grep", "Bash"]
---

You are running `/agent-factory:evaluate` — a capability assessment for your agent system.

## Step 1: Scan project components

Scan for all agent system components:
- Agents: Glob for `.claude/agents/*.md`
- Pipeline skills: Glob for `.claude/skills/*/SKILL.md`
- Knowledge skills: Glob for `.claude/skills/*.md`
- Hooks: Glob for `.claude/hooks/*.sh` and `hooks/*.sh`
- Settings: Read `.claude/settings.json` if it exists
- Context: Read `CLAUDE.md` if it exists
- Automation: Glob for `automation/*`, `scripts/*.sh`
- Memory: look for `memory/MEMORY.md`, `memory/SESSION-STATE.md`, `data/run-state.json`
- Heartbeat: look for `HEARTBEAT.md`
- Goals: look for `GOALS.md`
- Governance: look for `GOVERNANCE.md`
- Org chart: look for `ORG-CHART.md`
- Budget: look for `budget/BUDGET.md`, `budget/cost-events.jsonl`
- Docker: look for `Dockerfile`, `docker-compose.yml`

## Step 2: Score against 22 capabilities

Read the feature map at `${CLAUDE_PLUGIN_ROOT}/skills/agent-system-design/references/feature-map.md`.

For each of the 22 capabilities, check whether the user's project has the corresponding component. Score as:
- **OK** — component exists and is properly configured
- **Partial** — component exists but is incomplete or misconfigured
- **Missing** — component does not exist

## Step 3: Output capability matrix

AGENT SYSTEM EVALUATION

#	Capability	Status	What exists	What's needed
1	Agent Runtime	OK	CLAUDE.md + settings.json	—
2	Shell Execution	Missing	—	hooks/pre-tool-use.sh + deny list
...

Score: X/22 OK | Y/22 Partial | Z/22 Missing

## Step 4: Recommendations

Provide specific recommendations for filling gaps, ordered by impact:
1. Security gaps first (hooks, permissions)
2. Core functionality gaps (missing agents, skills)
3. Operational gaps (memory, automation, deployment)
4. Advanced gaps (governance, budget, self-learning)

If $ARGUMENTS specifies a focus area, expand that section with detailed guidance and link to relevant templates from `${CLAUDE_PLUGIN_ROOT}/scripts/templates/`.

## Step 5: Next steps

Suggest: "Run `/agent-factory:build` to fill gaps interactively, or `/agent-factory:deploy` to configure deployment."

Verify

head -3 /Users/ktg/repos/agent-builder/commands/evaluate.md | grep -c "description:"

Expected: 1

On failure

revert

Checkpoint

git commit -m "feat(commands): add /agent-factory:evaluate command"

---

Step 5: Create /agent-factory:status command

Files to create

commands/status.md:

---
description: Quick status check of your agent infrastructure. Shows agents, skills, hooks, deployment, and recent activity.
argument-hint: ""
allowed-tools: ["Read", "Glob", "Grep", "Bash"]
---

You are running `/agent-factory:status` — a quick health check of your agent infrastructure.

## Scan and report

Run all scans, then output a single compact status report.

### Agents
Glob for `.claude/agents/*.md`. For each agent file:
- Read the frontmatter to extract: name, model, tools count
- List as: `[name] (model: [model], tools: [N])`
- Flag: agents without `<example>` blocks in description (unreliable triggering)

### Skills
Glob for `.claude/skills/*/SKILL.md` and `.claude/skills/*.md`. For each:
- Read frontmatter to extract: name, version (if present)
- List as: `[name] v[version]`
- Flag: skills without version field

### Hooks
Glob for `.claude/hooks/*.sh` and `hooks/*.sh`. For each:
- Check if executable: `test -x [path]`
- List as: `[filename] ([executable/not executable])`
- Flag: hook scripts that are not executable

### Settings
Read `.claude/settings.json` if it exists:
- Count permission allow rules and deny rules
- Count hook configurations
- Summarize: `[N] allow rules, [M] deny rules, [K] hooks configured`

### Deployment
Check for:
- `automation/*.sh` → "Local automation scripts found"
- `automation/*.plist` → "launchd config found"
- `automation/*.service` → "systemd config found"
- `docker-compose.yml` or `Dockerfile` → "Docker config found"
- `HEARTBEAT.md` → "Heartbeat file found"

### Memory
Check for:
- `memory/MEMORY.md` → "Long-term memory: found"
- `memory/SESSION-STATE.md` → "Session state: found"
- `memory/*.md` (daily logs) → "Daily logs: [N] files"
- `data/run-state.json` → "Run state: found"

### Recent activity
If `.claude/hooks/audit.log` or `hooks/audit.log` exists:
- Read last 5 lines
- Display as recent tool call log

### Issues
Compile all flags from above into an issues list:
- "WARNING: [agent] has no example blocks — may not trigger reliably"
- "WARNING: [hook] is not executable — run chmod +x"
- "WARNING: No hooks configured — unattended runs have no guardrails"

## Output format

AGENT FACTORY STATUS

Agents: [N] configured Skills: [N] loaded Hooks: [N] configured ([M] executable) Settings: [allow/deny/hooks counts] Deployment: [target or "not configured"] Memory: [tiers found]

Issues: [N] [list if any]

Verify

head -3 /Users/ktg/repos/agent-builder/commands/status.md | grep -c "description:"

Expected: 1

On failure

revert

Checkpoint

git commit -m "feat(commands): add /agent-factory:status command"

---

Exit Condition

• grep -r "agent-builder" /Users/ktg/repos/agent-builder/ --include="*.md" --include="*.json" | grep -v ".git/" | grep -v "research/" | grep -v "ultraplan" | grep -v "blueprints/" | grep -v "execution-guide" | wc -l → 0
• ls /Users/ktg/repos/agent-builder/commands/ | sort → build.md deploy.md evaluate.md status.md
• ls /Users/ktg/repos/agent-builder/agents/ | sort → builder.md deployment-advisor.md
• python3 -c "import json; d=json.load(open('/Users/ktg/repos/agent-builder/.claude-plugin/plugin.json')); assert d['name']=='agent-factory'; assert d['version']=='0.2.0'" → no error
• All agent files have valid YAML frontmatter: find /Users/ktg/repos/agent-builder/agents -name "*.md" -exec python3 -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]).read().split('---')[1])" {} \; → no errors

Quality Criteria

• All 4 command files have valid YAML frontmatter with description: field
• deployment-advisor.md has 3 <example> blocks in description
• deploy.md covers all 5 deployment targets with specific instructions
• evaluate.md references the 22-capability feature map
• status.md scans all 7 component types (agents, skills, hooks, settings, deployment, memory, activity)
• No agent-builder references remain in any touched file
• plugin.json version is 0.2.0 and name is agent-factory