pal-e-docs

Project: pal-e-agency

project-pal-e-agency Project Page

active project-page
Project

pal-e-agency

Vision

The process pillar of a DORA Elite AI Enterprise. pal-e-agency defines how work moves through the system: the scoping pipeline (projects → boards → Forgejo issues → agents), agent dispatch and containment, SOPs, conventions, templates, and the tooling (MCP servers, SDKs) that agents use to execute. In the three-pillar model (platform=DevOps/SRE, docs=product, agency=process+enforcement), agency is the layer that turns documentation into deterministic execution. Management owns the process; agents own the implementation. The system produces elite delivery performance not through agent autonomy, but through a scoping pipeline so clean that well-contained agents can execute without needing broader context.

User Stories

Who uses the agency system, what they need, and how we measure success. Organized by role hierarchy (see glossary). The agency's "users" are internal — the superuser managing the platform, and the agents executing work.
Role Story Success Metric story:X key
<strong>Superuser</strong> (Lucas) I can scope, dispatch, and track all work across all projects from one Claude Code session. When I point at a project, the right context loads. When I merge, docs update automatically. When QA finds nits, they flow through the kanban. All board items traceable (story:X + arch:Y). Zero stale project pages after merge. /update-docs produces audit trail. <code>story:superuser-manage</code>
<strong>Superuser</strong> (Lucas) I can onboard a new project and the full process infrastructure (board, templates, hooks) works immediately without custom setup. New project page passes template hook. Board syncs issues. Issue templates validate. <code>story:superuser-onboard</code>
<strong>PM</strong> (Ava) I can triage boards, scope work into issues, dispatch agents, and run /update-docs without ambiguity. Every SOP tells me exactly what to do. Zero steps skipped in /update-docs. Scoping chain complete before dispatch. Nits tracked as nit-bundle issues. <code>story:pm-scope</code>
<strong>Dev agent</strong> I receive a well-scoped Forgejo issue with User Story, File Targets, Acceptance Criteria, and Test Expectations. I write code, create a PR, and nothing else. Agent prompt ≤100 tokens. PR passes QA on first review >70% of the time. <code>story:dev-execute</code>
<strong>QA agent</strong> I receive a PR diff and parent issue. I review for correctness and SOP compliance. I post a verdict with nits clearly separated from blockers. Zero false approvals (missed blockers). Nits properly categorized as non-blocking. <code>story:qa-review</code>
<strong>Validation agent</strong> I receive a merged PR and its acceptance criteria. I validate the deployed result matches the spec. I report PASS/PARTIAL/FAIL with evidence. Zero unvalidated merges in production. Evidence for every validation. <code>story:validation-execute</code>
<strong>Dottie</strong> I receive targeted doc update instructions from Ava. I update blocks surgically without rewriting unrelated content. I maintain note taxonomy consistency. Block-level updates only (no full note rewrites). Zero orphaned links. <code>story:dottie-docs</code>

How to Operate

This is the operating sequence for a new session. Each step links to the governing SOP.
  • Open a session. Ava (injected from claude-custom/agents/ava.md) auto-syncs boards and checks for blockers. See agent-workflow.
  • Check the board. list_board_items(board_slug="board-pal-e-agency") — items in next_up or todo are ready to work. See sop-board-workflow.
  • Pick a ticket. Move a board item to in_progress. The ticket is a Forgejo issue with file targets, acceptance criteria, and constraints.
  • Spawn an agent. Every dev agent needs a Forgejo issue reference in the prompt. Agents clone to /tmp/ for isolation. See agent-spawn-conventions.
  • Review the PR. QA agent reviews, posts findings. Review-fix loop until approved. See pr-lifecycle and pr-review-loop.
  • Merge. Only with explicit user approval. Run /update-docs after every merge. See sop-post-merge-docs.
  • Validate. Post-merge validation confirms the change works in production. See sop-validation.
Key SOPs: agent-workflow (operating model), agent-spawn-conventions (no issue, no agent), sop-board-workflow (kanban flow), pr-lifecycle (PR creation through merge), pr-review-loop (review-fix cycle), sop-claude-config-development (claude-custom changes), sop-post-merge-docs (post-merge chain), sop-validation (production validation).
Key conventions: convention-kanban-over-plans (plans deprecated, boards are the work tracker), agent-spawn-conventions (agent type capabilities and isolation rules), convention-claude-no-enforce (escape hatch for frontend iteration).
Historical note: Plans were the original scoping mechanism (Feb–Mar 2026). Deprecated on 2026-03-26 per convention-kanban-over-plans. Replaced by kanban boards + architecture diagrams + user stories. 12 legacy plan notes exist with status completed and tag deprecated.

