Handbook

Agents blueprint (automation)

This folder is a reusable, product-agnostic package for engineering automation: foundational Docker images, Compose patterns, and templates for isolated, repeatable jobs (shell scripts, browser runners, optional LLM tool…

Governance: read Blueprint policy — do not change casually — do not change this directory unless explicitly updating the baseline. Project automation lives in agents/ (mutable) at repository root when you adopt this blueprint.

Deliverable Purpose
Blueprint policy — do not change casually Immutability rules for this blueprint.
Agents blueprint — structure & layers Layers (conceptual → Docker → recipes → CI), security, adoption.
Orchestration — new agent / recipe Canonical steps to create recipes under agents/; assistants and Cursor rules should point here.
docker/ Foundational Dockerfile.base, compose.yaml, ignore rules.
templates/ Recipe stub and mutable agents/ workspace seed.
scripts/ init-agents-workspace.sh, new-agent-recipe.sh — see scripts/README.md.
docs/ Maintainer notes for handbook generation (website/agents--*.html via generator/build-handbook.py).

What does not belong here

  • API keys, tokens, .env with secrets, or project-specific URLs — use agents/ (gitignored patterns) and CI secret stores.
  • Application source code — stays in your product tree (app/, src/, etc.).
  • Frozen SDLC text — blueprints/sdlc/ only.

How to adopt

  1. Keep this folder at repository root as blueprints/agents/ (or copy the subtree).
  2. Add agents/ (mutable): run ./blueprints/agents/scripts/init-agents-workspace.sh from repo root, or copy Mutable `agents/` workspace (seed) manually.
  3. New recipes: follow Orchestration — new agent / recipe; scaffold with ./blueprints/agents/scripts/new-agent-recipe.sh <name> [--purpose "..."].
  4. From docs/INDEX.md (or root README.md) and blueprints/sdlc/README.md, link to blueprints/agents/README.md.
  5. Handbook (browser): generated under blueprints/website/ (e.g. agents--index.html) by generator/build-handbook.py; canonical Markdown: Agents blueprint — structure & layers, Documentation structure — proposal.
  6. Build images: docker compose -f blueprints/agents/docker/compose.yaml build (from repo root) for agent-base; add agent-playwright when running browser/Electron jobs in Linux containers (Docker — foundational files).

Blueprint — no project-specific content.