pal-e-docs

Agent Workflow

agent-workflow Sop

sop active agent
Project

Agent Workflow

The operating model for the DORA Elite AI Enterprise. Defines how work flows from board to production: who does what, what they can see, and how compliance is enforced. Management layer (Lucas, Ava, Dottie) owns the process. Execution layer (Dev, QA) owns the implementation. The Forgejo issue is the contract between the two layers.

Five Agents

Agent Role Domain
**Ava** Brain — coordinates, manages knowledge, creates issues, tracks boards pal-e-docs + Forgejo + Woodpecker
**Penny** Comms — email, calendar, social, external KBs Gmail, GCal, LinkedIn, Notion
**Dev** Hands — writes code across all domains. Impeccable skills for frontend, tofu enforcement for infra, ruff for Python, schema.rb drift check for Rails. Model decides what's relevant Repos + Forgejo only
**QA** Eyes — reviews PRs for code quality + dynamic domain expertise + PROCESS OBSERVATIONS. Explicit BLOCKER criteria Repos + Forgejo only
**Dottie** Librarian — executes doc updates, content audits, quality tracking pal-e-docs (delegated by Ava)
Strict information boundary. Dev and QA are repo-only — no pal-e-docs access, no boards, no SOPs. They get a well-scoped Forgejo issue and execute. The scoping pipeline (projects → boards → issues) is the management layer's job. By the time an agent sees an issue, all context is baked in.
Ava delegates documentation execution to Dottie to preserve main session context. Dottie operates in a separate context window, executing mechanical doc tasks (note creation, updates, audits) under Ava's direction. Dottie never makes strategic decisions — she executes and reports back. See decision-agent-dottie.

Knowledge Access: Block-First

All agents with pal-e-docs access (Ava, Dottie) follow the block-first pattern. See convention-block-first-access for full details.
  • Navigate: get_note_toc(slug) — see what sections exist before reading the full note
  • Read: get_section(slug, anchor_id) — fetch only the section you need
  • Write: update_block(slug, anchor_id, content) — edit one section without touching the rest
  • Fallback: get_note(slug) / update_note(content=...) — only for small notes or full rewrites
This pattern reduces token consumption by ~91% for note reads. Session startup injects board state; agents read sections on demand.

Work Path: Board-Driven

All work flows through the board. Every work item is a Forgejo issue on a project board.

The Flow

Ava creates a typed Forgejo issue (Feature/Bug/Spike/Task), adds it to the project board. Lucas reviews scope at the todo column. When approved to next_up, Ava spawns a dev agent. The Forgejo issue IS the spec.

Issue Types

All types use the same board flow. No standalone todo-* or bug-* notes — the Forgejo issue is the spec. See convention-todo-lifecycle for the type decision tree.

The Fundamental Rules

  • No issue, no agent. Every spawned agent traces to a Forgejo issue on a board. See agent-spawn-conventions.
  • No issue, no work. Agents work on Forgejo issues. The issue IS the spec.
  • Agents are repo-only. Dev and QA have zero pal-e-docs access. They read Forgejo issues and repo code. That's it.
  • Ava owns docs. Only the main session directs pal-e-docs changes. Dottie executes doc operations under Ava's direction. Dev and QA never touch docs.
  • Agents own repos. Only spawned agents write code and submit PRs. Ava never touches repo code directly.
  • Agents signal status via labels. Dev and QA set Forgejo labels to signal workflow state. Ava reads labels and syncs boards.
  • Block-first knowledge access. Navigate by TOC, read by section, write by block. Full note reads are the fallback, not the default. See convention-block-first-access.
  • Autonomy levels govern actions. L0 (always ask Lucas), L1 (proceed if SOP exists), L2 (fully autonomous). See convention-agent-autonomy-levels.
  • Self-correct before escalating. When something breaks, follow the matching recovery SOP. Escalate only after recovery steps fail. See convention-escalation-triggers.
  • Verified beats reported. Before marking work complete, run validation checkpoints. See convention-validation-checkpoints.

