project-page active pal-e-agency
project-pal-e-agency updated 2026-04-04

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 → plans → phases → kanban items → issues), 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. Proven through three pillars: SRE observability (deployment metrics), value stream tracking (idea-to-production traceability), and enforcement architecture (hooks that make compliance deterministic, not aspirational).

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
Superuser (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 + phase). Zero stale project pages after merge. /update-docs produces 10-step audit trail. story:superuser-manage
Superuser (Lucas) I can onboard a new project and the full process infrastructure (board, plan, templates, hooks) works immediately without custom setup. New project page passes template hook. Board auto-syncs phases. Issue templates validate. story:superuser-onboard
PM (Ava) I can triage boards, scope work into plans/phases/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. story:pm-scope
Dev agent 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. story:dev-execute
QA agent 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. story:qa-review
Validation agent I receive a merged PR and its acceptance criteria. I log in as each relevant role via Playwright, navigate the deployed UI, take screenshots, and validate the user experience matches the spec. I report PASS/PARTIAL/FAIL with visual evidence. Zero unvalidated merges in production. Screenshot evidence for every validation. Role-specific validation catches what code review cannot. story:validation-execute
Dottie 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. story:dottie-docs

Plan

Active: plan-pal-e-agency — A DORA Elite AI Enterprise Operating Model. 8 phases (6 completed, 2 remaining). Scoping pipeline, agent containment, enforcement architecture, value stream tracking.

Completed:

  • plan-2026-02-24-sop-enforcement — SOP Enforcement via Hooks
  • plan-2026-02-24-enforcement-unification — pal-e-docs as Development Operating System
  • plan-2026-02-25-template-enforcement — Template Enforcement Hooks
  • plan-2026-02-25-agent-profiles — Agent Profiles & Phase Execution
  • plan-2026-02-28-woodpecker-sdk-mcp — Woodpecker SDK & MCP
  • plan-2026-02-28-agent-skill-frontmatter — Agent & Skill Frontmatter Fix
  • plan-2026-03-01-forgejo-pypi-migration — Forgejo PyPI Migration
  • plan-2026-03-07-note-hierarchy-conventions — Note Hierarchy Conventions

Deferred:

  • plan-2026-02-28-woodpecker-mcp — Woodpecker MCP Server
  • plan-2026-03-09-template-rendering — Server-Side Template Rendering (phases 1-2 done)

Board

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

Status

As of 2026-03-27:

  • 19 repos: MCP servers (gmail, gcal, linkedin, notion, forgejo, woodpecker), their SDKs, remote services, claude-custom, mcp-remote-auth
  • 14 SOPs (9 active + 5 recovery), 17+ conventions, 10 templates (9 active + 1 deprecated), 6 skills — all active
  • 5 agents: Ava (coordinator), Penny (comms), Dev (enhanced — all domains), QA (enhanced — generic + dynamic domain), Dottie (docs).
  • Hook enforcement live: 34 scripts across 6 layers (block, auto-format, auto-label, remind, context-inject, containment). See hook-catalog.
  • Context-scoped session loading LIVE — session startup detects project from git remote via /repos/{name} endpoint, scopes plan TOCs, dynamic briefing, and board items to detected project. Fail-open to cross-project when undetected.
  • 4 issue types: Feature, Bug, Spike, Nit-Bundle. Hook-enforced via check-issue-template.sh. See glossary for definitions.
  • 6 error recovery SOPs active: CI pipeline, deploy, hook block, MCP server, PR rejection, DB migration.
  • Platform glossary: glossary note — canonical definitions for Enterprise, Role Hierarchy, User Story, Traceability Triangle, Scoping Pipeline, Three Pillars, Continuous Kanban, Nit, Issue Types.
  • Plan: Phases 18-20 COMPLETED this session. 18: glossary + nit-bundle + update-docs alignment. 19: user stories on all 5 project pages (44 stories). 20: context-scoped session loading.
  • Key artifacts: hook-catalog (34 hooks), glossary (platform vocabulary), sop-board-workflow (continuous kanban), arch-domain-pal-e-agency (org chart).
  • PR #226 merged 2026-03-27: 4 new NoteTypes (review, architecture, validation, user-story) + validation BoardColumn added to pal-e-api. Forgejo issue #223 closed. Cross-pillar impact: pal-e-docs-mcp server needs restart to pick up new enum values from the API schema. Until restarted, new types are in the DB but not available via MCP tools.

Architecture

The DORA Elite AI Enterprise has two layers separated by a strict information boundary:


