D. Agentic Workflow Standards

Wasteology has built real agentic capability — overnight feature delivery, cross-repo operators, multi-agent orchestration — but without a shared vocabulary for when to reach for which tool. This section establishes that vocabulary: a decision guide that matches the right tool to the job, a canonical home (wg-agent-infra) for shared agents, a standard promotion path from prototype to production, and the guardrails that keep autonomous work safe and auditable. The goal is not to impose process for its own sake, but to ensure every developer — current and future — starts with the same powerful baseline and doesn't reinvent what already works.

When to Use What — Decision Guide

Use this table as the first stop when deciding how to execute any piece of work.

Situation	Use This	Trigger
Exploratory, open-ended, or sensitive work requiring judgment at each step	Interactive Claude Code session	You are actively in the loop; the next step depends on what you learn
A repeatable multi-step workflow you invoke by name (e.g. "deploy this", "publish docs", "check lat")	Slash-command skill	Pattern is fixed, inputs vary per run
A cross-repo operation — same logic needed in multiple projects (e.g. publish docs from any repo, audit any repo's lat.md)	Global agent via wg-agent-infra	The operation must work identically regardless of which repo it is called from
A well-scoped task (bug fix, feature, chore) that can be implemented from a written spec without human decisions mid-flight	ADW overnight pipeline (`/dispatch`)	The spec is complete; human review happens on the resulting PR, not during implementation
A complex goal with parallelizable sub-problems — UI work + API + tests simultaneously	oh-my-claudecode multi-agent workflow	The task is too large or parallel for a single agent; sub-tasks can be assigned to specialists

Default rule of thumb: Start with an interactive session. Once you find yourself repeating the same sequence of steps across multiple sessions or multiple repos, extract it into a skill or agent. Once a spec is complete and the work is bounded, dispatch it to ADW and review the PR.

1. Interactive Claude Code Sessions

Current state

Used daily — /prime, /standup, /status, /diagnose, and ad-hoc exploration. No standard for when a session should stay interactive vs. be promoted to a skill.

Recommended standard

Interactive sessions are the right tool when:

The next step depends on what you learn from the current step (debugging, exploration, research)
The work involves judgment calls not expressible in a spec (architectural trade-offs, novel integrations)
The task is a one-off with no likelihood of repetition
The operation touches secrets, production databases, or irreversible state — you want a human watching each action

Interactive sessions are not the right tool when the same prompt sequence is being typed every day. That is a skill waiting to be extracted.

PO decision point

Should Claude Code sessions require a session-wrap step before closing? The /session-wrap command audits docs impact, proposes lat.md updates, and identifies skill extraction candidates. Recommend: require it for any session that produced committed code. Optional for exploratory sessions.

2. Slash-Command Skills

Current state

Skills live in .claude/skills/ and are auto-triggered by keyword patterns. Some are per-project (e.g., deploy/ in wdp-palantiri), some have been promoted to wg-agent-infra. No standard exists for when a skill should be per-project vs. promoted to global.

Recommended standard

A skill belongs in .claude/skills/ of a single repo when its logic is project-specific (deploy commands, test commands, project-specific validation). It should be promoted to wg-agent-infra when:

The same skill is needed in two or more repos, OR
The skill operates on a target repo (reads its config) rather than being part of that repo

Key distinction: Skills carry logic. Per-project config and context stay in the target repo's docs-triggers.yaml, manifests, and lat.md/. A global skill reads those at runtime rather than hardcoding project parameters.

How it works

Skills are defined in SKILL.md files with YAML frontmatter. The frontmatter declares trigger keywords, so Claude activates the skill automatically when a matching phrase appears in the prompt — no explicit /command call needed.

.claude/
  skills/
    deploy/
      SKILL.md      ← frontmatter: trigger: ["deploy", "push image"]

When the skill is promoted to global, the same file moves to wg-agent-infra/skills/ and is symlinked into ~/.claude/skills/ on every host.

3. wg-agent-infra — Canonical Home for Shared Agents

Current state

Ten global agents exist today, covering docs publishing, Prefect infrastructure, lat.md maintenance, web UI validation, command generation, governance auditing, and more (full catalog below). They were built one at a time as cross-repo needs emerged but without an explicit standard for promotion.

Recommended standard

wg-agent-infra is the canonical home for any agent or skill that must work across repos. Never copy an agent into a project repo. Never maintain two versions.

The logic-global / config-per-project model

This is the central design principle. An agent in wg-agent-infra carries only the algorithm — the steps, the prompts, the tool calls. It never hardcodes a project's parameters. At runtime it reads three layers:

Layer	What	Where it lives
Logic	The steps — what to do and how	`wg-agent-infra/agents/<name>.md` (global)
Config	Project-specific parameters — which docs site, which deploy command, which ADO repo	`docs-triggers.yaml`, `manifests/builtin/.toml` in the target* repo
Context	What the project is — its architecture, constraints, active tasks	`lat.md/` + `CLAUDE.md` in the target repo, read at runtime

This is what allows one docs-publisher agent to publish from wg-orchestration, wdp-palantiri, and mars_workorder_system without any per-project fork.

Distribution: symlink + link.sh

wg-agent-infra/
  agents/     → symlinked to ~/.claude/agents/
  skills/     → symlinked to ~/.claude/skills/
  commands/   → symlinked to ~/.claude/commands/
  scripts/
    link.sh   ← run once when adding a new resident

Because ~/.claude/ entries are symlinks to this repo (not copies), updating a resident requires only:

Edit the .md file in wg-agent-infra
git commit && git push
git pull on each host

No relink, no per-repo deploy, no drift. Adding a new resident (new file) requires running ./scripts/link.sh once to create its symlink, then restarting Claude sessions (agents load at session start).

Current resident catalog

Agent	Invoked for
`docs-publisher`	Publish or update docs on the wasteology-docs sites from any repo; reads `docs-triggers.yaml` for routing
`prefect-infra-operator`	Diagnose / create / deploy Prefect flows on the ACI push-pool platform
`lat-keeper`	Audit and sync a repo's `lat.md` against code; runs `lat check`; fulfills the post-task checklist
`playwright-validator`	Validate any web UI (Orbit, dashboard, docs) via Playwright MCP — navigate, act, screenshot, assert
`wg-command-generator`	Generate new wg-orchestration slash commands from a one-line description
`notebooklm-visuals`	Generate infographics, slides, or mind maps from docs via NotebookLM
`orbit-roadmap-update`	Reconcile the Mars roadmap against merged PRs and spec badges; can run headlessly post-merge
`azure-governance-auditor`	Audit Azure resources, costs, RBAC, and credential health across all three subscriptions
`tool-scout`	Research an external tool, score it against our infrastructure, and produce an HTML briefing
`youtube-insights`	Retrieve a video's transcript and produce a timestamped concept walkthrough

How any dev or repo invokes a global agent

From any Claude Code session, in any repo, without any per-project install:

Task(
  subagent_type="docs-publisher",
  prompt="Publish the portal reconciliation architecture docs"
)

Or via the oh-my-claudecode orchestration layer:

/oh-my-claudecode:orchestrate use docs-publisher to publish the recon docs

Agents are discovered automatically at session start — no per-project registration.

PO decision point

Who approves promotion to wg-agent-infra? Currently ad-hoc. Recommend: any agent that has been used successfully in two or more repos is eligible. The dev who built it opens a PR to wg-agent-infra; one reviewer approves. Once merged, it is available globally on next git pull.

4. ADW Overnight Pipeline

Current state

The Agentic Developer Workflow (ADW) turns a written spec into an implemented, PR'd feature overnight, with full observability in wg_digests and the wdp-palantiri dashboard (pages 9 and 10). Tasks enter from two sources: Tirion's OODA loop (automated, on accepted recommendations) and manual ops digest add-task.

Recommended standard

The ADW pipeline is the right tool when:

A spec is complete and reviewable before implementation begins
The work is bounded — a bug fix, a feature with defined acceptance criteria, a chore
Human review will happen on the resulting PR, not during implementation
The task can be expressed as text: a title and description sufficient for Claude Sonnet to plan and implement without asking questions mid-flight

The ADW pipeline is not the right tool for:

Exploratory work where the requirements will emerge during implementation
Operations touching production data or infrastructure without a rehearsed rollback plan
Work requiring external credentials that ADW does not have in its .env

Entry points (human-initiated)

# 1. Always create the spec first (handles dedup, registration, blob upload)
/spec-create "description of the work"         # from wg-orchestration directory

# 2a. Implement now in current session
/task <digest-task-id>                          # looks up spec → implements → wraps

# 2b. Deferred — let ADW pick it up overnight
/dispatch --go                                  # creates ADO work item + triggers pipeline 9
ops digest runner                               # equivalent CLI form

Critical distinction: /task <id> takes a digest task integer ID (from ops digest tasks). /feature, /bug, /chore take an ADO work item ID and description — these are the commands the ADW pipeline itself runs internally. Do not confuse them.

ADW pipeline steps (what happens overnight)

Classify work item type (bug / feature / chore)
Generate branch name
Plan implementation (Claude Sonnet claude-sonnet-4-6)
Review plan
Implement (Claude Sonnet claude-sonnet-4-6)
Review spec completeness
Commit — Gemini Flash generates the commit message (~98% cheaper than Claude for this step)
Create PR with auto-complete enabled

Observability

Every ADW run writes to three tables in wg_digests:

ai_developer_workflows — one row per execution with status and duration
agent_logs — per-step log entries
agents — agent registration records

wdp-palantiri surfaces these on Page 09 (Agent Activity) and Page 10 (ADW Swimlanes). Logfire provides real-time step tracing during execution via the adw-workflow root span.

PO decision point

Should all Tirion-accepted recommendations go straight to ADW, or should a human review the generated spec before dispatch? Current behavior: Tirion auto-dispatches after acceptance. Recommend: keep auto-dispatch for chores and low-risk bugs; require a 30-minute human spec review window before dispatch for features touching billing, reporting, or customer-facing data.

5. Multi-Agent Workflows (oh-my-claudecode)

Current state

oh-my-claudecode provides the orchestration layer: it routes work to specialist agents (executor, architect, designer, qa-tester, etc.), runs them in parallel when tasks are independent, and enforces verification before claiming completion. Used actively for complex feature work.

Recommended standard

Reach for multi-agent orchestration when:

The task has clearly parallelizable sub-problems (backend + frontend + tests)
Deep analysis is needed before implementation (architect → executor → qa-tester)
The task requires specialist knowledge in multiple domains simultaneously

The orchestration tier above ADW is:

Interactive session
  └── oh-my-claudecode orchestration (multi-agent, parallel, verified)
        └── ADW overnight (single-agent, spec-driven, unattended)

Multi-agent is heavier and more expensive. Use it when parallelism meaningfully shortens the wall-clock time or when specialist quality matters (e.g., a security reviewer running in parallel with the implementor).

6. How to Build a New Agentic Workflow — The Standard Promotion Path

New agentic workflows follow a three-stage promotion path.

Stage 1 — Prototype as a skill (single repo)

Start in the repo where the need is felt. Write a SKILL.md in .claude/skills/<name>/. Test it in interactive sessions. Keep it small: one responsibility, clear trigger keywords, minimal hardcoded assumptions.

Stage 2 — Promote to wg-agent-infra (cross-repo)

When the same skill is needed in a second repo, or when it operates on any repo's config rather than being part of one repo, promote it:

Move the logic to wg-agent-infra/agents/<name>.md (or skills/ if it remains skill-shaped)
Remove any project-specific hardcoding; replace with runtime reads from docs-triggers.yaml, manifests, or the target repo's lat.md
Run ./scripts/link.sh in wg-agent-infra to create the ~/.claude/ symlink
Open a PR; get one review
After merge: git pull on all hosts; restart Claude sessions

Stage 3 — Wire into ADW (autonomous execution)

When the workflow should run unattended — triggered by Tirion, a Prefect flow failure hook, or a scheduled pipeline — wire it into the ADW dispatch system:

Ensure the logic is expressible as a spec (title + description sufficient for Claude to plan)
Register the trigger: Tirion auto-fix rule, Prefect on_failure hook, or n8n scheduled workflow
Validate that the ADW agent has all required credentials in its .env
Run once manually (ops digest runner --local) and review the PR before enabling auto-dispatch

Concrete example — `orbit-roadmap-update`

Stage 1 (prototype): Built as a manual command in the mars repo to reconcile roadmap badges after merges. Tested interactively over several sprint closes.
Stage 2 (promote): The same logic was needed from wg-orchestration (which manages specs) and from CI. Moved to wg-agent-infra/agents/orbit-roadmap-update.md. Agent reads mars's lat.md and specs/roadmap.html at runtime — no hardcoding. Symlinked globally.
Stage 3 (autonomous): Wired into mars's adw-postmerge-roadmap.yml — the agent runs headlessly after every merge to main, keeping the roadmap current without manual intervention.

7. Governance & Guardrails

Verification before completion (mandatory)

No agent — interactive, skill, or ADW — claims "done", "fixed", or "complete" without fresh verification evidence. The standard checks, in order:

Claim	Required evidence
"Fixed"	A test run showing the test passes after the change
"Implemented"	`lat check` clean + build passing
"Refactored"	All tests still passing
"Deployed"	Container app revision confirmed via `az containerapp show`

Phrases like "should work", "probably fixed", or "seems correct" without a verification command output are disallowed. Agents must stop and run the check before reporting status.

Demanding file deliverables from subagents

Critical operational note: Claude Code's Stop hook can consume a subagent's final message, causing it to report "Noted." instead of its actual findings. Any workflow that spawns a subagent to produce a report or analysis must demand a file deliverable, not a text response:

# Correct pattern
"...write your findings to /tmp/agent-findings-<timestamp>.md"

# Then read that file in the orchestrating agent

For recovery when a subagent message was eaten: extract text blocks from the task .output JSONL file via Python.

Secrets handling

Agents must never:

Commit .env files, .key, .pem, credentials.json, or .secret files
Log secrets to stdout (they appear in wg_digests.agent_logs)
Construct database DSN URLs via shell string concatenation when the password contains @, $, !, `, or \ — use keyword arguments (asyncpg) or parameterized connection

The ADW pipeline's RISKY_FILE_PATTERNS guard in adws/adw_plan_build.py auto-unstages sensitive files before committing. Do not bypass it.

Generated passwords for any service must avoid $, !, `, \ — these break in double-quoted bash strings and are a common source of silent auth failures.

Cost awareness

Step	Approach	Rationale
ADW commit messages	Gemini Flash (not Claude)	~98% cheaper; commit message quality is acceptable
ADW system prompt	Prompt caching (`cache_control: ephemeral`)	~30% savings on plan and implement steps
Simple lookups in multi-agent workflows	Haiku-tier agents	Reserve Sonnet/Opus for reasoning-heavy steps
Overnight ADW	Claude Sonnet `claude-sonnet-4-6`	Calibrated for quality/cost balance; update `MODEL_MAP` in `adws/agent.py` when models change

Human-in-the-loop for risky operations

The following always require a human approval step before execution, regardless of automation level:

Production database schema migrations
Bicep infrastructure deploys (/infra skill enforces what-if before every prod deploy)
ADO PAT rotation or service principal changes
Dispatching ADW tasks to projects with customer-facing data (billing, CRM, API)
Any az containerapp update or Docker push to a prod container app

For the ADW pipeline specifically: auto-complete on the PR does not mean the change is deployed. Deployment is always a separate, human-approved step.

8. Onboarding — New Devs Inherit the Agents on Day One

How it works

The new-project checklist in lat.md/claude-standard.md (step 3 in the Adding a New Project section) includes cloning wg-agent-infra and running ./scripts/link.sh. After that, every global agent is available in the new dev's Claude sessions from the first session — no per-project install, no manual wiring.

The setup sequence is:

git clone https://dev.azure.com/wasteology/Wasteology/_git/wg-agent-infra ~/projects/wg-agent-infra
ln -s ~/projects/wg-agent-infra/agents   ~/.claude/agents
ln -s ~/projects/wg-agent-infra/skills   ~/.claude/skills
ln -s ~/projects/wg-agent-infra/commands ~/.claude/commands

After this, a new dev can immediately:

Run docs-publisher from any repo to publish docs
Run lat-keeper to audit and fix any repo's lat.md
Run playwright-validator to validate any web UI
Use all global slash commands (/spec-create, /dispatch, /standup, etc.)

Keeping agents current

Because ~/.claude/ entries are symlinks (not copies), updates reach every dev on git pull:

Edit the agent in wg-agent-infra → commit → push
Each dev runs git pull in ~/projects/wg-agent-infra
Symlinks resolve to the new content immediately; restart Claude sessions to activate

This eliminates the class of "my skills are outdated" problems that plagued per-repo copies.

The agent as onboarding documentation

Each resident in wg-agent-infra/agents/ doubles as documentation of the workflow it implements. A new dev reading docs-publisher.md learns the full docs-publishing workflow, not just the command. Keeping agents well-commented is therefore both a maintenance requirement and an onboarding investment.

PO decision point

Should wg-agent-infra setup be part of the IT/dev environment provisioning script, or documented as a manual step? Recommend: automate it in the standard developer setup script (the same one that installs uv, az, lat). This guarantees no dev is ever without the global agents, and eliminates one class of "it works on my machine" support requests.

Summary of Defaults

Decision	Default	Override when
Starting point for new work	Interactive Claude Code session	—
Extracting a repeatable workflow	Slash-command skill in the project repo	Needs to work in 2+ repos → promote to wg-agent-infra
Promoting to global	PR to wg-agent-infra with one review	—
Spec-based implementation	`/spec-create` → `/task` (now) or `/dispatch` (overnight)	—
Overnight automation	ADW pipeline (spec required, PR reviewed by human)	Work is exploratory or touches prod-critical data → interactive only
Multi-agent for complex tasks	oh-my-claudecode orchestration	Task is sequential with no parallelism → single-agent ADW
Verification	Always run a check command before claiming completion	—
Secrets	Never commit; use keyword args for DB passwords	—
Onboarding	wg-agent-infra setup in day-one provisioning script	—

When to Use What — Decision Guide​

1. Interactive Claude Code Sessions​

Current state​

Recommended standard​

2. Slash-Command Skills​

Current state​

Recommended standard​

How it works​

3. wg-agent-infra — Canonical Home for Shared Agents​

Current state​

Recommended standard​

The logic-global / config-per-project model​

Distribution: symlink + link.sh​

Current resident catalog​

How any dev or repo invokes a global agent​

4. ADW Overnight Pipeline​

Current state​

Recommended standard​

Entry points (human-initiated)​

ADW pipeline steps (what happens overnight)​

Observability​

5. Multi-Agent Workflows (oh-my-claudecode)​

Current state​

Recommended standard​

6. How to Build a New Agentic Workflow — The Standard Promotion Path​

Stage 1 — Prototype as a skill (single repo)​

Stage 2 — Promote to wg-agent-infra (cross-repo)​

Stage 3 — Wire into ADW (autonomous execution)​

Concrete example — orbit-roadmap-update​

7. Governance & Guardrails​

Verification before completion (mandatory)​

Demanding file deliverables from subagents​

Secrets handling​

Cost awareness​

Human-in-the-loop for risky operations​

8. Onboarding — New Devs Inherit the Agents on Day One​

How it works​

Keeping agents current​

The agent as onboarding documentation​

Summary of Defaults​

When to Use What — Decision Guide

1. Interactive Claude Code Sessions

Current state

Recommended standard

2. Slash-Command Skills

Current state

Recommended standard

How it works

3. wg-agent-infra — Canonical Home for Shared Agents

Current state

Recommended standard

The logic-global / config-per-project model

Distribution: symlink + link.sh

Current resident catalog

How any dev or repo invokes a global agent

4. ADW Overnight Pipeline

Current state

Recommended standard

Entry points (human-initiated)

ADW pipeline steps (what happens overnight)

Observability

5. Multi-Agent Workflows (oh-my-claudecode)

Current state

Recommended standard

6. How to Build a New Agentic Workflow — The Standard Promotion Path

Stage 1 — Prototype as a skill (single repo)

Stage 2 — Promote to wg-agent-infra (cross-repo)

Stage 3 — Wire into ADW (autonomous execution)

Concrete example — `orbit-roadmap-update`

7. Governance & Guardrails

Verification before completion (mandatory)

Demanding file deliverables from subagents

Secrets handling

Cost awareness

Human-in-the-loop for risky operations

8. Onboarding — New Devs Inherit the Agents on Day One

How it works

Keeping agents current

The agent as onboarding documentation

Summary of Defaults