Board

board-pal-e-agency — Pal E Agency Board. Permanent kanban. Columns: Backlog → Todo → Next Up → In Progress → Done.

Status

As of 2026-06-11:
  • Core workflow: Fully operational. Issue → agent → PR → QA → merge pipeline runs daily.
  • 19 repos: claude-custom (core), 5 MCP integration triplets (Gmail, Notion, GCal, LinkedIn, Woodpecker), forgejo-mcp/sdk, mcp-remote-auth, gcal-scheduler.
  • 5 agents: Ava (coordinator), Penny (comms), Dev (enhanced — all domains), QA (enhanced — generic + dynamic domain), Dottie (docs).
  • Enforcement: Hook surface covers agent spawn, issue validation, PR template, merge gate, cross-repo isolation. See hook-catalog.
  • MCP integrations: Forgejo, Gmail, Notion, Woodpecker operational. GCal, LinkedIn partially wired.
  • Board-driven workflow: Plans deprecated 2026-03-26. All work tracked on board-pal-e-agency kanban.
  • Known gaps: arch-domain-pal-e-agency still references 'Betty Sue' (renamed to Ava 2026-03-28). No deployment architecture note yet.

Architecture

The DORA Elite AI Enterprise has two layers separated by a strict information boundary:
Scoping pipeline: Projects → Boards → Forgejo Issues → Dev/QA agents. The issue is the handoff point. By the time a dev agent sees it, all context, scope, and acceptance criteria are baked in. The agent doesn't need to know why — just the spec. Work enters the board from user stories and architecture decisions, flows through the kanban columns (backlog → todo → next_up → in_progress → done), and converges at the Forgejo issue. See agent-workflow.
Enforcement architecture (34 hooks in claude-custom):
Layer Mechanism Hook Count What it does
1. Block PreToolUse hooks 15 Hard stops — reject non-compliant actions before they execute. Spawn gate, main branch protection, merge guards, template validation.
2. Auto-format PreToolUse hooks 2 Fix compliance automatically — ruff format on commit, no human intervention.
3. Auto-label PostToolUse hooks 3 Advance workflow state machine — issue labels transition automatically on branch, PR, verdict.
4. Remind PostToolUse hooks 4 Nudge downstream obligations — review loop, update-docs, board sync.
5. Context inject SessionStart + SubagentStart 5 Inject personality, SOPs, board context, MCP health checks at session/agent open.
6. Agent containment disallowedTools + frontmatter hooks per-agent Strip tools from agent palette (QA: no Write/Edit/Bash). Enforce information boundary.
Workflow state machine (automated by PostToolUse label hooks):
Enterprise pillar boundaries: Agency owns both the process and the enforcement (SOPs, conventions, agent definitions, scoping pipeline, hooks, frontmatter restrictions, settings). Platform owns the infrastructure (DevOps, SRE, observability — proves the DORA numbers). Docs owns the product (knowledge system, boards, note taxonomy). Together, the three pillars form the DORA Elite AI Enterprise.
Three proof pillars: SRE observability (deployment frequency, lead time, failure rate, MTTR — the DORA numbers). Value stream tracking (idea-to-production traceability via boards and issues). Enforcement architecture (hooks make compliance deterministic — conventions → SOPs → hooks, where the hook is the teeth). See dora-framework for the full SOP→metric mapping.

Repos

Repo Platform Role Status
claude-custom Forgejo Hooks, skills, agent configs Active
forgejo-mcp / forgejo-sdk Forgejo Forgejo API pair Active
gmail-sdk / gmail-mcp / gmail-mcp-remote Forgejo Gmail triple Active
gcal-sdk / gcal-mcp / gcal-mcp-remote / gcal-scheduler Forgejo Google Calendar quad Active
linkedin-sdk / linkedin-mcp-scheduler / linkedin-scheduler-remote Forgejo LinkedIn triple Active
notion-sdk / notion-mcp / notion-mcp-remote Forgejo Notion triple Active
woodpecker-sdk / woodpecker-mcp Forgejo Woodpecker CI pair Active
mcp-remote-auth Forgejo Shared OAuth library Active

Inbox

Untriaged items. Check the board for current work: list_board_items(board_slug="board-pal-e-agency").
Item Summary Status
<code>arch-domain-pal-e-agency</code> Org chart still references 'Betty Sue' — needs Ava rename Open
Deployment architecture note No <code>arch-deployment-pal-e-agency</code> note exists yet Open
Query: list_notes(project="pal-e-agency", note_type="todo", status="open") — filter for null parent_slug.