pal-e-docs

Plan: Agent Profiles & Phase Execution

plan-2026-02-25-agent-profiles Plan

plan completed
Project

Plan: Agent Profiles & Phase Execution

Vision

pal-e-docs is the development operating system. Agents are defined roles with explicit skills, MCP tool inventories, and SOP assignments. Every phase is assigned to an agent type. Hooks enforce the assignment. The chain is unbroken: project → plan → phase → agent → issue → PR.

Projects & Repos Touched

Project/Repo Platform Role in this plan
pal-e-docs (notes) Forgejo Agent profiles, skill notes, template updates, SOP audit
pal-e-docs (API) Forgejo Slug rename feature (PR #24, #25)
pal-e-docs-mcp Forgejo new_slug parameter (PR #2)
claude-custom Forgejo Skill files, upgrade spawn hook, add SubagentStart hook, repo cleanup

Context

What's done:
  • 5-layer paradigm documented (agent-paradigm): Events → Hooks → MCP → Skills → Agents
  • Separation of concerns established (sop-agent-workflow): main session = docs, agents = repos
  • check-agent-spawn.sh enforces plan- slug in spawn prompts
  • Template enforcement hooks deployed — deny works, ask doesn't for subagents
  • 8 active SOPs, but agent types are informal (mentioned but not defined or enforced)
  • 4 MCP servers: pal-e-docs (14 tools), forgejo (12 tools), playwright, notion

Previous Plan

plan-2026-02-25-template-enforcement (completed)

Depends On

None.

Decisions Made

Decision Rationale
Agent profiles live in pal-e-docs notes, not <code>.claude/agents/</code> <code>.claude/</code> stays thin. SubagentStart hook injects profile from docs. Single source of truth.
Skills live in pal-e-docs notes with explicit MCP tool lists No assumptions. Agent is accountable to listed tools. <code>### MCP Tools</code> section required.
Skill files in <code>~/.claude/skills/</code> are thin pointers to pal-e-docs notes User-invokable via <code>/name</code>. Content lives in pal-e-docs. SKILL.md is 5-10 lines.
Phase slugs: <code>phase-{plan-date}-{n}-{description}</code> Traceability. Phase slug encodes its parent plan.
Three agent types: Dev, QA, Issue Creator Issue Creator provides fresh eyes on plan→issue translation. Ensures template compliance before Dev starts.
Flow: plan phase → Issue Creator → user reviews → Dev Agent → QA Agent Issues created just-in-time for next-up phase, not all at once. Reduces garbage.
<code>deny</code> for all enforcement hooks Proven: <code>ask</code> silently ignored by subagents.
MCP tool discovery is automatic, but skills list tools explicitly MCP servers tell the AI what's available. Skills tell the agent what to USE and in what order.
QA agent checks SOP compliance, not just code quality Closes the loop: Dev follows SOP, QA verifies SOP was followed.
claude-custom uses worktrees + symlink swap for testing Same <code>.worktrees/</code> pattern as every other repo. Symlink swap to test live.
pal-e-docs and Claude Config co-arise Cross-referenced on project pages. Brain (knowledge) and nervous system (behavior).
All SOP slugs use <code>sop-</code> prefix Consistent with all other note type prefixes (plan-, template-, agent-, skill-, project-).
Global SOPs have no project association SOPs are cross-cutting. Project-specific SOPs keep their project but are the exception.

Phases

Phase 1: Define agent profiles + audit SOP coverage ✓

Slug: phase-2026-02-25-1-agent-profiles
Owner: Main session
Status: Complete
Deliverables: agent-dev, agent-qa, agent-issue-creator, template-agent, sop-index (updated)

Phase 2: Define skills as notes with MCP tool inventories ✓

Slug: phase-2026-02-25-2-skill-notes
Owner: Main session
Status: Complete
Deliverables: skill-create-issue, skill-implement-phase, skill-review-pr, skill-fix-review, template-skill, 4 SKILL.md files in ~/.claude/skills/, project-pal-e-docs and project-claude-config cross-referenced

Phase 3: Introduce phase slugs ✓

Slug: phase-2026-02-25-3-phase-slugs
Owner: Main session
Status: Complete
Deliverables: template-plan (updated with phase slug + owner + deliverables requirements)

Phase 3.5: Clean up claude-custom repo and establish development SOP — IN PROGRESS

Slug: phase-2026-02-25-3.5-claude-custom-cleanup
Owner: Main session + Dev Agent
Status: In progress — SOP renames pending deployment
Completed:
  • ✓ Created sop-claude-config-development note
  • ✓ Triaged uncommitted changes
  • ✓ Added .gitignore for artifacts (PR #31 merged on claude-custom)
  • ✓ Got working tree clean on main (PR #31 merged, stashes dropped)
  • ✓ Cleaned up stale branches (12 local branches deleted, worktrees removed)
  • ✓ Added slug rename feature to pal-e-docs API (PR #24) and MCP (PR #2)
  • ✓ Fixed ruff format CI failure (PR #25)
Remaining:
  • Wait for CI to build new pal-e-docs image with slug rename feature
  • Rename 7 SOP slugs to sop- prefix (attempted, blocked by old deployed image)
  • Update all references: sop-index, agent profiles, skill notes, plan notes, hook scripts, CLAUDE.md, MEMORY.md
  • Update sop-worktree-workflow content — add post-merge cleanup steps, "main is default branch" rule
  • Update sop-claude-config-development — remove duplicate worktree basics, reference shared SOP
  • Move global SOPs to no project association
Deliverables so far: sop-claude-config-development, PR #31 (claude-custom), PR #24/#25 (pal-e-docs API), PR #2 (pal-e-docs-mcp), issue #30 (claude-custom), issue #23 (pal-e-docs)

Phase 4: Upgrade spawn hook

Slug: phase-2026-02-25-4-spawn-hook
Goal: PreToolUse on Task requires plan slug + agent slug. Phase slug recommended.
Owner: Dev Agent

Phase 5: Add SubagentStart hook

Slug: phase-2026-02-25-5-subagent-start
Goal: Inject agent profile as context when subagent spawns.
Owner: Dev Agent

Verification

  • [x] agent-dev, agent-qa, agent-issue-creator notes exist with SOPs, MCP tools, constraints
  • [x] Every active SOP mapped to at least one agent profile
  • [x] Skill notes list every MCP tool used
  • [x] Thin SKILL.md files in ~/.claude/skills/ point to pal-e-docs notes
  • [x] Phase slugs on this plan (dogfooding)
  • [x] template-plan updated with phase slug + deliverables requirement
  • [x] template-skill created
  • [x] claude-custom repo clean on main with development SOP
  • [x] Slug rename feature added to API and MCP
  • [ ] SOP slugs renamed to sop- prefix (blocked on deployment)
  • [ ] All references updated (notes, hooks, CLAUDE.md)
  • [ ] Spawn hook blocks prompts missing agent slug
  • [ ] SubagentStart hook injects agent profile as context
  • [ ] End-to-end: Issue Creator proposes → Dev Agent implements → QA Agent reviews

Next Plan Seeds

  • Slug format validation (Pydantic regex on NoteCreate/NoteUpdate)
  • Default branch = main convention (Forgejo server setting)
  • More agent types (Ops Agent for infra, Research Agent for exploration)
  • Agent-specific permissions (Dev auto-allowed Write, QA read-only)
  • /assign-phase skill for the full spawn workflow
  • Phase completion tracking (status tags on phase notes?)
  • Multi-repo issues — separate issues per repo when work spans repos
  • plan-2026-02-25-template-enforcement — completed, proved deny > ask
  • plan-2026-02-24-docs-foundation — parent plan lineage
  • agent-paradigm — 5-layer model
  • sop-agent-workflow — separation of concerns (pending rename)
  • agent-spawn-conventions — current spawn rules (to be upgraded)
  • sop-index — updated with agent mapping, skills, templates