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:

```json
{
  "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](https://git.fromaitochitta.com/open/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

```bash
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
```bash
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`**:

```markdown
---
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

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

### On failure
revert

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

---

## Step 3: Create deployment-advisor agent

### Files to create

**`agents/deployment-advisor.md`**:

```markdown
---
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:
- [file 1]: [description]
- [file 2]: [description]

Activation:
[exact commands to activate the deployment]

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

Rollback:
[exact commands to undo if needed]
```
```

### Verify

```bash
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
```bash
git commit -m "feat(agents): add deployment-advisor agent"
```

---

## Step 4: Create /agent-factory:evaluate command

### Files to create

**`commands/evaluate.md`**:

```markdown
---
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

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

### On failure
revert

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

---

## Step 5: Create /agent-factory:status command

### Files to create

**`commands/status.md`**:

```markdown
---
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

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

### On failure
revert

### Checkpoint
```bash
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`