feat(templates): add import/export system for agent systems
This commit is contained in:
Kjell Tore Guttormsen
parent
efbdbd82ed
commit
ea3ff53d2c
4 changed files with 372 additions and 0 deletions
29
scripts/templates/transfer/MANIFEST.md
Normal file
29
scripts/templates/transfer/MANIFEST.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
# Agent System Manifest
|
||||
Export name: {{EXPORT_NAME}}
|
||||
Export date: {{EXPORT_DATE}}
|
||||
Generated by: Agent Factory export-system.sh
|
||||
|
||||
## Components
|
||||
|
||||
| Type | File | Checksum (SHA256, first 16) |
|
||||
|------|------|---------------------------|
|
||||
| agent | .claude/agents/pipeline-runner.md | a1b2c3d4e5f6a7b8 |
|
||||
| skill | .claude/skills/my-pipeline/SKILL.md | b2c3d4e5f6a7b8c9 |
|
||||
| hook | .claude/hooks/pre-tool-use.sh | c3d4e5f6a7b8c9d0 |
|
||||
| settings | .claude/settings.json | d4e5f6a7b8c9d0e1 |
|
||||
| automation | automation/run-pipeline.sh | e5f6a7b8c9d0e1f2 |
|
||||
| context | CLAUDE.md | f6a7b8c9d0e1f2a3 |
|
||||
|
||||
## Requirements
|
||||
|
||||
| Requirement | Value |
|
||||
|-------------|-------|
|
||||
| Claude Code version | 1.x or later |
|
||||
| MCP servers | (list any required MCP servers, e.g. GitHub, Slack) |
|
||||
| Tools | Bash, Read, Write, Glob, Grep |
|
||||
| Environment | ANTHROPIC_API_KEY |
|
||||
|
||||
## Notes
|
||||
|
||||
Replace all `{{PLACEHOLDER}}` variables after import.
|
||||
See transfer/README.md for import instructions.
|
||||
64
scripts/templates/transfer/README.md
Normal file
64
scripts/templates/transfer/README.md
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
# Import / Export System
|
||||
|
||||
Portable packaging for agent systems. Export a working agent system from one
|
||||
project and import it into another, with automatic placeholder substitution.
|
||||
|
||||
## Export
|
||||
|
||||
Pack your current agent system into a tarball:
|
||||
|
||||
```bash
|
||||
bash scripts/templates/transfer/export-system.sh my-project-name
|
||||
# Creates: agent-system-my-project-name-2026-04-11.tar.gz
|
||||
```
|
||||
|
||||
### What is included
|
||||
|
||||
| Included | Excluded |
|
||||
|---------|---------|
|
||||
| `.claude/agents/` | `.env` (secrets) |
|
||||
| `.claude/skills/` | `*.local.*` files |
|
||||
| `.claude/hooks/` | `audit.log` |
|
||||
| `.claude/settings.json` | `cost-events.jsonl` |
|
||||
| `hooks/` | `memory/` (machine-specific state) |
|
||||
| `automation/` | `.git/` |
|
||||
| `scripts/` | |
|
||||
| `CLAUDE.md` | |
|
||||
|
||||
## Import
|
||||
|
||||
Extract a tarball into a new project directory:
|
||||
|
||||
```bash
|
||||
# Dry run first: inspect without extracting
|
||||
tar -tzf agent-system-my-project-name-2026-04-11.tar.gz
|
||||
|
||||
# Import (will stop if files conflict)
|
||||
bash scripts/templates/transfer/import-system.sh agent-system-my-project-name-2026-04-11.tar.gz
|
||||
|
||||
# Import and overwrite existing files
|
||||
bash scripts/templates/transfer/import-system.sh agent-system-my-project-name-2026-04-11.tar.gz --force
|
||||
```
|
||||
|
||||
The import script will:
|
||||
1. Read `MANIFEST.md` and verify the archive
|
||||
2. Check for conflicts with existing files (stops unless `--force`)
|
||||
3. Extract all files
|
||||
4. Replace `{{PROJECT_DIR}}` and `{{PROJECT_NAME}}` placeholders
|
||||
5. Make `.sh` files executable
|
||||
6. Validate agent frontmatter and hook syntax
|
||||
|
||||
## Customization after import
|
||||
|
||||
1. **Update `CLAUDE.md`** — replace project-specific context, goals, and constraints
|
||||
2. **Add secrets** — create `.env` with `ANTHROPIC_API_KEY=sk-ant-...`
|
||||
3. **Review hooks** — check that paths in hook scripts match your environment
|
||||
4. **Run `/agent-factory:status`** — verify all components load correctly
|
||||
5. **Run `/agent-factory:evaluate`** — check capability coverage
|
||||
|
||||
## Manifest
|
||||
|
||||
Each export includes `MANIFEST.md` listing every file with a SHA256 checksum
|
||||
(first 16 hex characters). Use this to verify file integrity after transfer.
|
||||
|
||||
Template manifest: `scripts/templates/transfer/MANIFEST.md`
|
||||
132
scripts/templates/transfer/export-system.sh
Normal file
132
scripts/templates/transfer/export-system.sh
Normal file
|
|
@ -0,0 +1,132 @@
|
|||
#!/bin/bash
|
||||
# Agent Factory — export-system.sh
|
||||
# Packages an agent system into a portable tarball with checksums.
|
||||
# Usage: bash export-system.sh <export-name>
|
||||
# Bash 3.2 compatible.
|
||||
|
||||
set -e
|
||||
|
||||
EXPORT_NAME="${1:-agent-system}"
|
||||
DATE=$(python3 -c "import datetime; print(datetime.date.today().strftime('%Y-%m-%d'))")
|
||||
OUTPUT_FILE="agent-system-${EXPORT_NAME}-${DATE}.tar.gz"
|
||||
STAGING_DIR="/tmp/agent-export-$$"
|
||||
MANIFEST_FILE="${STAGING_DIR}/MANIFEST.md"
|
||||
|
||||
# Determine project root (directory containing .claude/)
|
||||
PROJECT_ROOT="$(pwd)"
|
||||
if [ ! -d "${PROJECT_ROOT}/.claude" ]; then
|
||||
echo "ERROR: No .claude/ directory found in $(pwd)" >&2
|
||||
echo "Run this script from your project root." >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "[export] Starting export: ${EXPORT_NAME}"
|
||||
echo "[export] Date: ${DATE}"
|
||||
echo "[export] Output: ${OUTPUT_FILE}"
|
||||
|
||||
mkdir -p "${STAGING_DIR}"
|
||||
|
||||
# Collect files — explicit inclusions only
|
||||
collect_files() {
|
||||
local dir="$1"
|
||||
local dest="$2"
|
||||
if [ -d "${PROJECT_ROOT}/${dir}" ]; then
|
||||
mkdir -p "${STAGING_DIR}/${dest}"
|
||||
cp -r "${PROJECT_ROOT}/${dir}/." "${STAGING_DIR}/${dest}/" 2>/dev/null || true
|
||||
echo "[export] Collected: ${dir}"
|
||||
fi
|
||||
}
|
||||
|
||||
collect_files ".claude/agents" ".claude/agents"
|
||||
collect_files ".claude/skills" ".claude/skills"
|
||||
collect_files ".claude/hooks" ".claude/hooks"
|
||||
collect_files "hooks" "hooks"
|
||||
collect_files "automation" "automation"
|
||||
collect_files "scripts" "scripts"
|
||||
|
||||
# Copy settings.json if it exists
|
||||
if [ -f "${PROJECT_ROOT}/.claude/settings.json" ]; then
|
||||
mkdir -p "${STAGING_DIR}/.claude"
|
||||
cp "${PROJECT_ROOT}/.claude/settings.json" "${STAGING_DIR}/.claude/settings.json"
|
||||
echo "[export] Collected: .claude/settings.json"
|
||||
fi
|
||||
|
||||
# Copy CLAUDE.md if it exists
|
||||
if [ -f "${PROJECT_ROOT}/CLAUDE.md" ]; then
|
||||
cp "${PROJECT_ROOT}/CLAUDE.md" "${STAGING_DIR}/CLAUDE.md"
|
||||
echo "[export] Collected: CLAUDE.md"
|
||||
fi
|
||||
|
||||
# Remove excluded files from staging
|
||||
echo "[export] Removing excluded files"
|
||||
rm -f "${STAGING_DIR}/.env" 2>/dev/null || true
|
||||
find "${STAGING_DIR}" -name "*.local.*" -delete 2>/dev/null || true
|
||||
find "${STAGING_DIR}" -name "audit.log" -delete 2>/dev/null || true
|
||||
find "${STAGING_DIR}" -name "cost-events.jsonl" -delete 2>/dev/null || true
|
||||
find "${STAGING_DIR}" -name ".git" -prune -o -print | grep "\.git$" | xargs rm -rf 2>/dev/null || true
|
||||
rm -rf "${STAGING_DIR}/memory" 2>/dev/null || true
|
||||
|
||||
# Generate MANIFEST.md with checksums
|
||||
echo "[export] Generating manifest"
|
||||
|
||||
COMPONENT_ROWS=""
|
||||
find "${STAGING_DIR}" -type f | sort | while read -r fpath; do
|
||||
rel="${fpath#${STAGING_DIR}/}"
|
||||
checksum=$(python3 -c "import hashlib; print(hashlib.sha256(open('${fpath}','rb').read()).hexdigest()[:16])")
|
||||
filetype="other"
|
||||
case "$rel" in
|
||||
.claude/agents/*) filetype="agent" ;;
|
||||
.claude/skills/*) filetype="skill" ;;
|
||||
.claude/hooks/*|hooks/*) filetype="hook" ;;
|
||||
.claude/settings.json) filetype="settings" ;;
|
||||
automation/*) filetype="automation" ;;
|
||||
CLAUDE.md) filetype="context" ;;
|
||||
esac
|
||||
echo "| ${filetype} | ${rel} | ${checksum} |" >> "${MANIFEST_FILE}.rows"
|
||||
done
|
||||
|
||||
cat > "${MANIFEST_FILE}" << MANIFEST
|
||||
# Agent System Manifest
|
||||
Export name: ${EXPORT_NAME}
|
||||
Export date: ${DATE}
|
||||
Generated by: Agent Factory export-system.sh
|
||||
|
||||
## Components
|
||||
|
||||
| Type | File | Checksum (SHA256, first 16) |
|
||||
|------|------|---------------------------|
|
||||
MANIFEST
|
||||
|
||||
if [ -f "${MANIFEST_FILE}.rows" ]; then
|
||||
cat "${MANIFEST_FILE}.rows" >> "${MANIFEST_FILE}"
|
||||
rm "${MANIFEST_FILE}.rows"
|
||||
fi
|
||||
|
||||
cat >> "${MANIFEST_FILE}" << MANIFEST
|
||||
|
||||
## Requirements
|
||||
|
||||
| Requirement | Value |
|
||||
|-------------|-------|
|
||||
| Claude Code version | 1.x or later |
|
||||
| MCP servers | List any required MCP servers here |
|
||||
| Tools | List any required tools (Bash, WebSearch, etc.) |
|
||||
| Environment | List required env vars (ANTHROPIC_API_KEY, etc.) |
|
||||
|
||||
## Notes
|
||||
|
||||
Add any project-specific setup notes here.
|
||||
MANIFEST
|
||||
|
||||
echo "[export] Manifest written"
|
||||
|
||||
# Create tarball
|
||||
cd "${STAGING_DIR}"
|
||||
tar -czf "${PROJECT_ROOT}/${OUTPUT_FILE}" .
|
||||
cd "${PROJECT_ROOT}"
|
||||
|
||||
# Cleanup
|
||||
rm -rf "${STAGING_DIR}"
|
||||
|
||||
echo "[export] Done: ${OUTPUT_FILE}"
|
||||
echo "[export] Size: $(du -sh "${OUTPUT_FILE}" | cut -f1)"
|
||||
147
scripts/templates/transfer/import-system.sh
Normal file
147
scripts/templates/transfer/import-system.sh
Normal file
|
|
@ -0,0 +1,147 @@
|
|||
#!/bin/bash
|
||||
# Agent Factory — import-system.sh
|
||||
# Imports an exported agent system tarball into the current project.
|
||||
# Usage: bash import-system.sh <tarball> [--force]
|
||||
# Bash 3.2 compatible.
|
||||
|
||||
set -e
|
||||
|
||||
TARBALL="$1"
|
||||
FORCE="${2:-}"
|
||||
STAGING_DIR="/tmp/agent-import-$$"
|
||||
|
||||
if [ -z "$TARBALL" ]; then
|
||||
echo "Usage: bash import-system.sh <agent-system-*.tar.gz> [--force]" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ ! -f "$TARBALL" ]; then
|
||||
echo "ERROR: File not found: $TARBALL" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "[import] Importing: $TARBALL"
|
||||
|
||||
mkdir -p "$STAGING_DIR"
|
||||
tar -xzf "$TARBALL" -C "$STAGING_DIR"
|
||||
|
||||
# Read MANIFEST.md
|
||||
MANIFEST="${STAGING_DIR}/MANIFEST.md"
|
||||
if [ ! -f "$MANIFEST" ]; then
|
||||
echo "ERROR: No MANIFEST.md found in tarball — may not be a valid Agent Factory export" >&2
|
||||
rm -rf "$STAGING_DIR"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "[import] Manifest found:"
|
||||
head -5 "$MANIFEST"
|
||||
echo ""
|
||||
|
||||
# Check for conflicts (existing files in destination)
|
||||
CONFLICTS=""
|
||||
find "$STAGING_DIR" -type f | sort | while read -r fpath; do
|
||||
rel="${fpath#${STAGING_DIR}/}"
|
||||
dest="${PWD}/${rel}"
|
||||
if [ -f "$dest" ] && [ "$FORCE" != "--force" ]; then
|
||||
echo "[import] CONFLICT: $rel already exists"
|
||||
CONFLICTS="yes"
|
||||
fi
|
||||
done
|
||||
|
||||
if [ -n "$CONFLICTS" ] && [ "$FORCE" != "--force" ]; then
|
||||
echo ""
|
||||
echo "Conflicts detected. Re-run with --force to overwrite, or remove conflicting files first." >&2
|
||||
rm -rf "$STAGING_DIR"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Extract files to project
|
||||
echo "[import] Extracting files"
|
||||
find "$STAGING_DIR" -type f | sort | while read -r fpath; do
|
||||
rel="${fpath#${STAGING_DIR}/}"
|
||||
dest="${PWD}/${rel}"
|
||||
destdir="$(dirname "$dest")"
|
||||
mkdir -p "$destdir"
|
||||
cp "$fpath" "$dest"
|
||||
echo "[import] Wrote: $rel"
|
||||
done
|
||||
|
||||
# Replace {{PLACEHOLDER}} variables
|
||||
echo "[import] Replacing placeholders"
|
||||
PROJECT_DIR="$(pwd)"
|
||||
PROJECT_NAME="$(basename "$PROJECT_DIR")"
|
||||
|
||||
find "$PROJECT_DIR/.claude" "$PROJECT_DIR/automation" "$PROJECT_DIR/hooks" \
|
||||
"$PROJECT_DIR/CLAUDE.md" -type f 2>/dev/null | while read -r fpath; do
|
||||
case "$fpath" in
|
||||
*.sh|*.md|*.json|*.yml|*.yaml)
|
||||
python3 - "$fpath" "$PROJECT_DIR" "$PROJECT_NAME" << 'PYEOF'
|
||||
import sys, re
|
||||
path, project_dir, project_name = sys.argv[1], sys.argv[2], sys.argv[3]
|
||||
try:
|
||||
with open(path, 'r', encoding='utf-8') as f:
|
||||
content = f.read()
|
||||
content = content.replace('{{PROJECT_DIR}}', project_dir)
|
||||
content = content.replace('{{PROJECT_NAME}}', project_name)
|
||||
with open(path, 'w', encoding='utf-8') as f:
|
||||
f.write(content)
|
||||
except Exception:
|
||||
pass
|
||||
PYEOF
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
# Make .sh files executable
|
||||
echo "[import] Setting executable permissions"
|
||||
find "$PROJECT_DIR/.claude/hooks" "$PROJECT_DIR/hooks" "$PROJECT_DIR/automation" \
|
||||
-name "*.sh" -type f 2>/dev/null | while read -r fpath; do
|
||||
chmod +x "$fpath"
|
||||
echo "[import] chmod +x: $fpath"
|
||||
done
|
||||
|
||||
# Validate frontmatter in agent files
|
||||
echo "[import] Validating agent frontmatter"
|
||||
INVALID_AGENTS=""
|
||||
if [ -d "$PROJECT_DIR/.claude/agents" ]; then
|
||||
for agent in "$PROJECT_DIR/.claude/agents"/*.md; do
|
||||
[ -f "$agent" ] || continue
|
||||
python3 - "$agent" << 'PYEOF'
|
||||
import sys, re
|
||||
path = sys.argv[1]
|
||||
try:
|
||||
with open(path, 'r') as f:
|
||||
content = f.read()
|
||||
if not content.startswith('---'):
|
||||
print(f"WARN: {path} missing YAML frontmatter")
|
||||
sys.exit(0)
|
||||
parts = content.split('---', 2)
|
||||
if len(parts) < 3:
|
||||
print(f"WARN: {path} malformed frontmatter")
|
||||
except Exception as e:
|
||||
print(f"WARN: {path} could not be validated: {e}")
|
||||
PYEOF
|
||||
done
|
||||
fi
|
||||
|
||||
# Validate bash syntax on hook scripts
|
||||
echo "[import] Validating hook syntax"
|
||||
if [ -d "$PROJECT_DIR/.claude/hooks" ]; then
|
||||
for script in "$PROJECT_DIR/.claude/hooks"/*.sh; do
|
||||
[ -f "$script" ] || continue
|
||||
if bash -n "$script" 2>/dev/null; then
|
||||
echo "[import] OK: $script"
|
||||
else
|
||||
echo "[import] WARN: $script failed bash -n check"
|
||||
fi
|
||||
done
|
||||
fi
|
||||
|
||||
rm -rf "$STAGING_DIR"
|
||||
|
||||
echo ""
|
||||
echo "[import] Import complete."
|
||||
echo "[import] Next steps:"
|
||||
echo " 1. Review CLAUDE.md and update project-specific sections"
|
||||
echo " 2. Add your ANTHROPIC_API_KEY to .env"
|
||||
echo " 3. Run /agent-factory:status to verify the system"
|
||||
Loading…
Add table
Add a link
Reference in a new issue