pal-e-docs

Agent Spawn Conventions

agent-spawn-conventions Convention

active convention pal-e-docs agent
Project

Agent Spawn Conventions

Rules for spawning subagents in the DORA Elite AI Enterprise. The information boundary is sacred: management layer (Ava, Dottie) sees pal-e-docs + Forgejo. Execution layer (Dev, QA) sees repos + Forgejo only. The Forgejo issue is the contract between the two layers.

The Axiom

No issue, no agent.
Every spawned agent must trace to a Forgejo issue on a project board. A Forgejo issue URL or issue number must appear in the spawn prompt. The Forgejo issue IS the spec — it contains user story, file targets, acceptance criteria, and constraints. See convention-kanban-over-plans.

Work Path: Board-Driven

Path Flow When
Board-driven <code>Forgejo issue → board (backlog → todo → next_up) → agent → PR</code> All work: features, bugs, spikes, tasks
Agents exist to preserve main session context. Every agent spawn costs ~100 tokens for the prompt but saves thousands by offloading work that would pollute Ava's conversation. The question is not "can I do this myself" but "will doing this myself burn context I need later?"

Five Agents

Agent Domain Can do Cannot do
**Ava** pal-e-docs + Forgejo + Woodpecker Manage boards, create issues, spawn agents, track lifecycle, update docs Write code in repos
**Penny** Gmail, GCal, LinkedIn, Notion Send emails, manage calendar, post social, query external KBs. Defined in pal-e-docs but not yet wired (no claude-custom config). Code, docs, repos
**Dev** Repos + Forgejo Read Forgejo issue, write code across all domains (frontend, backend, infra). Impeccable skills for frontend, tofu enforcement for infra, ruff for Python. Model decides what expertise is relevant. Access pal-e-docs. Write or modify notes.
**QA** Repos + Forgejo Read PR diff, read repo code, post domain-expert review with process observations. Dynamic expertise across frontend (a11y, responsive, UX), backend (PEP, OWASP, SQLAlchemy), and infra (Terraform, k8s, ArgoCD). Explicit BLOCKER criteria. Access pal-e-docs. Write code. Merge.
**Dottie** pal-e-docs (delegated by Ava) Execute doc updates, content audits, bulk cleanup under Ava's direction Write code. Create/close Forgejo issues. Make strategic decisions.
Only Ava, Dottie, and Lucas touch docs. Dev and QA are repo-only. No exceptions. Dev handles all code domains (frontend, backend, infra) — the model applies the right expertise dynamically. QA reviews all PR types with dynamic domain expertise. The trust is in the model, not in domain-gated agent configs.

The Minimal Prompt Pattern

Agent prompts should be ~100 tokens, not 3-4KB. The Forgejo issue is the spec. The prompt is a pointer.
Why this works: The Forgejo issue contains everything the agent needs — user story, file targets, acceptance criteria, test expectations, constraints. The agent reads the issue via Forgejo MCP or curl.

Agent Access Scope

Resource Ava Penny Dev QA Dottie
Forgejo issues Yes <strong>No</strong> Yes Yes Read-only
Repo codebase Read-only <strong>No</strong> Yes Yes (read-only) <strong>No</strong>
PR diffs Yes <strong>No</strong> Yes Yes <strong>No</strong>
pal-e-docs notes Yes (read/write) <strong>No</strong> <strong>No</strong> <strong>No</strong> Yes (read/write)
Gmail / GCal <strong>No</strong> Yes <strong>No</strong> <strong>No</strong> <strong>No</strong>
LinkedIn / Notion <strong>No</strong> Yes <strong>No</strong> <strong>No</strong> <strong>No</strong>

Required in Every Spawn Prompt

Element Why
<strong>Forgejo issue number</strong> The agent reads this for its complete spec. Required for ALL work.
<strong>Repo (owner/name)</strong> Where the code lives
<strong>Forgejo issue URL</strong> Traceability. The Forgejo issue is the single source of truth for scope.
<strong>Boundary statement</strong> Explicitly state: no pal-e-docs access

