coding-agent-orchestration: Skill for Codex

continuous-documentation

Purpose

Run the continuous-documentation workflow in continuous mode until the dispatcher returns recommended_role: stop (no MAJOR/MODERATE findings remain).

The workflow rotates through four prompt steps in a strict cycle:

1. prompt.docs_gap_analysis — detect missing documentation
2. prompt.docs_gap_fix — apply targeted gap fixes
3. prompt.docs_refactor_analysis — analyze existing doc quality
4. prompt.docs_refactor_fix — apply refactors

Cold starts are handled automatically — the infrastructure initialises the rotation at step 1 when no prior runtime entry exists.

Agent execution protocol

Run one dispatcher step at a time:

# 1. Ask the dispatcher for the next prompt
python3 .codex/skills/vibe-loop/scripts/agentctl.py --repo-root . --format json next --workflow continuous-documentation

# 2. Read the prompt body from the catalog path returned by the dispatcher
python3 .codex/skills/vibe-prompts/scripts/prompt_catalog.py <prompt_catalog_path> get <recommended_prompt_id>

# 3. Execute the prompt body (do the actual documentation work)

# 4. After execution, record the loop result
python3 .codex/skills/vibe-loop/scripts/agentctl.py --repo-root . --format json loop-result --line "LOOP_RESULT: <json>"

# 5. Repeat from step 1 until recommended_role == "stop"

The --workflow continuous-documentation flag is required — it activates the continuous override that ignores normal plan-state routing and selects from the documentation prompt rotation instead.

In this orchestration source repo, use tools/agentctl.py and tools/prompt_catalog.py instead; the .codex runtime helper scripts are generated during install.

LOOP_RESULT format

After executing each prompt, emit a LOOP_RESULT JSON line with the dispatcher-required report fields:

{
  "loop": "implement",
  "result": "ready_for_review",
  "stage": "<current_stage>",
  "checkpoint": "<current_checkpoint>",
  "status": "<current_status>",
  "next_role_hint": "implement|review|stop",
  "workflow": "continuous-documentation",
  "report": {
    "acceptance_matrix": [
      {
        "item": "<checked behavior>",
        "status": "PASS|FAIL|N/A",
        "evidence": "<command or file evidence>",
        "critical": true,
        "confidence": 0.9,
        "evidence_strength": "LOW|MEDIUM|HIGH"
      }
    ],
    "top_findings": [
      {"impact": "MAJOR|MINOR", "title": "[MAJOR|MODERATE|MINOR] ...", "evidence": "...", "action": "..."}
    ],
    "state_transition": {
      "before": {"stage": "<current_stage>", "checkpoint": "<current_checkpoint>", "status": "<previous_status>"},
      "after": {"stage": "<current_stage>", "checkpoint": "<current_checkpoint>", "status": "<current_status>"}
    },
    "loop_result": {
      "loop": "implement",
      "result": "ready_for_review",
      "stage": "<current_stage>",
      "checkpoint": "<current_checkpoint>",
      "status": "<current_status>",
      "next_role_hint": "implement|review|stop"
    }
  }
}