audit-skill-md

Metadata

Description

## Description
SKILL.md should mirror agent-guide content for use as a skill installation. Audit for alignment with current agent-guide and divergence-from-current-behavior.

## Baseline

Determine baseline = last commit that touched this file by a human (heuristic: commits NOT authored by an agent — agent commits have agent IDs in commit messages; human commits do not). If unclear, fall back to 2026-04-12 (date of prior doc-sync-audit doc).

Audit scope = ALL changes to wg behavior / commands / config / state-machine / etc. SINCE that baseline. Not just today. Look at git log between baseline and HEAD.

## Output (no source/doc changes)
Post findings via \`wg log <this-task-id>\` as a structured list of deltas. Each delta = one specific update needed in the audited file. Format:

  - **Section X:** <what is currently said vs what should be said, with citation>
  - **Missing:** <feature/command/concept not mentioned>
  - **Stale:** <reference to removed or superseded thing>
  - **Inconsistent:** <conflicts with another doc — note which>

The synthesis task (doc-sync-audit) reads all audit logs and applies updates. This task DOES NOT MODIFY FILES.

## Validation
- [ ] Baseline commit identified (cite SHA or fall back to 2026-04-12 with reasoning)
- [ ] Delta list posted via wg log with structured entries
- [ ] No source / doc modifications — audit only

Depends on

• done quality-pass-doc
• done .assign-audit-skill-md

Required by

• done doc-sync-audit

Log

• 2026-04-30T02:05:06.463176320+00:00 Task paused
• 2026-04-30T02:08:32.966755608+00:00 Task published
• 2026-04-30T02:09:03.349642372+00:00 Lightweight assignment: agent=Careful Programmer (f5143935), exec_mode=light, context_scope=task, reason=Careful Programmer's detail-oriented tradeoff and strong documentation/code review track record (score 0.78, 364 tasks) are ideal for carefully auditing SKILL.md alignment with git history; read-only access sufficient for history review and structured delta reporting.
• 2026-04-30T02:19:11.596997042+00:00 Spawned by coordinator --executor amplifier --model sonnet
• 2026-04-30T02:19:15.241574914+00:00 Task marked as failed: Agent exited with code 1
• 2026-04-30T02:26:24.767484253+00:00 Task reset for retry from failed (attempt #2)
• 2026-04-30T02:26:30.302349944+00:00 Spawned by coordinator --executor claude --model sonnet
• 2026-04-30T02:27:00.508020467+00:00 Starting audit: reading SKILL.md and git history to establish baseline
• 2026-04-30T02:30:20.802469584+00:00 Baseline: a13eebd69 (2026-04-12) — last agent commit in doc-sync-apr12 series. All commits to SKILL.md since 2026-02-27 have been agent commits; the prior human commit was 7f7c9a0ed (2026-02-27, feat: autopoietic task generation with guardrails). Using a13eebd69 as the effective documentation baseline since agent commits kept SKILL.md current through that date. Audit scope = 523 commits since 2026-04-12.
• 2026-04-30T02:30:31.441817833+00:00 DELTA LIST (1/4) — Terminology/Role changes: - **Stale Section 'Your role as a top-level agent':** SKILL.md says 'You are a **coordinator**.' — should say 'You are a **chat agent**.' agent-guide (wg agent-guide, reorg-separate-universal commit 9de67a5e3, 2026-04-29) formally deprecated 'coordinator' and 'orchestrator' as role nouns. New vocabulary: 'dispatcher' = the daemon; 'chat agent' = the persistent LLM session the user talks to; 'worker agent' = spawned-by-dispatcher LLM process. - **Stale Section 'Service & agents' table:** wg service subcommands renamed. 'create-coordinator' → 'create-chat', 'delete-coordinator' → 'delete-chat', 'archive-coordinator' → 'archive-chat', 'stop-coordinator' → 'stop-chat', 'interrupt-coordinator' → 'interrupt-chat'. Old names are legacy aliases preserved but not primary. (implement-tmux-wrapped, migrate chat-rename migration). - **Stale Section 'Setup & configuration' table:** Line 'wg config --coordinator-executor claude' is now 'wg config --dispatcher-executor claude'. The '--coordinator-executor' flag is now labeled a legacy alias in wg config --help output. Line 'wg config --coordinator-provider openrouter' is explicitly marked [DEPRECATED] — use 'provider:model' in --coordinator-model instead. - **Stale Section 'Multi-coordinator support' (bottom):** Uses all old command names (create/stop/archive/delete-coordinator) and states default '--max-coordinators 4' — actual default is now 16 (confirmed via wg config --help). Also uses wg chat --coordinator 1 which still works but is now the --coordinator flag for the coordinator ID, not a role noun.
• 2026-04-30T02:30:52.345947261+00:00 DELTA LIST (2/4) — Missing new commands/subcommands: - **Missing wg secret:** New secrets management command (set, get, list, rm, check, backend subcommands). Manages API keys in credential store. Added in implement-wg-secret (6f4c98d1c, 2026-04-28). SKILL.md has 'wg key' but not 'wg secret'. - **Missing wg recover:** Batch-recover from credit-exhaustion/mass-failure (dry-run by default). Options: --yes, --filter, --set-model, --set-endpoint, --keep-agency, --max-attempts, --reason. Not in SKILL.md. - **Missing wg reprioritize:** Change task priority level (critical/high/normal/low/idle). Not in SKILL.md. - **Missing wg rescue:** Rescue failed task by inserting first-class replacement at its graph slot. Rewires successors to unblock from the rescue. Not in SKILL.md. - **Missing wg reset:** Bulk-reset a subgraph — given seed tasks, close reachable set and reset each to Open. Has --also-strip-meta to delete system tasks. Not in SKILL.md. - **Missing wg worktree:** Manage agent worktrees (list, archive, inspect). Not in SKILL.md. - **Missing wg incomplete:** Mark task as incomplete (retryable — needs another pass). Not in SKILL.md. - **Missing wg insert:** Graph-surgery primitive: insert task before/after/parallel to existing target. Foundation for 'wg rescue'. Not in SKILL.md. - **Missing wg cleanup:** Manual cleanup commands for edge case recovery. Not in SKILL.md. - **Missing wg executors:** List executors wg knows about, which are usable, and where binaries live. Not in SKILL.md. - **Missing wg which:** Print workgraph directory wg would use from here (shows resolver step). Not in SKILL.md. - **Missing wg html:** Render workgraph as static clickable HTML viewer (TUI-parity). Not in SKILL.md. - **Missing wg metrics:** Display cleanup and monitoring metrics. Not in SKILL.md. - **Missing wg nex:** Interactive agentic REPL — coding assistant powered by any model. Not in SKILL.md. - **Missing wg session:** Manage nex chat sessions (list, attach, alias). Not in SKILL.md. - **Missing wg migrate:** One-shot graph migrations: chat-rename, retire-compact-archive, config, secrets. Not in SKILL.md. Notably: 'wg migrate chat-rename' rewrites .coordinator-N → .chat-N. - **Missing wg coordinator:** Manage coordinator sessions (list, archive, restore). Separate from wg service commands. Not in SKILL.md. - **Missing wg agent-guide:** Print the universal agent/chat-agent role contract bundled with the binary. Not in SKILL.md.
• 2026-04-30T02:31:15.407356664+00:00 DELTA LIST (3/4) — Missing new service subcommands, wg chat subcommands, wg done/retry behavior: - **Missing wg service install:** Generate a systemd user service file for the wg service daemon. Not in SKILL.md. - **Missing wg service set-executor:** Hot-swap a chat agent's executor and/or model. SIGTERMs live handler; supervisor respawns with new settings. Conversation history preserved. Options: --executor, --model. Not in SKILL.md. - **Missing wg service purge-chats:** Bulk-purge all chat agents — archive every chat-loop task, kill live chat handlers, prevent respawn on daemon restart. Idempotent, reversible via 'wg chat new'. Not in SKILL.md. - **Missing wg chat subcommands:** SKILL.md only shows 'wg chat send/history/clear/attachment/coordinator' as options. Current 'wg chat' has full subcommands: create, list, show, attach, send, stop, resume, archive, delete. These parallel the service create/stop/archive/delete-chat commands at a per-session level. Not in SKILL.md. - **Missing wg retry options:** SKILL.md shows only 'wg retry <id>'. Current command has: --preserve-session (keep Claude session ID), --fresh (discard prior worktree, start from main), --reason (log reason). Added in add-wg-retry (71b671ac1, 2026-04-27). Especially important: --fresh vs default retry-in-place semantics for prior WIP. - **Missing wg done --ignore-unmerged-worktree:** Defer worktree merge when branch cannot be cleanly merged (creates .merge-<id> task). Added in wg-done-silent (417d8c305, 2026-04-28). Not in SKILL.md. - **Section 'Task state transitions': Missing wg reap command:** 'wg reap' dead/done/failed agents from registry. SKILL.md has 'wg dead-agents --purge' but not the standalone 'wg reap' command. - **Section 'Task lifecycle': Missing failed-pending-eval state:** When agent exits nonzero and auto_evaluate=true, task transitions to 'failed-pending-eval' instead of directly to 'failed'. The .evaluate-* system task bypasses the block on downstream. Operator 'wg fail' on a failed-pending-eval task forces terminal transition. Added in implement-failed-pending (cae4cca54, 2026-04-29). SKILL.md lifecycle diagram does not include this state.
• 2026-04-30T02:31:39.664961791+00:00 DELTA LIST (4/4) — Missing behavioral/role contract content, stale executor info, retired concepts: - **Missing: Quality pass convention:** agent-guide section 'Quality pass before batch execution' — when a chat agent creates more than a couple of tasks, it inserts a .quality-pass-<batch-id> task with no --after (immediately ready), wired to gate the batch via --before/--after. Not mentioned in SKILL.md. - **Missing: Paused-task convention:** agent-guide section 'Paused-task convention' — a task in waiting status is a deliberate hold; worker agents and dispatcher MUST NOT unilaterally resume it. Only use wg resume when the blocker is genuinely cleared. Not in SKILL.md. - **Missing: Smoke gate documentation:** agent-guide has a detailed 'Smoke Gate (Hard Gate on wg done)' section. SKILL.md has no mention of the smoke gate despite being the skill that bootstraps agent context. - **Missing: Worktree isolation warnings:** agent-guide explicitly warns against using EnterWorktree/ExitWorktree tools (they abandon the workgraph branch and cause lost work). Not in SKILL.md. - **Missing: Prior WIP handling:** agent-guide tells worker agents to inspect prior work-in-progress before starting fresh (git status, git log, git diff). Not in SKILL.md. - **Stale: WG_EXECUTOR_TYPE env var values:** SKILL.md section 'Environment variables' says values are 'claude', 'amplifier', or 'shell'. agent-guide lists 'claude', 'codex', 'nex', 'shell', ... — 'amplifier' appears to be superseded; 'codex' and 'nex' are now first-class handler types. - **Stale: Amplifier executor description:** SKILL.md section 'Amplifier bundles (amplifier executor only)' refers to WG_EXECUTOR_TYPE=amplifier which may be deprecated. Current service executor types are claude, codex, nex, native, shell per wg executors listing. - **Stale/Retired: .compact-N and archive-loop tasks:** 'wg migrate retire-compact-archive' migration description states 'The graph-cycle compactor and archive-loop scaffolding were retired — archival now runs natively in the dispatcher; chat memory is handled by the chat agent's own memory subsystem.' SKILL.md does not document the wg compact command as retired. - **Missing: wg config lint subcommand:** New subcommand under wg config — read-only companion to wg migrate config that reports deprecated keys, legacy field names, stale model strings without rewriting. - **Missing: wg config merged flag:** New --merged flag shows effective merged config (global + local) for debugging model routing. Not in SKILL.md's config section. - **Inconsistent with CLAUDE.md: --executor flag:** SKILL.md has 'wg config --executor claude' and 'wg config --global --executor claude'. CLAUDE.md states '--executor / -x flag and [agent].executor / [dispatcher].executor config keys are deprecated'. wg config --help confirms --executor still works but model-spec is the single source of truth. - **Inconsistent with agent-guide: 'coordinator' label in wg service create-coordinator:** SKILL.md 'Multi-coordinator support' section still uses create/stop/archive/delete-coordinator naming while agent-guide says these are legacy aliases for create/stop/archive/delete-chat.
• 2026-04-30T02:31:49.534328438+00:00 Validation: Baseline identified as a13eebd69 (2026-04-12) with reasoning. Delta list posted in 4 structured log entries covering: (1) terminology/role changes, (2) missing new commands, (3) missing service/chat/done/retry changes, (4) missing behavioral contract content and stale items. No source or doc files modified — audit only.
• 2026-04-30T02:31:52.489876530+00:00 Task pending eval (agent reported done; awaiting `.evaluate-*` to score)
• 2026-04-30T02:33:34.416274496+00:00 PendingEval → Done (evaluator passed; downstream unblocks)