When to Spawn Each Agent

Agents exist to preserve main session context. Every agent spawn costs ~100 tokens for the prompt but saves thousands by offloading work that would pollute Ava's conversation. The question is not "can I do this myself" but "will doing this myself burn context I need later?"
Situation Agent Why
Code change needed (any repo, any domain) Dev Worktree isolation protects main. Agent reads Forgejo issue, writes code, opens PR. ~100 token prompt. Handles frontend, backend, and infra — model applies the right expertise.
PR needs review (any domain) QA Fresh context catches things Ava would miss after a long session. Dynamic domain expertise (frontend, backend, infra). Structured review format with explicit BLOCKER criteria.
Bulk doc updates (5+ notes, audits, tag cleanup) Dottie Keeps main session clean. Dottie's precise prompt style (~450 tokens) beats Ava doing it manually. Spawn early in session.
Single surgical doc edit (1-2 blocks) Ava directly Not worth the spawn overhead. Use update_block directly.
Issue creation, board management Ava directly Strategic decisions stay in main session. Lucas needs to see and approve these.
External comms (email, calendar, social, KB queries) Penny Isolates external API interactions from main session. Not yet wired in claude-custom — config pending.
Research / codebase exploration Explore agent Protects context window from large search results. Use for broad searches (>3 queries).

Pre-Spawn Checklist

Before spawning a Dev or QA agent:
  • Fetch + pull main — git fetch <remote> && git pull <remote> main. Claude Code's isolation: worktree branches from local HEAD. Stale main = stale worktree. (Incident: 2026-03-06, 40K+ tokens wasted)
  • Forgejo issue exists — the issue IS the spec. Create it first via mcp__forgejo__create_issue.
  • Board item exists — traceability. The Forgejo issue must be linked to a board item.
  • Boundary statement in prompt — explicitly state: no pal-e-docs access (for Dev/QA) or no code writes (for Dottie).

Enforcement

What How
Forgejo issue required <code>check-agent-spawn.sh</code> (PreToolUse) blocks Dev agent without Forgejo issue reference
Dev can't write docs <code>pal-e-docs</code> removed from dev.md mcpServers — tools don't exist in agent context
QA can't write docs <code>pal-e-docs</code> removed from qa.md mcpServers — tools don't exist in agent context
QA can't write code <code>disallowedTools: Write, Edit, Bash</code> + PreToolUse hook
Dottie can't write code Frontmatter hooks block code writes (Write/Edit/Bash on repos). <code>general-purpose</code> subagent type.

Deprecated

  • Plan notes (plan-*) — deprecated 2026-03-26. Plans replaced by kanban boards + architecture diagrams + user stories. See convention-kanban-over-plans. Existing plan notes preserved as historical artifacts.
  • issue-creator agent — removed 2026-03-02. Ava creates issues directly. The middleman added tokens and a round trip without value.
  • pal-e-docs issue notes — removed 2026-03-02. Issues live in Forgejo only. See issue-as-spec pattern.
  • pal-e-docs repo page notes — repo pages are READMEs in the repos. Not pal-e-docs notes.
  • Specialized Dev/QA agents (6 notes) — deprecated 2026-03-16. pal-e-agency Phase 12 tried splitting Dev into Dev-Frontend, Dev-Backend, DevOps and QA into Frontend-QA, Dev-QA, DevOps-QA. Consolidated back to single Dev + single QA. The model applies domain expertise dynamically — domain-gated configs added friction without value. See: agent-dev-frontend, agent-dev-backend, agent-devops, agent-frontend-qa, agent-dev-qa, agent-devops-qa (all status=deprecated).
  • agent-workflow — the operating model for the DORA Elite AI Enterprise
  • plan-pal-e-agency — A DORA Elite AI Enterprise Operating Model
  • project-pal-e-agency — project page with architecture diagrams
  • template-issue — the Forgejo issue template
  • pr-lifecycle — the 7-stage PR flow