The Flow

  • Scope — Ava creates typed Forgejo issue (Feature/Bug/Spike/Task), adds to project board
  • Board — Ava calls sync_board(board_slug) on the project board. Open Forgejo issues auto-appear as board items.
  • Spawn — Ava spawns dev agent with ~100 token prompt pointing to issue
  • Execute — Dev reads Forgejo issue, implements. Hook auto-sets status:in-progress on branch creation.
  • Signal — Dev submits PR. Hook auto-sets status:qa on issue, comments PR URL.
  • Review — Ava spawns QA agent. QA reviews PR, posts structured findings as PR comment.
  • Verdict — QA includes VERDICT line. Hook auto-sets status:approved or status:needs-fix.
  • Fix Loop — If needs-fix: Ava dispatches Dev with rework instructions. Dev fixes, submits. Repeat until approved.
  • Present — Ava presents PR to Lucas. STOP. Never merge without approval.
  • Deploy — For CI-enabled repos (pal-e-platform), merge triggers automatic deploy via Woodpecker. Ava verifies pipeline success before proceeding to doc updates. If the apply step failed, follow sop-ci-pipeline-recovery. For non-CI repos, this step is implicit (merge = done).
  • Update — After merge (and deploy verification if applicable): remind-update-docs.sh fires. Ava runs /update-docs to update project docs (via Dottie if needed). Ava calls sync_board to reconcile if needed.

Label Signaling Protocol

Forgejo labels are the communication channel between agents and the management layer. Labels are the source of truth for workflow state. Labels are set automatically by PostToolUse hooks — agents do not set labels manually. See label-on-branch.sh, label-on-pr.sh, label-on-verdict.sh in claude-custom.

Status Labels (set by agents)

Label Set By Hook Trigger DORA Data
<code>status:in-progress</code> <code>label-on-branch.sh</code> <code>create_issue_and_branch</code> Lead Time start timestamp
<code>status:qa</code> <code>label-on-pr.sh</code> <code>submit_pr</code> Code complete timestamp
<code>status:needs-fix</code> <code>label-on-verdict.sh</code> <code>comment_on_pr</code> with VERDICT: NOT APPROVED Rework iteration (Change Failure Rate)
<code>status:approved</code> <code>label-on-verdict.sh</code> <code>comment_on_pr</code> with VERDICT: APPROVED Review complete timestamp

Type Labels (set by Ava at issue creation)

Label Purpose
<code>type:feature</code> New functionality
<code>type:bug</code> Bug fix
<code>type:devops</code> Infrastructure/CI/config work

Rules

  • Hooks set status labels automatically. Ava sets type labels at issue creation.
  • Only one status label at a time. Each hook replaces the previous status label.
  • QA posts structured review as a PR comment (via comment_on_pr). The VERDICT line in the comment triggers the label hook.
  • Every QA nit gets either a "no fix needed because X" comment or Ava dispatches Dev with rework instructions and the hook sets status:needs-fix.

Board Workflow (Continuous Kanban)

Boards are the work execution tool. Continuous kanban flow — no time-boxed sprints. Full details in sop-board-workflow. Key mechanics: (1) sync_board(board_slug) reconciles Forgejo issues onto the board, (2) sync-issues pulls open Forgejo issues onto boards automatically. Left side of the board (backlog → todo → next_up) is the scoping pipeline. The todo column is a planning review gate where Lucas reviews scope before items advance to next_up. Right side (in_progress → done) is automated via label hooks. Board items are Forgejo issues — no standalone todo-* or bug-* notes. See convention-kanban-over-plans.
Trigger Board Effect Manual?
<code>sync_board(slug)</code> called All Forgejo issues reconciled — missing items created, columns aligned Ava calls at session start + after merge
<code>sync-issues</code> called (with sync_board) Open Forgejo issues from linked repos auto-appear as board items. Closed issues move to done. Automated (runs with sync_board)
Non-issue item (repo onboarding) Must be created/moved manually Yes — <code>create_board_item</code> / <code>update_board_item</code>

Repo Pages = READMEs

Repo documentation lives in repo READMEs, not pal-e-docs notes. READMEs point to pal-e-docs for project context. pal-e-docs has project pages, not repo pages.
  • agent-spawn-conventions — spawn rules, minimal prompt pattern, enforcement
  • pr-lifecycle — the 7-stage PR flow with label integration
  • template-issue — what goes in a Forgejo issue
  • plan-pal-e-agency — A DORA Elite AI Enterprise Operating Model
  • project-pal-e-agency — project page with architecture diagrams
  • dora-framework — labels feed DORA metrics
  • convention-block-first-access — the knowledge access pattern all pal-e-docs agents follow
  • convention-agent-autonomy-levels — L0/L1/L2 action classification
  • convention-escalation-triggers — when to stop and ask
  • convention-validation-checkpoints — three verification loops (per-phase, per-session, periodic)
  • agent-dottie — Dottie's personality and access scope
  • decision-agent-dottie — why Dottie was created