┌─────────────────────────────────────────────────────────────────┐
│  MANAGEMENT LAYER (pal-e-docs + Forgejo)                       │
│  Sees: projects, plans, phases, boards, SOPs, conventions      │
│                                                                 │
│  Lucas (human) ─── decides what to build                       │
│    └─ Ava (main session) ─── scopes, dispatches, tracks        │
│         └─ Dottie (doc librarian) ─── maintains knowledge base │
├─────────────────────────────────────────────────────────────────┤
│  ▼ HANDOFF: Forgejo Issue (the contract)                       │
│    - All context, scope, acceptance criteria baked in           │
│    - Agent doesn't need to know WHY — just the spec            │
├─────────────────────────────────────────────────────────────────┤
│  EXECUTION LAYER (repos + Forgejo only)                        │
│  Sees: issue spec, repo code, PR diff — nothing else           │
│                                                                 │
│  Dev (code writer) ─── reads issue, writes code, opens PR      │
│  QA (reviewer) ─────── reads PR diff, posts verdict            │
└─────────────────────────────────────────────────────────────────┘

Scoping pipeline: Projects → Plans → Phases → Kanban items → 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. Two entry points: Feature Work (plan → phase → issue) and Lightweight Work (TODO → issue). Both converge 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, plan 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):


Forgejo Issue Lifecycle (labels set automatically by hooks):

  new ──▶ in-progress ──▶ qa ──▶ approved ──▶ merged ──▶ deployed
           │                      │                        │
           │ create_issue_and_    │ comment_on_pr           │ CI apply success
           │ branch (Dev)         │ VERDICT: APPROVED       │ (Woodpecker)
           │                      │                        │
           │              ┌───────┘                 deploy-failed
           │              ▼                                │
           │         needs-fix ──▶ qa (re-review)          │ CI apply failure
           │              │                                │
           │              │ comment_on_pr                   │
           │              │ VERDICT: NOT APPROVED           ▼
           │              │                         sop-ci-pipeline-
           │              └── Dev dispatched with    recovery
           │                  rework instructions
           │
           └── submit_pr (Dev) sets status:qa

Hook triggers:
  create_issue_and_branch  → label-on-branch.sh  → status:in-progress
  submit_pr                → label-on-pr.sh      → status:qa
  comment_on_pr (APPROVED) → label-on-verdict.sh → status:approved
  comment_on_pr (NOT APPROVED) → label-on-verdict.sh → status:needs-fix
  merge_approved_pr        → remind-update-docs.sh → /update-docs prompt

Post-merge (CI-enabled repos like pal-e-platform):
  merged → deployed        (on Woodpecker CI apply success)
  merged → deploy-failed   (on Woodpecker CI apply failure → sop-ci-pipeline-recovery)

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.


                    DORA Elite AI Enterprise
    ┌─────────────────────────────────────────────────────┐
    │                                                     │
    │   ┌───────────┐  ┌───────────┐  ┌───────────────┐  │
    │   │ PLATFORM  │  │   DOCS    │  │    AGENCY     │  │
    │   │ (DevOps/  │  │ (Product) │  │  (Process +   │  │
    │   │  SRE)     │  │           │  │ Enforcement)  │  │
    │   │           │  │ pal-e-docs│  │               │  │
    │   │ k3s, CI,  │  │ knowledge,│  │ SOPs, agents, │  │
    │   │ observ-   │  │ boards,   │  │ scoping,      │  │
    │   │ ability   │  │ taxonomy  │  │ hooks, config │  │
    │   └─────┬─────┘  └─────┬─────┘  └───────┬───────┘  │
    │         │              │                 │          │
    │      PROVES          TRACKS           DEFINES +    │
    │     the DORA        the value        ENFORCES      │
    │     numbers         stream           the process   │
    │     (DF/MTTR)        (LT)             (CFR)        │
    │                                                     │
    └─────────────────────────────────────────────────────┘

  Enforcement pyramid (conventions → SOPs → hooks):

    ┌─────────────┐
    │    HOOKS    │  ← the teeth (code rejects non-compliance)
    ├─────────────┤
    │    SOPs     │  ← step-by-step procedures
    ├─────────────┤
    │ CONVENTIONS │  ← agreed patterns and rules
    └─────────────┘

  Feedback loop (cross-pillar triggers):

    PLATFORM ──PROVES──▶ AGENCY ◀──TRACKS── DOCS
        ▲                   │
        │                   │
        └───TRIGGERS────────┘
             review

  Convention→hook feedback is internal to Agency.
  See convention-cross-pillar-triggers for the trigger
  matrix and file-pattern mappings.

Three proof pillars: SRE observability (deployment frequency, lead time, failure rate, MTTR — the DORA numbers). Value stream tracking (idea-to-production traceability via plans/phases/boards). 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 TODOs. Most open TODOs graduated into plan-pal-e-agency phases during 2026-03-13 triage.

Slug Summary Discovered
todo-jinja2-plan-templates Jinja2 template rendering for plan creation (linked to deferred plan) 2026-03-09

Query: list_notes(project="pal-e-agency", note_type="todo", status="open") — filter for null parent_slug.