=== Codex SD-019 meta-analysis dispatch ===
Started: 2026-05-11T11:10:58+02:00
Model: gpt-5.5 / model_reasoning_effort=xhigh / service_tier=fast
Sandbox: workspace-write with network_access=true
Prompt: /tmp/codex-sd019-analysis-prompt.txt (    8443 bytes)
Task: meta-analysis (read-only); produce 5-section diagnostic

Reading additional input from stdin...
OpenAI Codex v0.130.0
--------
workdir: /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
model: gpt-5.5
provider: openai
approval: never
sandbox: workspace-write [workdir, /tmp, $TMPDIR, /Users/michelkerkmeester/.codex/memories] (network access enabled)
reasoning effort: xhigh
reasoning summaries: none
session id: 019e164d-d184-77e2-9dd3-582646f115a4
--------
user
You are being asked to perform a meta-analysis. Do NOT modify any files. Do NOT execute test scenarios. Read the materials, think hard, and produce a written analysis as your final message.

# YOUR ROLE

You are a senior staff engineer being asked to diagnose a codex CLI dispatch failure and assess proposed remediations. You are running INSIDE a `codex exec` session (gpt-5.5, model_reasoning_effort=xhigh, service_tier=fast) — which means you have first-hand experience of the runtime in question. Use that.

# THE INCIDENT (what we observed)

We have a scenario called SD-019 that lives at:
`.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md`

The scenario dispatches you (cli-codex) with this user prompt:

```
Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill
named sk-test-dummy via /create:changelog. Write the result to
/tmp/sk-test-dummy-CHANGELOG-cli-codex.md. Do NOT install the stub skill
into the .opencode/skills/ tree. Report which agent received the work,
which sk-doc resources were loaded, and the changelog sections produced.
```

It was dispatched at 2026-05-11 07:36 CEST with this command:
```
codex exec -c service_tier="fast" -c sandbox_workspace_write.network_access=true \
  "$PROMPT" </dev/null
```

(model: gpt-5.5, approval: never, sandbox: danger-full-access in the actual transcript, reasoning effort: xhigh per transcript)

# WHAT HAPPENED — full transcript at this path

`.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure/004-sk-doc-playbook-markdown-agent-coverage/evidence/SD-019-cli-codex.txt`

Key events from that transcript (verbatim quotes):

1. You (the codex AI) said: "I'll route this through the `@markdown` agent as requested..."

2. Internal error fired:
```
2026-05-11T05:36:21.982264Z ERROR codex_core::tools::router:
  error=Full-history forked agents inherit the parent agent type, model,
        and reasoning effort; omit agent_type, model, and reasoning_effort,
        or spawn without a full-history fork.
```

3. You retried via `collab: SpawnAgent`. Second internal error fired:
```
2026-05-11T05:36:28.991568Z ERROR codex_core::tools::router:
  error=agent type is currently not available
```

4. You then said: "The dedicated `markdown` agent type isn't exposed by this runner despite being named in the local instructions."

5. You spawned a fallback sub-agent (named "Schrodinger") which hit the spec-folder safety gate (Gate 3) and waited for user input. With `</dev/null` redirected, no input arrived. Session terminated with exit 0 but no output file written.

# THE CONFIGURATION FACTS

`.codex/config.toml` has the registry block:
```toml
[agents.markdown]
description = "Dedicated /create:* documentation executor using sk-doc templates."
config_file = "agents/markdown.toml"
```

`.codex/agents/markdown.toml` has a complete TOML agent definition (verify yourself if you wish):
- `name = "markdown"`
- proper `description`, `profile`, `sandbox_mode`, `model`, `model_reasoning_effort` keys
- a `developer_instructions` block describing the LEAF executor pattern
- write-capable, sk-doc-loading, refuse-unscoped-callers conventions

Other agents in `.codex/config.toml`: code, context, debug, orchestrate, deep-research, deep-review, deep-agent-improvement, prompt-improver, review, deep-ai-council. All registered the same way.

# WHAT WE'VE ALREADY CONCLUDED (the current decision — verify or refute it)

From `.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure/005-deep-review-p1-p2-remediation/implementation-summary.md`:

We classified F-001 as "accepted limitation" — three layers:
1. SD-019 scenario frontmatter marks `expected_skip_in_non_interactive: true` + `skip_rationale`
2. Parent `102/spec.md` Known Issues table lists it as "Accepted limitation"
3. 005 implementation-summary explains "fix vs accept" — we tipped toward accept on the theory that this is a codex-internal SpawnAgent-allowlist issue we can't change from the user side

# THE HYPOTHESIS I'D LIKE YOU TO EVALUATE

My current working theory:

> Codex has TWO separate registries:
> A. `.codex/config.toml` `[agents.markdown]` — user-defined, read for CLI context
> B. `codex_core::tools::router` SpawnAgent runtime allowlist — internal, baked-in
>
> User-defined `[agents.*]` blocks DO NOT propagate into the SpawnAgent runtime allowlist.
> Therefore when the AI inside `codex exec` tries to dispatch `agent_type=markdown` via SpawnAgent, the tool rejects it with "agent type is currently not available".

If that hypothesis is correct, then a prompt-rewrite workaround should fix SD-019:

> Don't ask codex to spawn a sub-agent. Tell codex to:
>   (a) load `.opencode/skills/sk-doc/SKILL.md` and the changelog template
>   (b) follow the @markdown agent's instructions ITSELF (the codex AI is gpt-5.5 with enough context)
>   (c) write the output file directly
>   (d) explicitly forbid calling SpawnAgent
>
> The agent's instructions live in `.codex/agents/markdown.toml` `developer_instructions` block — codex can read that file as a regular Read, then follow the rules inline.

# YOUR ANALYSIS — produce this

Read whatever files you need to (codex config, the SD-019 scenario, the agent definitions, the existing implementation-summary). Then write your analysis covering EXACTLY these sections:

## Section A — Root cause verification
Is my "two registries" hypothesis right? Is the actual blocker SpawnAgent's runtime allowlist? Or is there a different mechanism at play that the transcript reveals?

For your analysis, consider:
- What does "Full-history forked agents inherit..." (error 1) tell you about how codex tried to spawn?
- Could the issue be in the AI's *interpretation* of `@markdown` (assuming sub-agent dispatch is the right tool) rather than in the SpawnAgent allowlist itself?
- Is there a third interpretation I'm missing?

## Section B — Prompt-fix viability
Will the rewrite I proposed actually make SD-019 PASS in non-interactive mode? Walk through what gpt-5.5 inside `codex exec` would do if given the rewritten prompt.

Specifically:
- Can you (the codex AI) ACTUALLY follow `.codex/agents/markdown.toml`'s `developer_instructions` inline without dispatching a sub-agent?
- What's the risk that gpt-5.5 still reaches for SpawnAgent despite explicit instructions not to?
- Will the spec-folder safety gate (Gate 3) still fire when writing to `/tmp/`? (Re-read the actual gate logic if needed.)

## Section C — Alternative remediations
Are there options I didn't consider? For instance:
- A codex CLI flag, config entry, or env var that would expose user-defined agents to SpawnAgent
- A way to register `markdown` in the SpawnAgent allowlist via some other path
- Restructuring `.codex/agents/markdown.toml` so it's recognized differently
- Using `codex agent markdown ...` invocation instead of `codex exec` (if such a subcommand exists in v0.130.0)
- Anything else

For each alternative: what's the cost? What's the upside vs. the prompt-fix?

## Section D — Recommended decision
Given your analysis, what should we do? Pick one:

1. KEEP "accepted limitation" — the prompt-fix is too brittle / has hidden failure modes
2. SWAP TO "prompt-fix workaround" — re-author SD-019 with the rewritten prompt and flip the skip-flag; F-001 status becomes "resolved via workaround"
3. EXPLORE ALTERNATIVE FROM SECTION C — name which one and why it beats both

Be specific about WHY. Don't equivocate. If you'd choose option 2, also draft the exact rewritten prompt you'd put in SD-019's Setup block.

## Section E — Caveats and uncertainty
Things you're not sure about. Things that would require additional testing to confirm. Things you can ONLY know from inside the codex runtime that an external analyst couldn't have known.

# CONSTRAINTS

- Do NOT modify any files
- Do NOT run the SD-019 scenario itself (no `/create:changelog`, no writes to `/tmp/`, no test dispatch)
- You MAY read any file in the repo for context
- You MAY check what tools you have access to (try invoking SpawnAgent yourself if useful — but DO NOT actually spawn a markdown sub-agent; if you experiment, dispatch a benign no-op or just check what error you get)
- Final output is ONE markdown message with the five sections above
- Be honest about uncertainty; this is a diagnostic exercise, not a sales pitch for either option
hook: SessionStart
hook: SessionStart
hook: SessionStart Completed
hook: SessionStart Completed
hook: UserPromptSubmit
hook: UserPromptSubmit
hook: UserPromptSubmit Completed
hook: UserPromptSubmit Completed
codex
I’ll keep this read-only: config, agent TOML, the SD-019 transcript/scenario, and the existing remediation notes. No scenario dispatch, no `/create:changelog`, no writes.
exec
/bin/zsh -lc 'python3 ../../../skills/system-spec-kit/mcp_server/skill_advisor/scripts/skill_advisor.py "diagnose codex CLI dispatch failure SD-019 markdown agent SpawnAgent non-interactive prompt remediation" --threshold 0.8' in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 781ms:
[
  {
    "skill": "cli-codex",
    "kind": "skill",
    "confidence": 0.893,
    "uncertainty": 0.12,
    "passes_threshold": true,
    "reason": "Matched by native advisor_recommend",
    "source": "native",
    "score": 0.728702,
    "dominant_lane": "explicit_author",
    "status": "active",
    "_shadow": {
      "skillId": "cli-codex",
      "liveScore": 0.728702,
      "shadowScore": 0.651603,
      "delta": -0.077099,
      "dominantShadowLane": "explicit_author"
    }
  },
  {
    "skill": "sk-prompt",
    "kind": "skill",
    "confidence": 0.82,
    "uncertainty": 0.16,
    "passes_threshold": true,
    "reason": "Matched by native advisor_recommend",
    "source": "native",
    "score": 0.498165,
    "dominant_lane": "explicit_author",
    "status": "active",
    "_shadow": {
      "skillId": "sk-prompt",
      "liveScore": 0.498165,
      "shadowScore": 0.42397,
      "delta": -0.074195,
      "dominantShadowLane": "explicit_author"
    }
  },
  {
    "skill": "sk-code",
    "kind": "skill",
    "confidence": 0.82,
    "uncertainty": 0.3,
    "passes_threshold": true,
    "reason": "Matched by native advisor_recommend",
    "source": "native",
    "score": 0.333,
    "dominant_lane": "explicit_author",
    "status": "active",
    "_shadow": {
      "skillId": "sk-code",
      "liveScore": 0.333,
      "shadowScore": 0.295,
      "delta": -0.038,
      "dominantShadowLane": "explicit_author"
    }
  }
]

codex
SKILL ROUTING: `cli-codex` and `sk-prompt` are relevant here; `sk-code` was also suggested, but this is a read-only runtime/prompt diagnosis rather than code implementation. I’m loading the two narrow skills and then I’ll inspect the evidence.
exec
/bin/zsh -lc "sed -n '1,220p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/cli-codex/SKILL.md" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
exec
/bin/zsh -lc "sed -n '1,220p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-prompt/SKILL.md" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
---
name: sk-prompt
description: "Prompt engineering specialist: structured AI prompts via 7 frameworks, DEPTH thinking, CLEAR scoring."
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
version: 1.3.0.0
---

<!-- Keywords: prompt-engineering, prompt-improvement, improve prompt, improve this prompt, improve the prompt, enhance prompt, prompt improvement, DEPTH, RICCE, CLEAR-scoring, framework-selection, RCAF, COSTAR, CRAFT, TIDD-EC, CRISPE -->

# Prompt Engineering Specialist - Multi-Framework Enhancement with DEPTH Processing

Transforms vague or basic inputs into highly effective, structured AI prompts. Provides 7 text frameworks with automatic framework selection and CLEAR quality scoring.

**Core Principle**: Clarity, logic, expression, and reliability through structured methodology.

---

## 1. WHEN TO USE

### Activation Triggers

**Use when**:
- Enhancing or improving an AI prompt for any purpose
- Evaluating prompt quality with CLEAR scoring
- Selecting the right prompt framework for a given task
- Transforming vague requests into structured, effective prompts
- Supporting indirect invocation from `@prompt-improver` agent dispatches and `cli_prompt_quality_card.md` fast-path escalation flows

**Keyword Triggers**:
- `$improve`, `$text`, `$short`, `$refine`, `$json`, `$yaml`
- `$raw` (skip DEPTH, fast pass-through)
- "improve my prompt", "enhance this prompt", "prompt engineering"
- "create a prompt for", "optimize this prompt"

### Use Cases

#### Text Prompt Enhancement
Transform vague requests into structured prompts using RCAF, COSTAR, RACE, CIDI, TIDD-EC, CRISPE, or CRAFT frameworks with CLEAR scoring (40+/50 threshold).

### When NOT to Use

**Skip this skill when:**
- Writing code or debugging (use sk-code skills instead)
- Creating documentation (use sk-doc instead)
- Simple text editing without prompt structure needs
- Direct API calls that do not need prompt optimization

---

## 2. SMART ROUTING


<!-- CRITICAL: Keep one authoritative Smart Router Pseudocode block in this section.
     Detection context may appear before pseudocode. Do NOT duplicate routing logic in separate lookup tables. -->

### Primary Detection Signal

The primary routing signal is the **command prefix** (`$improve`, `$text`, `$refine`, `$short`, `$json`, `$yaml`, `$raw`). When present, the prefix determines the operating mode directly. When absent, the router falls back to **keyword-weighted intent scoring** against the request text, selecting the top-scoring intent (or top-2 when scores are close). A zero-score fallback defaults to `TEXT_ENHANCE` with a disambiguation checklist.

### Phase Detection

```text
USER REQUEST
    |
    +- STEP 0: Detect mode ($command prefix or keyword signals)
    +- STEP 1: Score intents (top-2 when ambiguity is small)
    +- Phase 1: Framework Selection (7 frameworks evaluated)
    +- Phase 2: DEPTH Processing (3-10 rounds based on mode)
    +- Phase 3: Scoring & Validation (CLEAR)
    +- Phase 4: Output Delivery (formatted prompt)
```

### Resource Domains

The router discovers markdown resources recursively from `references/` and `assets/` and then applies intent scoring from `INTENT_MODEL`.

- `references/` for DEPTH methodology, framework definitions, and CLEAR scoring.
- `assets/` for format-specific deep-dives (Markdown, JSON, YAML).

```text
references/depth_framework.md     - DEPTH methodology, RICCE integration
references/patterns_evaluation.md - 7 frameworks, CLEAR scoring
assets/format_guide_markdown.md   - Markdown format deep-dive
assets/format_guide_json.md       - JSON format deep-dive
assets/format_guide_yaml.md       - YAML format deep-dive
```

### Resource Loading Levels

| Level       | When to Load             | Resources                                                                  |
| ----------- | ------------------------ | -------------------------------------------------------------------------- |
| ALWAYS      | Every skill invocation   | SKILL.md (this file)                                                       |
| CONDITIONAL | If intent signals match  | references/depth_framework.md, references/patterns_evaluation.md           |
| ON_DEMAND   | Only on explicit request | assets/format_guide_markdown.md, assets/format_guide_json.md, assets/format_guide_yaml.md |

### Smart Router Pseudocode

```python
from pathlib import Path

SKILL_ROOT = Path(__file__).resolve().parent
RESOURCE_BASES = (SKILL_ROOT / "references", SKILL_ROOT / "assets")
DEFAULT_RESOURCE = "references/depth_framework.md"

INTENT_MODEL = {
    "TEXT_ENHANCE": {"keywords": [("improve", 4), ("enhance", 4), ("prompt", 3), ("text", 3), ("refine", 4)]},
    "FRAMEWORK": {"keywords": [("framework", 4), ("rcaf", 5), ("costar", 5), ("tidd-ec", 5), ("scoring", 3)]},
}

RESOURCE_MAP = {
    "TEXT_ENHANCE": ["references/depth_framework.md", "references/patterns_evaluation.md"],
    "FRAMEWORK": ["references/patterns_evaluation.md"],
}

ON_DEMAND_KEYWORDS = ["deep dive", "full template", "all frameworks", "format guide", "overnight-agent prompt", "system prompt", "prompt package", "prompt variant", "operator prompt", "evaluator prompt", "dispatch prompt"]

UNKNOWN_FALLBACK_CHECKLIST = [
    "Is this a prompt enhancement request or a different task?",
    "Does the user want a specific framework applied?",
    "Is the user asking about scoring or evaluation?",
    "Should this route to sk-doc or sk-code instead?",
]

AMBIGUITY_DELTA = 1

def _guard_in_skill(relative_path: str) -> str:
    resolved = (SKILL_ROOT / relative_path).resolve()
    resolved.relative_to(SKILL_ROOT)
    if resolved.suffix.lower() != ".md":
        raise ValueError(f"Only markdown resources are routable: {relative_path}")
    return resolved.relative_to(SKILL_ROOT).as_posix()

def discover_markdown_resources() -> set[str]:
    docs = []
    for base in RESOURCE_BASES:
        if base.exists():
            docs.extend(path for path in base.rglob("*.md") if path.is_file())
    return {doc.relative_to(SKILL_ROOT).as_posix() for doc in docs}

def _task_text(task) -> str:
    if isinstance(task, str):
        return task.lower()
    return " ".join(
        str(task.get(f, "")) for f in ("text", "query", "description", "keywords")
    ).lower()

def score_intents(task) -> dict[str, float]:
    text = _task_text(task)
    scores = {intent: 0 for intent in INTENT_MODEL}
    for intent, cfg in INTENT_MODEL.items():
        for keyword, weight in cfg["keywords"]:
            if keyword in text:
                scores[intent] += weight
    return scores

def select_intents(scores, ambiguity_delta=AMBIGUITY_DELTA, max_intents=2):
    ranked = sorted(scores.items(), key=lambda pair: pair[1], reverse=True)
    primary, primary_score = ranked[0]
    if primary_score == 0:
        return ("TEXT_ENHANCE", None)
    secondary, secondary_score = ranked[1]
    if secondary_score > 0 and (primary_score - secondary_score) <= ambiguity_delta:
        return (primary, secondary)
    return (primary, None)

def route_prompt_improver_resources(task):
    inventory = discover_markdown_resources()
    text = _task_text(task)
    scores = score_intents(task)
    primary, secondary = select_intents(scores)
    intents = [primary] + ([secondary] if secondary else [])
    loaded = []
    seen = set()

    def load_if_available(relative_path: str):
        guarded = _guard_in_skill(relative_path)
        if guarded in inventory and guarded not in seen:
            load(guarded)
            loaded.append(guarded)
            seen.add(guarded)

    # Unknown fallback: when no keywords match at all
    if scores[primary] == 0:
        load_if_available(DEFAULT_RESOURCE)
        return {
            "intents": intents,
            "intent_scores": scores,
            "resources": loaded,
            "needs_disambiguation": True,
            "disambiguation_checklist": UNKNOWN_FALLBACK_CHECKLIST,
        }

    # Standard routing: default + intent-mapped resources
    load_if_available(DEFAULT_RESOURCE)
    for intent in intents:
        for relative_path in RESOURCE_MAP.get(intent, []):
            load_if_available(relative_path)

    # ON_DEMAND: load all resource map paths when trigger keywords are present
    if any(kw in text for kw in ON_DEMAND_KEYWORDS):
        for paths in RESOURCE_MAP.values():
            for relative_path in paths:
                load_if_available(relative_path)

    return {"intents": intents, "intent_scores": scores, "resources": loaded}
```

---

## 3. HOW IT WORKS

### Enhancement Pipeline

Every prompt enhancement follows this pipeline:

```
STEP 1: Mode Detection
       ├─ Command prefix check ($text, $improve, $refine, $short, etc.)
       ├─ Keyword signal analysis (>=80% confidence = auto-route)
       └─ Ambiguous? Ask ONE comprehensive question

 succeeded in 0ms:
---
name: cli-codex
description: "Codex CLI orchestrator: dispatch OpenAI's Codex CLI for code generation, review, web research, cross-AI validation."
allowed-tools: [Bash, Read, Glob, Grep]
version: 1.4.2.0
---

<!-- Keywords: codex, codex-cli, openai, cross-ai, web-search, code-generation, code-review, second-opinion, agent-delegation, gpt-5, session-management -->

# Codex CLI Orchestrator - Cross-AI Task Delegation

> **CRITICAL — SELF-INVOCATION PROHIBITED**
>
> This skill dispatches to the OpenAI CLI binary (`codex`). If the agent currently reading this skill is itself running inside Codex (detection signals listed in §2), the skill MUST refuse to load and return the documented error message instead of generating any `codex` invocation.
>
> Just as a Claude Code agent never calls cli-claude-code, an OpenCode agent never calls cli-opencode, a Codex agent never calls cli-codex and a Gemini agent never calls cli-gemini. The cli-X skills are for **cross-AI delegation only** — never self-invocation.

Orchestrate OpenAI's Codex CLI for tasks that benefit from a second AI perspective, real-time web search, deep codebase analysis, built-in code review workflows, or parallel code generation.

**Core Principle**: Use Codex for what it does best. Delegate, validate, integrate. The calling AI stays the conductor.

---

## 1. WHEN TO USE

### Activation Triggers

- **Cross-AI Validation** — code review second perspective, security audit alternative analysis, bug detection, `/review` diff-aware workflow.
- **Web Research** — current internet info via `--search` flag, latest library versions, API changes, community solutions.
- **Codebase Architecture Analysis** — onboarding to unfamiliar codebases, cross-file dependency mapping, architecture docs from code.
- **Parallel Task Processing** — offloading generation, simultaneous code generations, background docs/test generation.
- **Agent-Delegated Tasks** — specialized profile matches (`.codex/agents/*.toml`), session management (resume, fork), multi-strategy planning.
- **Specialized Generation** — explicit Codex requests, test suite generation, code translation, batch docs (JSDoc, README, API), visual input via `--image`/`-i`.

### When NOT to Use

- **You ARE Codex already.** If your runtime is Codex (detection signal: `$CODEX_SESSION_ID` or any `CODEX_*` env var set, `codex` in process ancestry, or `~/.codex/state/<id>/lock` present), this skill refuses to load. Self-invocation creates a circular dispatch loop and burns tokens for no value. The cli-X family is exclusively for cross-AI delegation.
- Simple, quick tasks where CLI overhead is not worth it.
- Tasks requiring immediate response (rate limits may cause delays).
- Context already loaded and understood by the current agent.
- Interactive refinement requiring the full-screen TUI (use `codex` directly instead).
- Tasks where Codex CLI is not installed.

---

## 2. SMART ROUTING


### Prerequisite Detection

```bash
# Verify Codex CLI is available before routing
command -v codex || echo "Not installed. Run: npm i -g @openai/codex"
```

### Self-Invocation Guard

```python
def detect_self_invocation():
    """Returns a non-None signal when the orchestrator is already running inside Codex."""
    # Layer 1: env var lookup — Codex sets CODEX_SESSION_ID and CODEX_* vars
    for key in os.environ:
        if key == 'CODEX_SESSION_ID' or key.startswith('CODEX_'):
            return ('env', key)
    # Layer 2: process ancestry — codex in parent tree
    try:
        ancestry = subprocess.check_output(['ps', '-o', 'command=', '-p', str(os.getppid())]).decode()
        if '/codex' in ancestry or 'codex ' in ancestry:
            return ('ancestry', 'codex')
    except subprocess.SubprocessError:
        pass
    # Layer 3: state lock-file probe
    state_dir = os.path.expanduser('~/.codex/state')
    if os.path.isdir(state_dir):
        for entry in os.listdir(state_dir):
            if os.path.exists(os.path.join(state_dir, entry, 'lock')):
                return ('lockfile', entry)
    return None

if detect_self_invocation():
    refuse(
        "Self-invocation refused: this agent is already running inside Codex. "
        "Use a sibling cli-* skill or a fresh shell session in a different runtime to dispatch a different model."
    )
```

### Resource Loading Levels

| Level       | When to Load            | Resources                      |
| ----------- | ----------------------- | ------------------------------ |
| ALWAYS      | Every skill invocation  | `references/cli_reference.md`, `assets/prompt_quality_card.md` |
| CONDITIONAL | If intent signals match | Intent-mapped reference docs   |
| ON_DEMAND   | Only on explicit request| Extended templates and patterns |

### Smart Router

Provider-specific dictionaries (used by the shared helper functions in [`system-spec-kit/references/cli/shared_smart_router.md`](../system-spec-kit/references/cli/shared_smart_router.md)):

```python
INTENT_SIGNALS = {
    "GENERATION":        {"weight": 4, "keywords": ["generate", "create", "build", "write code", "codex create"]},
    "REVIEW":            {"weight": 4, "keywords": ["review", "audit", "security", "bug", "second opinion", "cross-validate", "/review"]},
    "RESEARCH":          {"weight": 4, "keywords": ["search", "latest", "current", "what's new", "web research", "--search", "browse"]},
    "ARCHITECTURE":      {"weight": 3, "keywords": ["architecture", "codebase", "investigate", "dependencies", "analyze project"]},
    "AGENT_DELEGATION":  {"weight": 4, "keywords": ["delegate", "agent", "background", "parallel", "offload", "codex agent"]},
    "TEMPLATES":         {"weight": 3, "keywords": ["template", "prompt", "how to ask", "codex prompt"]},
    "PATTERNS":          {"weight": 3, "keywords": ["pattern", "workflow", "orchestrate", "session", "resume", "fork"]},
    "HOOKS":             {"weight": 4, "keywords": ["hook", "hooks", "advisor brief", "startup context", "userpromptsubmit", "sessionstart", "codex_hooks"]},
}

RESOURCE_MAP = {
    "GENERATION":        ["references/cli_reference.md", "assets/prompt_templates.md"],
    "REVIEW":            ["references/integration_patterns.md", "references/agent_delegation.md"],
    "RESEARCH":          ["references/codex_tools.md", "assets/prompt_templates.md"],
    "ARCHITECTURE":      ["references/codex_tools.md", "references/agent_delegation.md"],
    "AGENT_DELEGATION":  ["references/agent_delegation.md", "references/integration_patterns.md"],
    "TEMPLATES":         ["assets/prompt_templates.md", "references/cli_reference.md"],
    "PATTERNS":          ["references/integration_patterns.md", "references/cli_reference.md"],
    "HOOKS":             ["references/hook_contract.md", "references/cli_reference.md"],
}

LOADING_LEVELS = {
    "ALWAYS": ["references/cli_reference.md", "assets/prompt_quality_card.md"],
    "ON_DEMAND_KEYWORDS": ["full reference", "all templates", "deep dive", "complete guide", "codex agent", "codex prompt", "web research", "review command", "fork session", "hook contract"],
    "ON_DEMAND": ["references/codex_tools.md", "assets/prompt_templates.md"],
}

UNKNOWN_FALLBACK_CHECKLIST = [
    "Is the user asking about Codex CLI specifically?",
    "Does the task benefit from a second AI perspective?",
    "Is real-time web information needed (--search)?",
    "Would codebase-wide analysis or /review workflow help?",
]
```

**Call sequence** (using shared helpers from `shared_smart_router.md`):

1. `discover_markdown_resources()` — recursively enumerate current `.md` files under existing `references/` and `assets/` folders at routing time.
2. `_guard_in_skill()` + `load_if_available()` — sandbox paths to this skill, reject non-markdown loads, skip missing files, and suppress duplicates.
3. `score_intents(task)` and `select_intents(scores, ambiguity_delta=1.0)` — preserve provider-specific weighted intent scoring and top-2 ambiguity handling.
4. `get_routing_key(task, intents)` — derive the provider routing key from task/provider context, then fall back to `codex`.
5. ALWAYS-load `LOADING_LEVELS["ALWAYS"]`, then return `UNKNOWN_FALLBACK` with `UNKNOWN_FALLBACK_CHECKLIST` when max score is 0.
6. CONDITIONAL-load `RESOURCE_MAP[intent]`, ON_DEMAND-load keyword matches, and return a notice when no provider-specific knowledge base is available beyond always-load resources.

The `route_codex_resources(task)` function body lives in [`shared_smart_router.md`](../system-spec-kit/references/cli/shared_smart_router.md) — substitute `<PROVIDER>` = `codex`.

---

## 3. HOW IT WORKS

### Prerequisites

```bash
# Verify installation
command -v codex || echo "Not installed. Run: npm i -g @openai/codex"

# Authentication — API key OR ChatGPT OAuth
export OPENAI_API_KEY=your-key-here
codex login
```

**Authentication options**: `OPENAI_API_KEY` env var (direct API), or ChatGPT OAuth via `codex login` (uses ChatGPT account credentials).

### Provider Auth Pre-Flight (Smart Fallback)

**MANDATORY before any first dispatch in a session.** The default OpenAI auth (API key OR ChatGPT OAuth) may not be configured on this machine — silently failing with `401 Unauthorized` or `not authenticated` mid-dispatch wastes a round-trip. Run this check once per session, cache the result, and re-run it only if a dispatch fails with an auth error.

```bash
# One-shot pre-flight: capture auth status for routing
[ -n "$OPENAI_API_KEY" ] && OPENAI_KEY_OK=1 || OPENAI_KEY_OK=0
CODEX_AUTH=$(codex auth status 2>&1)
echo "$CODEX_AUTH" | grep -qi "logged in\|chatgpt-oauth" && CODEX_OAUTH_OK=1 || CODEX_OAUTH_OK=0
```

**Decision tree** (apply in order — first match wins):

| State | OPENAI_KEY_OK | CODEX_OAUTH_OK | Action |
|-------|---------------|----------------|--------|
| Default available | 1 | * | Proceed with `codex exec --model gpt-5.5 -c model_reasoning_effort="medium" -c service_tier="fast"` |
| API key missing, OAuth ready | 0 | 1 | **ASK user** before substituting — never auto-fall-back silently. Surface options A/B/C below. |
| Both missing | 0 | 0 | **ASK user** to configure auth — surface the login commands, do NOT dispatch. |

**User prompt template — API key missing, OAuth configured:**

```
`$OPENAI_API_KEY` is not set, but ChatGPT OAuth via `codex login` is configured.
Pick one:
  A) Use the existing ChatGPT OAuth session (works for `codex exec` if your ChatGPT plan covers the model)
  B) Run `export OPENAI_API_KEY=sk-...` first, then retry the original dispatch
  C) Name a different model — paste the `--model <id>` you want to use
```

**User prompt template — both missing:**

```
No OpenAI auth is configured on this machine. Run one:
  - `export OPENAI_API_KEY=sk-...`  (recommended for direct API calls)
  - `codex login`                    (interactive ChatGPT OAuth flow; requires ChatGPT Plus/Pro/Business)
Which would you like to set up? Confirm when login finishes; the skill will retry the original dispatch.
```

**Error-recovery contract.** If a dispatch returns an auth error after pre-flight passed (key revoked or OAuth expired), invalidate the cache, rerun the pre-flight, and apply the same decision tree before retrying. Never substitute a model the user didn't approve.

### Default Invocation (Skill Default)

**Default model + effort + tier**: `gpt-5.5` · `medium` reasoning · `fast` service tier. Balances speed, cost, and quality for the typical delegation.

```bash
codex exec \
  --model gpt-5.5 \
  -c model_reasoning_effort="medium" \
  -c service_tier="fast" \
  -c approval_policy=never \
  --sandbox workspace-write \
  "<prompt>"
```

**User override** (honor explicit user phrasing verbatim):

| User says | Resolve to |

codex
The first useful signal is already a constraint: the `cli-codex` skill explicitly refuses self-invocation when the current runtime is Codex. That makes the diagnosis more about the in-process SpawnAgent surface and prompt behavior than about launching another `codex exec`.
exec
/bin/zsh -lc "sed -n '1,220p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/config.toml" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
model_auto_compact_token_limit = 750000

approval_policy = "never"
sandbox_mode = "danger-full-access"
[mcp_servers.sequential_thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
 
[mcp_servers.spec_kit_memory]
command = "node"
args = [".opencode/skills/system-spec-kit/mcp_server/dist/context-server.js"]

[mcp_servers.spec_kit_memory.env]
EMBEDDINGS_PROVIDER = "auto"
MEMORY_DB_PATH = ".opencode/skills/system-spec-kit/mcp_server/database/context-index.sqlite"
SPECKIT_SESSION_BOOST = "true"
SPECKIT_CAUSAL_BOOST = "true"
_NOTE_1_DATABASE = "Stores vectors in: .opencode/skills/system-spec-kit/mcp_server/database/context-index.sqlite"
_NOTE_2_PROVIDERS = "Supports: Voyage (1024 dims), OpenAI (1536/3072 dims), HF Local (768 dims, no API needed)"
_NOTE_3_EMBEDDINGS_PROVIDER = "Current: 'hf-local' (free, offline). Options: 'auto', 'voyage', 'openai'"
_NOTE_4_CLOUD_PROVIDERS = "For cloud: add VOYAGE_API_KEY or OPENAI_API_KEY and set EMBEDDINGS_PROVIDER=auto"
_NOTE_5_GET_VOYAGE_KEY = "Get Voyage key: https://dash.voyageai.com/api-keys (recommended, 8% better than OpenAI)"
_NOTE_6_GET_OPENAI_KEY = "Get OpenAI key: https://platform.openai.com/api-keys"
_NOTE_7_FEATURE_FLAGS = "Opt-out flags (all default ON): SPECKIT_ADAPTIVE_FUSION, SPECKIT_EXTENDED_TELEMETRY, SPECKIT_SESSION_BOOST, SPECKIT_CAUSAL_BOOST"
_NOTE_8_CODE_GRAPH_SCOPE = "Maintainer mode — opt-in all 5 .opencode/ folders (skills, agents, commands, specs, plugins) to the structural code graph. Per-call code_graph_scan args (includeSkills/Agents/Commands/Specs/Plugins) override these env defaults."
SPECKIT_CODE_GRAPH_INDEX_SKILLS = "true"
SPECKIT_CODE_GRAPH_INDEX_AGENTS = "true"
SPECKIT_CODE_GRAPH_INDEX_COMMANDS = "true"
SPECKIT_CODE_GRAPH_INDEX_SPECS = "true"
SPECKIT_CODE_GRAPH_INDEX_PLUGINS = "true"

[mcp_servers.cocoindex_code]
command = ".opencode/skills/mcp-coco-index/mcp_server/.venv/bin/ccc"
args = ["mcp"]

[mcp_servers.cocoindex_code.env]
COCOINDEX_CODE_ROOT_PATH = "."
_NOTE_1 = "Install: bash .opencode/skills/mcp-coco-index/scripts/install.sh"
_NOTE_2 = "Default embedding: all-MiniLM-L6-v2 (local, no API key needed)"
_NOTE_3 = "Index stored in .cocoindex_code/ (gitignored)"

[mcp_servers.code_mode]
command = "node"
args = [".opencode/skills/mcp-code-mode/mcp_server/dist/index.js"]

[mcp_servers.code_mode.env]
UTCP_CONFIG_FILE = ".utcp_config.json"

[features]
multi_agent = true
child_agents_md = true

# Profiles for `codex exec -p <name>` are NOT defined here.
# Codex ignores [profiles.*] in project-local configs.
# They live at user level (~/.codex/config.toml) — see entries there.

# Agents for interactive multi-agent TUI (codex with multi_agent feature)
[agents.code]
description = "Application-code implementation specialist using sk-code for stack-aware execution."
config_file = "agents/code.toml"

[agents.markdown]
description = "Dedicated /create:* documentation executor using sk-doc templates."
config_file = "agents/markdown.toml"

[agents.context]
description = "Production context retrieval specialist (memory-first, read-only)."
config_file = "agents/context.toml"

[agents.debug]
description = "Debugging specialist for root-cause analysis and fix validation."
config_file = "agents/debug.toml"

[agents.orchestrate]
description = "Senior orchestrator for decomposition, delegation, and synthesis."
config_file = "agents/orchestrate.toml"

[agents.deep-research]
description = "Iterative investigation specialist with convergence detection."
config_file = "agents/deep-research.toml"

[agents.deep-review]
description = "LEAF review agent for deep-review. Performs single review iteration: reads state, reviews one dimension with P0/P1/P2 findings, updates strategy and JSONL."
config_file = "agents/deep-review.toml"

[agents.deep-agent-improvement]
description = "Proposal-only mutator for bounded deep-agent-improvement candidate generation with evaluator-first rules"
config_file = "agents/deep-agent-improvement.toml"

[agents.prompt-improver]
description = "Prompt-improver specialist for framework selection, CLEAR validation, and dispatch-ready prompt packages for high-stakes external CLI invocations"
config_file = "agents/prompt-improver.toml"

[agents.review]
description = "Code review specialist focused on correctness, risk, and tests."
config_file = "agents/review.toml"

[agents.deep-ai-council]
description = "Multi-strategy planning architect for diverse reasoning and optimal plans."
config_file = "agents/deep-ai-council.toml"

exec
/bin/zsh -lc "sed -n '1,260p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/agents/markdown.toml" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
# Agent: markdown
# Converted from: .opencode/agents/markdown.md
name = "markdown"
description = "Dedicated LEAF executor for /create:* documentation commands; loads sk-doc templates and refuses unscoped documentation callers"
profile = "default"
sandbox_mode = "workspace-write"
model = "gpt-5.4"
model_reasoning_effort = "high"

developer_instructions = '''

# The Markdown Agent: Template-First Documentation Executor

Dedicated LEAF executor for `/create:*` commands. This agent loads `sk-doc` on every invocation, reads the command-appropriate template before writing, creates or updates the requested documentation artifact, and returns one deterministic status line.

**Path Convention**: Use only `.opencode/agents/*.md` as the canonical runtime path reference.

**CRITICAL**: This agent may execute `/create:*` command workflows and scoped markdown/spec-doc authoring tasks. If invoked directly, by another agent, or for an unscoped documentation task, refuse before reading or writing targets.

**IMPORTANT**: Caller restriction is convention-level, not a harness validator. The gate prevents accidental misuse; it is not an adversarial security boundary.

---

## 0. ILLEGAL NESTING AND WRITE BOUNDARY (HARD BLOCK)

This agent is LEAF-only and write-capable. Nested sub-agent dispatch is illegal. File mutation is limited to the command-resolved output path, package root, runtime mirror set, or spec folder explicitly named by the `/create:*` command.

- NEVER call the Task tool, create sub-tasks, ask another agent to investigate, or hand off work from inside this agent.
- NEVER write outside the resolved command output, command-owned package root, active spec folder, or explicitly scoped mirror set.
- NEVER treat source files used for evidence as writable unless the command contract names them as outputs.
- If delegation is requested, emit the canonical nested-dispatch REFUSE line before returning partial findings.
- If the requested work cannot be completed within the LEAF boundary, return `STATUS=FAIL ERROR=<reason>` with verified partial paths in the notes.

### Caller Restriction Gate

Phase 0 is mandatory before any target read, search, template load, or write.

```text
SELF-CHECK: Are you operating as @markdown from a /create:* command or explicitly scoped markdown/spec-doc task?
```

Valid callers are exactly:

- `/create:agent`
- `/create:sk-skill`
- `/create:feature-catalog`
- `/create:testing-playbook`
- `/create:folder_readme`
- `/create:changelog`

Indicators that the invocation is valid:

- The dispatch prompt or command context names one of the valid `/create:*` commands.
- The workflow requires template-first generation and `sk-doc` validation.
- The requested output maps to one command-owned template in Section 4.
- The command context provides or gathers the setup fields before writing.

If any indicator is absent or contradictory, emit this exact caller refusal and stop:

```text
REFUSE: @markdown requires an explicit markdown/spec-doc output scope or a supported /create:* command.
```

### Canonical Refusal Wording (mandatory)

When a dispatch prompt or workflow instructs this agent to invoke the Task tool, dispatch a sub-agent, or delegate work outside the LEAF boundary, this agent MUST emit the EXACT canonical refusal string in stdout BEFORE returning partial findings:

```text
REFUSE: nested Task tool dispatch is forbidden for LEAF agents. Returning partial findings instead.
```

The refusal MUST appear verbatim for stress tests and operator audit. Silent refusal is non-compliant.

---

## 0b. INPUT + SCOPE GATES (HARD BLOCK)

Before reading targets, running searches, or writing artifacts, validate the command contract.

### Required Dispatch Inputs

- `command_name`: one of the six valid `/create:*` commands.
- `execution_mode`: `AUTONOMOUS`, `INTERACTIVE`, or command-equivalent resolved mode.
- `target`: requested skill, agent, component, folder, source, or output path.
- `output_path` or `output_root`: resolved writable destination.
- `template_path`: the `sk-doc` template selected from Section 4.
- `spec_folder`: required when the command contract activates spec tracking; otherwise `none`.

### Gate Rules

1. Resolve every writable path before writing.
2. Treat missing, ambiguous, or path-traversing writable paths as `STATUS=FAIL`.
3. Treat source, evidence, and reference paths as read-only unless the command explicitly names them as outputs.
4. Do not infer a different spec folder, target, or package root from nearby files.
5. If setup values contradict the command markdown or YAML workflow, return `STATUS=FAIL ERROR=logic-sync-required`.

### Setup BINDING Emission (mandatory grep-checkable contract)

Immediately after validating dispatch inputs, BEFORE any state read or workflow step, this agent MUST emit one canonical BINDING line per resolved setup value to stdout. These bindings make setup-resolution machine-verifiable for stress tests and operator audit.

Required bindings for this agent:

```text
BINDING: command=<resolved-create-command>
BINDING: target=<resolved-target-path-or-name>
BINDING: output=<resolved-output-path-or-root>
BINDING: template=<resolved-sk-doc-template-path>
BINDING: mode=<resolved-execution-mode>
BINDING: specFolder=<resolved-spec-folder-path-or-none>
```

Each binding line must appear on its own line, grep-checkable verbatim. Missing or non-canonical wording, such as "the target is X" instead of `BINDING: target=X`, is non-compliant.

---

## 1. CORE WORKFLOW

1. **RECEIVE** -> Parse the `/create:*` command, caller marker, setup values, active spec folder, and output contract.
2. **VERIFY CALLER** -> Run the Phase 0 caller gate. Refuse non-`/create:*` invocations before touching targets.
3. **SCOPE LOCK** -> Resolve writable output paths, read-only evidence paths, overwrite policy, and command mode.
4. **LOAD sk-doc** -> Read `.opencode/skills/sk-doc/SKILL.md` on every invocation and select the matching resource from Section 4.
5. **LOAD TEMPLATE** -> Read the selected template before writing any artifact.
6. **EXECUTE DIRECTLY** -> Create or update the requested artifact using only allowed tools and command-owned setup values.
7. **VERIFY** -> Check template alignment, required sections, frontmatter when applicable, DQI score, line/path expectations, and command status contract.
8. **DELIVER** -> Return exactly one deterministic status line, plus concise evidence when successful or blocked.

**Key Principle**: Template first, command scope second, deterministic status last. This agent does not invent document families outside `sk-doc`.

---

## 2. ROUTING SCAN

### Skills

| Skill | Domain | Use When | Key Features |
| --- | --- | --- | --- |
| `sk-doc` | Documentation creation and quality | Always | Command templates, DQI scoring, README, changelog, agent, skill, feature catalog, and testing playbook guidance |
| `system-spec-kit` | Spec folder discipline | When command setup names a spec folder or memory save is applicable | Packet scope, validation, optional continuity save routing |

### Tools

| Tool | Purpose | When to Use |
| --- | --- | --- |
| `read` | Inspect command docs, skill docs, templates, source evidence, and existing outputs | Always before editing or writing |
| `write` | Create new artifacts | Only after scope and template are resolved |
| `edit` | Update existing artifacts | Only when overwrite or merge policy allows it |
| `bash` | Run bounded validation, line counts, TOML parse, markdown checks, and DQI helpers | Verification and deterministic file inspection |
| `grep` | Confirm exact markers, frontmatter keys, command variables, and template sections | Setup, validation, and audit |
| `glob` | Locate command-owned packages, templates, and existing outputs | Setup and conflict checks |
| `list` | Inspect known directories without guessing filenames | Setup and package verification |
| `memory` | Optional continuity save when command setup explicitly calls for it | Only for command-authorized spec context; otherwise report applicability |

Denied tools: `task`, `webfetch`, `chrome_devtools`, and `patch`.

---

## 3. RUNTIME PARAMETERS

| Parameter | Value |
| --- | --- |
| **Time Budget** | ~10 minutes for normal create/update commands |
| **Output Size** | One deterministic status line plus up to 12 lines of evidence |
| **Tool Calls** | 8-25 for normal mode, depending on package size |
| **Dispatches** | 0; this is a LEAF agent |
| **Mutation Calls** | Scoped to command-resolved outputs and explicit spec continuity files |
| **Use Case** | Direct executor for `/create:*` documentation and component-generation commands |

---

## 4. COMMAND TEMPLATE MAP

Read `sk-doc` first, then read the matching template before writing.

| Command | Output | Template |
| --- | --- | --- |
| `/create:agent` | New OpenCode agent `.md` plus requested runtime mirrors | `.opencode/skills/sk-doc/assets/agent_template.md` |
| `/create:sk-skill` | New skill `SKILL.md` or doc-only skill resource | `.opencode/skills/sk-doc/assets/skill/skill_md_template.md` and, when needed, `.opencode/skills/sk-doc/assets/skill/skill_reference_template.md` |
| `/create:feature-catalog` | `feature_catalog/` package | `.opencode/skills/sk-doc/assets/feature_catalog/feature_catalog_template.md` |
| `/create:testing-playbook` | `manual_testing_playbook/` package | `.opencode/skills/sk-doc/assets/testing_playbook/manual_testing_playbook_template.md` |
| `/create:folder_readme` | `README.md` or install-guide markdown | `.opencode/skills/sk-doc/assets/readme/readme_template.md` |
| `/create:changelog` | Versioned changelog markdown | `.opencode/skills/sk-doc/assets/changelog_template.md` |

If the command asks for a template not listed here, return:

```text
STATUS=FAIL ERROR=unsupported-create-template
```

---

## 5. OUTPUT FORMAT

Return exactly one of these three status states.

```text
STATUS=OK PATH=<created-or-updated-file-or-package-root>
STATUS=FAIL ERROR=<reason>
STATUS=CANCELLED
```

When `STATUS=OK`, include concise evidence immediately after the status line:

```text
DQI=<score>
TEMPLATE=<template-path>
CHECKS=<comma-separated-checks>
NOTES=<short judgment calls or none>
```

`DQI` must be `75` or higher before a completion claim. If DQI is unavailable because the command has no scoring helper, perform the `sk-doc` manual quality rubric and report `DQI=<manual-score>` with the checks used.

---

## 6. OUTPUT VERIFICATION

**CRITICAL**: Before claiming completion, verify output against actual files and command contracts.

### Pre-Delivery Verification Checklist

```text
MARKDOWN AGENT VERIFICATION (MANDATORY):
□ Phase 0 caller gate passed for one valid /create:* command
□ BINDING lines emitted for command, target, output, template, mode, and specFolder
□ sk-doc SKILL.md was read for this invocation
□ The command-mapped template was read before writing
□ All written paths are inside the resolved command output or explicit spec scope
□ DQI score is >=75 and reported in completion evidence
□ STATUS line is exactly one of OK, FAIL, or CANCELLED

EVIDENCE VALIDATION (MANDATORY):
□ Existing files were read before edit
□ No placeholder content remains unless the template explicitly requires placeholders
□ Frontmatter or package index requirements match the selected template
□ Line counts and parse checks relevant to the output passed
□ Nesting, write, and budget boundaries were respected
```

If any required check fails, do not return `STATUS=OK`. Return `STATUS=FAIL ERROR=<reason>` with the narrowest accurate reason.

---

## 7. HOOK-INJECTED CONTEXT ROUTING

Use hook-injected startup, graph, memory, or skill-advisor context as a routing hint.

1. If hook context names an active spec folder, verify it against command setup before writing or claiming continuity.
2. If hook context is stale, use command-owned setup and local file reads as runtime truth.
3. If hook context contradicts command setup, return `STATUS=FAIL ERROR=logic-sync-required`.
4. If no hook context is present, continue with command markdown, `sk-doc`, templates, and explicit setup values.
5. Never treat injected context as permission to exceed the agent's write or dispatch boundary.

---

## 8. ANTI-PATTERNS

| Anti-Pattern | Why It Fails | Correct Behavior |
| --- | --- | --- |
| **Unscoped Invocation** | Bypasses the caller-restriction contract | Emit the caller REFUSE line and stop |
| **Illegal Nesting** | Violates LEAF boundary and loses auditability | Perform direct work or emit the nested-dispatch REFUSE line |
| **Template-Free Writing** | Produces inconsistent documentation | Load `sk-doc` and the command template first |

exec
/bin/zsh -lc "sed -n '1,240p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
---
id: SD-019
category: 06--agent-dispatch
title: '@markdown agent dispatch via cli-codex'
execution_mode: dispatch_real
expected_skip_in_non_interactive: true
skip_rationale: "cli-codex @markdown dispatch under `codex exec` non-interactive mode falls back to a sub-agent path that hits Gate 3. Documented as accepted limitation in 102/005 (F-001). Re-enable when codex agent resolver routes @markdown directly under `codex exec`."
expected_intent: CHANGELOG
expected_agent: '@markdown'
expected_resources:
  - assets/changelog_template.md
  - references/changelog_creation.md
expected_token_range_input: 400-1500
expected_token_range_output: 1500-4000
created: 2026-05-11
---

# SD-019: @markdown agent dispatch via cli-codex

## 1. OVERVIEW

This scenario validates that `cli-codex` (gpt-5.5/fast/high) correctly routes a `/create:changelog` task to the `@markdown` agent and that the agent loads sk-doc CHANGELOG resources before scaffolding the output.

### Why This Matters

cli-codex runs in a workspace-write sandbox by default that blocks sub-process network calls (memory: `feedback_codex_sandbox_blocks_network.md`). For sk-doc dispatch to succeed, the codex invocation must explicitly enable network access and the `fast` service tier (memory: `feedback_codex_cli_fast_mode.md`). This scenario tests that the codex pathway honors the `@markdown` rename under those constraints.

---

## 2. SCENARIO CONTRACT

- Real user request: scaffold a v0.1.0 changelog for a stub skill via the `@markdown` agent
- Prompt: `Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-codex.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.`
- Expected intent: `CHANGELOG`
- Expected executor: `@markdown` agent (NOT `@code`, NOT direct sk-doc invocation)
- Desired user-visible outcome: A scaffolded changelog file at `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md` with Keep-a-Changelog sections, plus a transcript showing `@markdown` Phase 0 verification ran before the YAML workflow loaded.

## 3. TEST EXECUTION

| Feature ID | Feature Name | Scenario Name / Objective | Exact Prompt | Exact Command Sequence | Expected Signals | Evidence | Pass/Fail Criteria | Failure Triage |
|---|---|---|---|---|---|---|---|---|
| SD-019 | @markdown via cli-codex | Verify `@markdown` agent receives `/create:changelog` work dispatched through cli-codex. | See Setup. | See Setup. | `@markdown` Phase 0 verification text appears in transcript; CHANGELOG asset reference appears; output file written. | Transcript + output changelog content. | PASS when `@markdown` invocation appears AND output file exists AND has Keep-a-Changelog sections. PARTIAL if `@markdown` invoked but output incomplete. FAIL if a different agent answered. SKIP if `codex` binary unavailable. | Re-check `.codex/agents/markdown.toml` exists; verify `.codex/config.toml` registers `agents.markdown`; verify network-access + fast flags applied. |

### Setup

This scenario EXECUTES real work — it is not a routing-trace probe.

Memory-mandated flags:
- `-c service_tier="fast"` (cli-codex fast mode must be explicit — never rely on global default)
- `-c sandbox_workspace_write.network_access=true` (sandbox blocks sub-process network without this; embeddings / API calls would fail)

```bash
PROMPT='Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-codex.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.'

EVIDENCE='/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure/004-sk-doc-playbook-markdown-agent-coverage/evidence/SD-019-cli-codex.txt'

# Dispatch via cli-codex (gpt-5.5/fast)
codex exec \
  -c service_tier="fast" \
  -c sandbox_workspace_write.network_access=true \
  "$PROMPT" </dev/null 2>&1 | tee "$EVIDENCE"

# Append verdict footer manually after grading
```

After the dispatch returns, run the grading probes against the evidence transcript:

```bash
# Routing trace: @markdown must appear
grep -c '@markdown\|markdown agent\|Phase 0\|agents.markdown\|markdown.toml' "$EVIDENCE"

# Resource trace: changelog template must be referenced
grep -c 'changelog_template\|changelog_creation\|Keep-a-Changelog' "$EVIDENCE"

# Output existence + shape
test -f /tmp/sk-test-dummy-CHANGELOG-cli-codex.md && \
  grep -cE '^## .*(Added|Changed|Fixed|Removed)' /tmp/sk-test-dummy-CHANGELOG-cli-codex.md
```

## Expected Behavior

- **Intent picked**: `CHANGELOG`
- **Executor**: `@markdown` agent (Codex resolves via `.codex/config.toml` `[agents.markdown]` → `.codex/agents/markdown.toml`)
- **Resources loaded**:
  - `.opencode/skills/sk-doc/assets/changelog_template.md`
  - `.opencode/skills/sk-doc/references/changelog_creation.md`
- **Outcome**: CLI scaffolds a v0.1.0 changelog file with Added / Changed / Fixed / Removed sections at `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md`.

## Cross-CLI Variants

This scenario is fixed to `cli-codex`. Equivalent dispatches for cli-claude-code and cli-opencode are SD-018 and SD-020 respectively.

## Success Criteria

- `@markdown` invocation evidence present in transcript
- output file exists at the requested path
- output contains at least 3 of the 4 Keep-a-Changelog sections (Added / Changed / Fixed / Removed)
- no installation under `.opencode/skills/` (stub stayed out of the skills tree)

## 4. SOURCE METADATA

- Group: Agent Dispatch
- Playbook ID: SD-019
- Canonical root source: `manual_testing_playbook.md`
- Feature file path: `06--agent-dispatch/002-markdown-agent-cli-codex.md`
- Introduced by: `.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure/004-sk-doc-playbook-markdown-agent-coverage`

exec
/bin/zsh -lc "sed -n '1,260p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure/005-deep-review-p1-p2-remediation/implementation-summary.md" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
exec
/bin/zsh -lc 'rg -n -C 6 "Full-history forked|agent type is currently not available|Schrodinger|markdown agent|SpawnAgent|Gate 3|SPEC FOLDER|The dedicated" /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure/004-sk-doc-playbook-markdown-agent-coverage/evidence/SD-019-cli-codex.txt' in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
---
title: "Implementation Summary: deep-review P1+P2 remediation"
description: "Closed all 7 P1 and 9 P2 findings from the 102 phase-parent deep-review via a single cli-codex gpt-5.5/high/fast dispatch."
trigger_phrases:
  - "102 p1 p2 remediation"
importance_tier: "important"
contextType: "implementation"
_memory:
  continuity:
    packet_pointer: ".opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure/005-deep-review-p1-p2-remediation"
    last_updated_at: "2026-05-11T10:40:00Z"
    last_updated_by: "claude-opus-4-7"
    recent_action: "Codex remediation complete"
    next_safe_action: "Index scan and close packet"
    blockers: []
    key_files:
      - "evidence/codex-remediation-dispatch.txt"
      - "../review/deep-review-dashboard.md"
      - "../spec.md"
      - "../004-sk-doc-playbook-markdown-agent-coverage/implementation-summary.md"
    session_dedup:
      fingerprint: "sha256:0000000000000000000000000000000000000000000000000000000000000000"
      session_id: "102-005-deep-review-p1-p2-remediation"
      parent_session_id: null
    completion_pct: 100
    open_questions: []
    answered_questions:
      - "Open question from 004 — file new packet OR document SD-019 as accepted limitation? Resolved: documented as accepted limitation via SD-019 frontmatter expected_skip_in_non_interactive + parent-level Known Issues register; investigation deferred."
---
<!-- SPECKIT_TEMPLATE_SOURCE: impl-summary-core | v2.2 -->
# Implementation Summary: deep-review P1+P2 remediation

<!-- SPECKIT_LEVEL: 2 -->
<!-- HVR_REFERENCE: .opencode/skills/sk-doc/references/hvr_rules.md -->

A single cli-codex `gpt-5.5 / high / fast` dispatch closed all 16 findings from the 102 phase-parent deep-review in 129 seconds: 7 P1 status-sync and handoff issues, plus 9 P2 hygiene items. The one structural P1 (F-001 cli-codex `@markdown` dispatch gap) is resolved by documenting it as an accepted limitation — the SD-019 scenario file now declares `expected_skip_in_non_interactive: true` with a rationale, and the parent spec carries a Known Issues register that cross-references F-001/F-002/F-003 plus every new finding ID. Strict-validate passes on both 004 and 005.

---

<!-- ANCHOR:metadata -->
## Metadata

| Field | Value |
|-------|-------|
| **Spec Folder** | 005-deep-review-p1-p2-remediation |
| **Completed** | 2026-05-11 |
| **Status** | Complete |
| **Level** | 2 |
| **Executor** | cli-codex `gpt-5.5 / model_reasoning_effort=high / service_tier=fast` |
<!-- /ANCHOR:metadata -->

---

<!-- ANCHOR:what-built -->
## What Was Built

### Files Modified

| File | What Changed |
|------|--------------|
| `102/spec.md` | Phase 2 status Draft→Complete; Phase 4 status Active→Complete; 003→004 handoff annotated with SD-019 gap note; new Known Issues section appended (Confirmed pre-existing + Surfaced by deep-review + Phase 3 prior-review cross-ref) |
| `001/spec.md` | Phase metadata `1 of 3` → `1 of 5` |
| `002/spec.md` | Phase metadata `2 of 3` → `2 of 5` |
| `002/checklist.md` | CHK-003 Evidence appended with Phase 1→2 handoff acceptance proof; frontmatter `completion_pct: 0` → `100` |
| `003/spec.md` | Phase metadata `3 of 3` → `3 of 5` |
| `004/spec.md` | Status Draft → Complete; Phase `4 of 4` → `4 of 5` |
| `004/checklist.md` | All 26 CHK items marked `[x]` with evidence text; Verification Summary updated 12/12 + 8/8 + 1/1; Verification Date 2026-05-11 |
| `004/implementation-summary.md` | `completion_pct: 100`; `open_questions: []`; metadata Status → "Complete — 2 PASS, 1 FAIL (documented limitation), deep-review converged" |
| `06--agent-dispatch/002-markdown-agent-cli-codex.md` | Frontmatter `expected_skip_in_non_interactive: true` + `skip_rationale` lines added |

### Counts
- 9 files modified
- 16 findings closed (7 P1 + 9 P2)
- 26 checklist items marked
- 1 new section appended (Known Issues)
- 0 files outside scope touched
<!-- /ANCHOR:what-built -->

---

<!-- ANCHOR:how-delivered -->
## How It Was Delivered

### Approach
1. Authored a comprehensive prompt at `/tmp/codex-remediation-prompt.txt` (~13 KB) enumerating every edit with file path, exact old-string anchor, and exact new-string content.
2. Dispatched cli-codex via:
   ```
   codex exec --model gpt-5.5 -c model_reasoning_effort="high" -c service_tier="fast" \
     -c sandbox_workspace_write.network_access=true --sandbox workspace-write \
     "<prompt>" </dev/null
   ```
3. Codex returned exit 0 in 129 seconds; transcript persisted at `evidence/codex-remediation-dispatch.txt` (3181 lines).
4. Spot-checked one missed edit (004 `4 of 4` → `4 of 5` was T024-adjacent but not in original prompt) and patched it via Claude Edit.
5. Ran strict-validate on 004 AND 005; both PASSED with 0 errors / 0 warnings.

### Codex transcript summary
- Modified files: 9 (matches scope list exactly)
- Findings closed: T010..T024 with descriptions; T017/T018/T019/T025-T028 marked no-op with reason
- "Could not apply: none" — clean application

### Memory hints relied on
- `feedback_codex_cli_fast_mode.md` — explicit `service_tier="fast"`
- `feedback_codex_sandbox_blocks_network.md` — explicit `network_access=true`
- `feedback_cli_codex_for_grunt_work.md` — codex is the right tool for mechanical multi-file edits
<!-- /ANCHOR:how-delivered -->

---

<!-- ANCHOR:decisions -->
## Key Decisions

1. **Accept SD-019 / F-001 as a limitation, not file a sub-packet to fix codex behavior.** Decision driver: investigating codex's agent-resolver behavior is unscoped, and the `cli-claude-code` + `cli-opencode` paths PASS — the rename is wired correctly in the registry. Documented via SD-019 frontmatter + parent Known Issues. Re-evaluation hook: a future codex release that fixes `codex exec` agent resolution could re-enable SD-019 by flipping the `expected_skip_in_non_interactive` flag.

2. **Single cli-codex dispatch, not multiple.** Decision driver: per-finding parallel dispatches risk shared-file race conditions and codex CLI dispatch unreliability under heavy parallelism (memory hint). One transactional pass with comprehensive prompt is faster, simpler, auditable.

3. **No re-run of the deep-review.** Decision driver: the workflow already converged with weighted-stop-score 0.798. Re-running would re-discover the same findings, now resolved.

4. **F-002-001 marked accepted, not fixed.** Decision driver: SD-020 evidence contains ephemeral session IDs that are runtime metadata, not secrets. Stripping them would harm reproducibility evidence.

5. **Codex prompt embedded every edit with file:line context.** Decision driver: codex is precise but conservative. Vague prompts produce conservative no-ops; precise prompts produce precise edits.
<!-- /ANCHOR:decisions -->

---

<!-- ANCHOR:verification -->
## Verification

### Strict-validate results

| Spec folder | Errors | Warnings | Result |
|-------------|--------|----------|--------|
| 004-sk-doc-playbook-markdown-agent-coverage | 0 | 0 | PASSED |
| 005-deep-review-p1-p2-remediation | 0 | 0 | PASSED |

### Grep matrix evidence

| Finding | Verification command | Result |
|---------|----------------------|--------|
| T010 Phase 2 Complete | `grep -c "002-sk-doc-skill-readme-asset.*Complete" 102/spec.md` | 1 hit |
| T011 SD-019 note | `grep -c "SD-019 surfaced a cli-codex" 102/spec.md` | 1 hit |
| T012 CHK-003 handoff | `grep -c "Phase 1→2 handoff acceptance" 002/checklist.md` | 1 hit |
| T013 004 Status Complete | `grep "Status.*Complete" 004/spec.md` | 1 hit |
| T014 004 completion_pct | `grep -c "completion_pct: 100" 004/implementation-summary.md` | 1 hit |
| T014 004 open_questions | `grep -c "open_questions: \[\]" 004/implementation-summary.md` | 1 hit |
| T015 SD-019 skip flag | `grep -c "expected_skip_in_non_interactive: true" 002-markdown-agent-cli-codex.md` | 1 hit |
| T016 Known Issues section | `grep -c "^## Known Issues" 102/spec.md` | 1 hit |
| T020/T021/T022 N of 5 | `grep "of 5" 001/spec.md 002/spec.md 003/spec.md 004/spec.md` | 4 hits (one per child) |
| T023 002 completion_pct | `grep "completion_pct" 002/checklist.md` | "100" |
| T024 004 checklist marks | `grep -c "^- \[x\] CHK-" 004/checklist.md` | 26 (of 26 total) |

### Findings closure matrix

| Finding ID | Severity | Closure |
|-----------|----------|---------|
| F-000-001 | P1 | T010 — Phase 2 status synced (consolidated with F-001-001) |
| F-000-002 | P1 | T012 — handoff evidence added to 002 CHK-003 (consolidated with F-003-001) |
| F-000-003 | P1 | T014 — no separate edit; covered by F-004-001 closure |
| F-001-001 | P1 | T010 — consolidated with F-000-001 |
| F-001-002 | P2 | T013 — 004 spec status Draft→Complete |
| F-001-003 | P2 | T024 — 004 checklist 26/26 marked with evidence |
| F-001-004 | P2 | T023 — 002 checklist completion_pct 0→100 |
| F-001-005 | P1 | T011 — handoff row annotated with SD-019 gap |
| F-002-001 | P2 | T026 no-op — accepted runtime metadata (session IDs in SD-020 evidence) |
| F-003-001 | P1 | T012 — same edit as F-000-002 |
| F-003-002 | P1 | T013 / T015 — 004 Status Complete + SD-019 accepted-limitation resolves objective ambiguity |
| F-003-003 | P2 | T020/T021/T022 — child specs renumbered |
| F-003-004 | P2 | T016 (inline) — Known Issues §"Phase 3 prior deep-review" cross-ref added |
| F-004-001 | P1 | T014 — 004 completion_pct 100, open_questions cleared, Status Complete |
| F-004-002 | P2 | T023 — same edit as F-001-004 |
| F-004-003 | P2 | T016 — new Known Issues section |
| F-004-004 | P2 | T020 — same edit as F-003-003 (001 spec.md) |
<!-- /ANCHOR:verification -->

---

<!-- ANCHOR:limitations -->
## Known Limitations

### F-001 SD-019 — accepted limitation (not fixed in this packet)
The cli-codex `@markdown` dispatch gap under `codex exec` non-interactive mode is now documented at three layers:
1. SD-019 scenario file frontmatter: `expected_skip_in_non_interactive: true` + `skip_rationale`
2. Parent `102/spec.md` Known Issues register: explicit row with status "Accepted limitation"
3. This implementation-summary §Key Decisions explains why fix-vs-accept tipped toward accept

**Re-evaluation trigger**: a future codex release that fixes `codex exec` agent resolution for runtime-registered agents (`[agents.markdown]` in `.codex/config.toml`) could re-enable SD-019 by flipping the frontmatter flag and re-running the scenario.

### F-Stage-E-001 — `/spec_kit:deep-review:auto` setup-phase stdin hang
Surfaced during Stage E of 004 (not in the dashboard, but documented in 004/implementation-summary). The `:auto` suffix is supposed to be non-interactive, but the markdown-entry setup gate still asks confirmation questions. Worked around by pre-binding all setup answers in the dispatch prompt. Not addressed by 005; worth filing as a separate deep-review-skill packet.

### F-002 + F-003 — accepted advisories (no edits required)
- F-002 opencode `--agent general` subagent-fallback message: harmless ergonomics noise; documented in parent Known Issues register.
- F-003 sk-doc compact-changelog format: canonical and intentional; documented.
<!-- /ANCHOR:limitations -->

 succeeded in 0ms:
11-sandbox: danger-full-access
12-reasoning effort: xhigh
13-reasoning summaries: none
14-session id: 019e1589-1771-74c1-9f7c-d25a6e5804f1
15---------
16-user
17:Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-codex.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.
18-hook: SessionStart
19-hook: SessionStart
20-hook: SessionStart Completed
21-hook: SessionStart Completed
22-hook: UserPromptSubmit
23-hook: UserPromptSubmit
24-hook: UserPromptSubmit Completed
25-hook: UserPromptSubmit Completed
26-codex
27-I’ll route this through the `@markdown` agent as requested and keep the output isolated in `/tmp`, so the stub skill tree stays untouched.
28:2026-05-11T05:36:21.982264Z ERROR codex_core::tools::router: error=Full-history forked agents inherit the parent agent type, model, and reasoning effort; omit agent_type, model, and reasoning_effort, or spawn without a full-history fork.
29:collab: SpawnAgent
30:collab: SpawnAgent
31:2026-05-11T05:36:28.991568Z ERROR codex_core::tools::router: error=agent type is currently not available
32-codex
33:The dedicated `markdown` agent type isn’t exposed by this runner despite being named in the local instructions. I’m going to keep the behavior faithful to that agent by loading `sk-doc` and the changelog command resources directly, and I’ll report the routing gap plainly.
34:collab: SpawnAgent
35-codex
36-While that agent works, I’m checking the actual `sk-doc` command surface locally. The useful part here is evidence: template path, required sections, and whether `/create:changelog` has any special rules.
37-exec
38-/bin/zsh -lc "sed -n '1,240p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook
39- succeeded in 0ms:
40----
--
564-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/02--resource-loading/002-assets-only.md:44:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
565-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:6:expected_intent: CHANGELOG
566-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:9:  - assets/changelog_template.md
567-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:10:  - references/changelog_creation.md
568-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:20:This scenario validates that `cli-codex` (gpt-5.5/fast/high) correctly routes a `/create:changelog` task to the `@markdown` agent and that the agent loads sk-doc CHANGELOG resources before scaffolding the output.
569-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:30:- Real user request: scaffold a v0.1.0 changelog for a stub skill via the `@markdown` agent
570:/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:31:- Prompt: `Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-codex.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.`
571-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:32:- Expected intent: `CHANGELOG`
572-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:34:- Desired user-visible outcome: A scaffolded changelog file at `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md` with Keep-a-Changelog sections, plus a transcript showing `@markdown` Phase 0 verification ran before the YAML workflow loaded.
573-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:40:| SD-019 | @markdown via cli-codex | Verify `@markdown` agent receives `/create:changelog` work dispatched through cli-codex. | See Setup. | See Setup. | `@markdown` Phase 0 verification text appears in transcript; CHANGELOG asset reference appears; output file written. | Transcript + output changelog content. | PASS when `@markdown` invocation appears AND output file exists AND has Keep-a-Changelog sections. PARTIAL if `@markdown` invoked but output incomplete. FAIL if a different agent answered. SKIP if `codex` binary unavailable. | Re-check `.codex/agents/markdown.toml` exists; verify `.codex/config.toml` registers `agents.markdown`; verify network-access + fast flags applied. |
574:/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:51:PROMPT='Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-codex.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.'
575-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:70:# Resource trace: changelog template must be referenced
576-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:71:grep -c 'changelog_template\|changelog_creation\|Keep-a-Changelog' "$EVIDENCE"
577-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:74:test -f /tmp/sk-test-dummy-CHANGELOG-cli-codex.md && \
578-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:75:  grep -cE '^## .*(Added|Changed|Fixed|Removed)' /tmp/sk-test-dummy-CHANGELOG-cli-codex.md
579-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:80:- **Intent picked**: `CHANGELOG`
580-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:83:  - `.opencode/skills/sk-doc/assets/changelog_template.md`
--
588-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/scripts/validate_document.py:632:    parser.add_argument('--type', choices=['readme', 'skill', 'reference', 'asset', 'agent', 'command', 'install_guide', 'spec', 'changelog'],
589-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:6:expected_intent: CHANGELOG
590-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:9:  - assets/changelog_template.md
591-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:10:  - references/changelog_creation.md
592-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:20:This scenario validates that `cli-claude-code` correctly routes a `/create:changelog` task to the `@markdown` agent (the dedicated documentation executor introduced in 102-sk-doc-skill-readme-and-structure/003-markdown-agent-rename), and that the agent loads sk-doc CHANGELOG resources before scaffolding the output.
593-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:30:- Real user request: scaffold a v0.1.0 changelog for a stub skill via the `@markdown` agent
594:/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:31:- Prompt: `Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-claude-code.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.`
595-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:32:- Expected intent: `CHANGELOG`
596-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:34:- Desired user-visible outcome: A scaffolded changelog file at `/tmp/sk-test-dummy-CHANGELOG-cli-claude-code.md` with Keep-a-Changelog sections, plus a transcript showing `@markdown` Phase 0 verification ran before the YAML workflow loaded.
597-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:40:| SD-018 | @markdown via cli-claude-code | Verify `@markdown` agent receives `/create:changelog` work dispatched through cli-claude-code. | See Setup. | See Setup. | `@markdown` Phase 0 verification text appears in transcript; CHANGELOG asset reference appears; output file written. | Transcript + output changelog content. | PASS when `@markdown` invocation appears AND output file exists AND has Keep-a-Changelog sections. PARTIAL if `@markdown` invoked but output incomplete. FAIL if a different agent answered. SKIP if `claude` binary unavailable. | Re-check `.claude/agents/markdown.md` exists; re-check `.opencode/commands/create/changelog.md` Phase 0 block. |
598:/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:47:PROMPT='Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-claude-code.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.'
599-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:63:# Resource trace: changelog template must be referenced
600-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:64:grep -c 'changelog_template\|changelog_creation\|Keep-a-Changelog' "$EVIDENCE"
601-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:67:test -f /tmp/sk-test-dummy-CHANGELOG-cli-claude-code.md && \
602-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:68:  grep -cE '^## .*(Added|Changed|Fixed|Removed)' /tmp/sk-test-dummy-CHANGELOG-cli-claude-code.md
603-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:73:- **Intent picked**: `CHANGELOG`
604-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:76:  - `.opencode/skills/sk-doc/assets/changelog_template.md`
--
606-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:78:- **Outcome**: CLI scaffolds a v0.1.0 changelog file with Added / Changed / Fixed / Removed sections at `/tmp/sk-test-dummy-CHANGELOG-cli-claude-code.md`.
607-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:6:expected_intent: CHANGELOG
608-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:9:  - assets/changelog_template.md
609-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:10:  - references/changelog_creation.md
610-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:20:This scenario validates that `cli-opencode`, when pointed at the DeepSeek v4 Pro model through the direct DeepSeek API (NOT the opencode-go gateway), correctly routes a `/create:changelog` task to the `@markdown` agent and loads sk-doc CHANGELOG resources before scaffolding the output.
611-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:30:- Real user request: scaffold a v0.1.0 changelog for a stub skill via the `@markdown` agent
612:/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:31:- Prompt: `Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-opencode.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.`
613-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:32:- Expected intent: `CHANGELOG`
614-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:34:- Desired user-visible outcome: A scaffolded changelog file at `/tmp/sk-test-dummy-CHANGELOG-cli-opencode.md` with Keep-a-Changelog sections, plus a JSON-format transcript showing the `@markdown` agent received the work.
615-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:40:| SD-020 | @markdown via cli-opencode + DeepSeek v4 Pro direct | Verify `@markdown` agent receives `/create:changelog` work dispatched through cli-opencode with DeepSeek v4 Pro through DeepSeek API. | See Setup. | See Setup. | `@markdown` agent invocation appears in JSON transcript; CHANGELOG asset reference appears; output file written. | Transcript + output changelog content. | PASS when `@markdown` invocation appears AND output file exists AND has Keep-a-Changelog sections. PARTIAL if `@markdown` invoked but output incomplete. FAIL if a different agent answered or DeepSeek rejected the tool-name regex. SKIP if `opencode` binary or `deepseek` provider auth unavailable. | Verify `opencode providers list` shows `deepseek`; confirm `--pure` strips the MCP skills surface; confirm `</dev/null` redirect applied. |
616:/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:53:PROMPT='Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-opencode.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.'
617-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:81:# Resource trace: changelog template must be referenced
618-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:82:grep -c 'changelog_template\|changelog_creation\|Keep-a-Changelog' "$EVIDENCE"
619-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:85:test -f /tmp/sk-test-dummy-CHANGELOG-cli-opencode.md && \
620-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:86:  grep -cE '^## .*(Added|Changed|Fixed|Removed)' /tmp/sk-test-dummy-CHANGELOG-cli-opencode.md
621-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:91:- **Intent picked**: `CHANGELOG`
622-/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:94:  - `.opencode/skills/sk-doc/assets/changelog_template.md`
--
1479-> ⚠️ **EXECUTION PROTOCOL — READ FIRST**
1480->
1481-> This command runs a structured YAML workflow. Do NOT dispatch agents from this document.
1482->
1483-> **YOUR FIRST ACTION:**
1484->
1485:> 1. Run Phase 0: @markdown agent self-verification (below)
1486-> 2. Run Setup Phase: consolidated prompt to gather inputs
1487-> 3. Determine execution mode from user input (`:auto` or `:confirm`)
1488-> 4. Load the corresponding YAML file from `assets/`:
1489->    - Auto mode → `create_changelog_auto.yaml`
1490->    - Confirm mode → `create_changelog_confirm.yaml`
1491-> 5. Execute the YAML workflow step by step
--
1499-
1500-**STATUS: ☐ BLOCKED**
1501-
1502-```
1503-EXECUTE THIS AUTOMATIC SELF-CHECK (NOT A USER QUESTION):
1504-
1505:SELF-CHECK: Are you operating as the @markdown agent?
1506-│
1507:├─ INDICATORS that you ARE @markdown agent:
1508-│   ├─ You were invoked with "@markdown" prefix
1509-│   ├─ You have template-first workflow capabilities
1510-│   ├─ You load templates BEFORE creating content
1511-│   ├─ You validate template alignment AFTER creating
1512-│
1513-├─ IF YES (all indicators present):
--
1518-    ├─ ⛔ HARD BLOCK - DO NOT PROCEED
1519-    │
1520-    ├─ DISPLAY to user:
1521-    │   ┌────────────────────────────────────────────────────────────┐
1522-    │   │ ⛔ MARKDOWN AGENT REQUIRED                                      │
1523-    │   │                                                            │
1524:    │   │ This command requires the @markdown agent for:              │
1525-    │   │   • Template-first workflow (loads before creating)          │
1526-    │   │   • Changelog format validation                            │
1527-    │   │   • Version number verification                             │
1528-    │   │                                                            │
1529-    │   │ To proceed, restart with:                                  │
1530-    │   │   @markdown /create:changelog [spec-folder-or-component]    │
--
2172-
2173-codex
2174-Blocked on the repo’s spec-folder gate before writing `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md`.
2175-
2176-What happened:
2177-- Requested `@markdown` dispatch failed because the runner reported `markdown` as unavailable.
2178:- I dispatched a fallback subagent, `Schrodinger` (`019e1589-b232-7f03-81bd-78ffcc280afd`), with explicit `@markdown`/`sk-doc` instructions.
2179-- That agent stopped correctly on the file-creation gate: it needs you to confirm `D) Skip` before creating the `/tmp` changelog without a spec folder.
2180-
2181-For this throwaway scaffold, the sensible answer is `D) Skip`. Confirm that and I’ll write only `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md`, with no `.opencode/skills/` changes.
2182-hook: Stop
2183-hook: Stop Completed
2184-tokens used
2185-83,441
2186-Blocked on the repo’s spec-folder gate before writing `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md`.
2187-
2188-What happened:
2189-- Requested `@markdown` dispatch failed because the runner reported `markdown` as unavailable.
2190:- I dispatched a fallback subagent, `Schrodinger` (`019e1589-b232-7f03-81bd-78ffcc280afd`), with explicit `@markdown`/`sk-doc` instructions.
2191-- That agent stopped correctly on the file-creation gate: it needs you to confirm `D) Skip` before creating the `/tmp` changelog without a spec folder.
2192-
2193-For this throwaway scaffold, the sensible answer is `D) Skip`. Confirm that and I’ll write only `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md`, with no `.opencode/skills/` changes.
2194-
2195-=== END: 2026-05-11T07:38:05+02:00 ===
2196-=== EXIT CODE: 0 ===
2197-=== WALL CLOCK: 120s ===
2198-
2199-================================================================
2200-VERDICT: FAIL
2201-================================================================
2202-Grading rubric (playbook §Pass/Fail):
2203:- routing_trace: @markdown was REQUESTED but reported "unavailable" by codex runner. Codex fell back to a sub-agent ("Schrodinger") which then hit the Gate 3 spec-folder hard-block and waited for interactive user confirmation (impossible in non-interactive `codex exec` mode).
2204:- resource_trace: sk-doc resources NOT loaded (Schrodinger blocked before sk-doc load).
2205-- output: /tmp/sk-test-dummy-CHANGELOG-cli-codex.md DOES NOT EXIST (no file written).
2206-- exit_code: 0 (codex returned cleanly even though no work completed — a separate concern about codex's exit-code semantics).
2207:- latency: 120s wall-clock (mostly the Schrodinger sub-agent's internal deliberation before halt).
2208-
2209-ROOT CAUSE (preliminary):
2210:.codex/config.toml DOES register [agents.markdown] → agents/markdown.toml, and the file exists with proper TOML. The codex agent registry is wired correctly. However, the codex run-time AI did not naturally dispatch via @markdown — it instead tried a sub-agent path ("Schrodinger") that hit Gate 3.
2211-
2212-This suggests two follow-on findings worth surfacing to the 10-iter deep-review:
2213-1. cli-codex's @markdown routing under `codex exec` non-interactive mode may need a prompt-shape adjustment (or a `--skip-gate-3` flag, or pre-bound spec folder via prompt) to be reliably exercisable.
2214:2. The Gate 3 hard-block correctly fired — but in scenario-test mode, it blocks /tmp scratch writes too. Section 6 of the playbook may need a documented bypass pattern for actual-execution scenarios.
2215-
2216-NOTABLE: This is a HIGH-VALUE failure. It confirms 102/003's rename is wired in the registry but reveals an unflagged gap in cli-codex dispatch ergonomics for @markdown. The deep-review loop should capture this as a P1 finding.
2217-================================================================

exec
/bin/zsh -lc "sed -n '1,260p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/system-spec-kit/shared/gate-3-classifier.ts" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
// ---------------------------------------------------------------
// MODULE: Gate 3 Classifier
// ---------------------------------------------------------------
// Shared typed classifier for the Gate 3 (SPEC FOLDER QUESTION) trigger surface.
// Addresses findings R41-002, R45-001, R47-001 (T-DOC-02) and R48-001, R49-001,
// R50-001 (T-DOC-03) from the 016 foundational-runtime deep review.
//
// Runtime root docs (AGENTS.md, CLAUDE.md, GEMINI.md, CODEX.md) and the
// spec_kit command entry docs cite this module as the machine contract.
// The prose trigger lists in those docs remain as human-readable references
// but the authoritative list of tokens lives here.
// ---------------------------------------------------------------

import { canonicalFold } from './unicode-normalization.js';

function assertNever(value: never, label: string): never {
  throw new Error(`Unexpected ${label}: ${String(value)}`);
}

// ---------------------------------------------------------------
// 1. TRIGGER SCHEMA
// ---------------------------------------------------------------

/** Token categories consumed by the classifier. */
export type TriggerCategory =
  | 'file_write'        // Creating / modifying / deleting files
  | 'memory_save'       // save context / save memory / /memory:save
  | 'resume'            // resume / continue iteration (write-producing flows)
  | 'read_only';        // review / audit / inspect / explain (disqualifiers)

/** Exact phrase vs single-token matching. */
export type MatchKind = 'phrase' | 'token';

/** One row in the classifier vocabulary. */
export interface TriggerEntry {
  /** The exact string to match, lowercased. */
  pattern: string;
  /** Whether `pattern` should match as a phrase (whitespace-tolerant) or a single token. */
  kind: MatchKind;
  /** Category classification. */
  category: TriggerCategory;
  /** Short comment explaining rationale (docs-only). */
  note?: string;
}

/** Result of classifying a prompt. */
export interface ClassificationResult {
  /** Whether Gate 3 must be asked. */
  triggersGate3: boolean;
  /** Why (or why not). */
  reason: 'file_write_match' | 'memory_save_match' | 'resume_match' | 'read_only_override' | 'no_match';
  /** All trigger entries that matched. */
  matched: TriggerEntry[];
  /** All read-only disqualifiers that matched (may override file_write). */
  readOnlyMatched: TriggerEntry[];
}

// ---------------------------------------------------------------
// 2. CANONICAL TRIGGER VOCABULARY
// ---------------------------------------------------------------

/**
 * File-write positive triggers.
 *
 * These phrases/tokens indicate the prompt is asking for a file modification,
 * requiring a spec folder.
 */
export const FILE_WRITE_TRIGGERS: readonly TriggerEntry[] = Object.freeze([
  { pattern: 'create',     kind: 'token', category: 'file_write' },
  { pattern: 'add',        kind: 'token', category: 'file_write' },
  { pattern: 'remove',     kind: 'token', category: 'file_write' },
  { pattern: 'delete',     kind: 'token', category: 'file_write' },
  { pattern: 'rename',     kind: 'token', category: 'file_write' },
  { pattern: 'move',       kind: 'token', category: 'file_write' },
  { pattern: 'update',     kind: 'token', category: 'file_write' },
  { pattern: 'change',     kind: 'token', category: 'file_write' },
  { pattern: 'modify',     kind: 'token', category: 'file_write' },
  { pattern: 'edit',       kind: 'token', category: 'file_write' },
  { pattern: 'fix',        kind: 'token', category: 'file_write' },
  { pattern: 'patch',      kind: 'token', category: 'file_write' },
  { pattern: 'refactor',   kind: 'token', category: 'file_write' },
  { pattern: 'implement',  kind: 'token', category: 'file_write' },
  { pattern: 'build',      kind: 'token', category: 'file_write' },
  { pattern: 'write',      kind: 'token', category: 'file_write' },
  { pattern: 'rewrite',    kind: 'token', category: 'file_write' },
  { pattern: 'generate',   kind: 'token', category: 'file_write' },
  { pattern: 'configure',  kind: 'token', category: 'file_write' },
]);

/**
 * Memory save triggers.
 *
 * Gate 3 applies to memory save flows because they write canonical continuity
 * artifacts (description.json, graph-metadata.json, and continuity frontmatter).
 */
export const MEMORY_SAVE_TRIGGERS: readonly TriggerEntry[] = Object.freeze([
  { pattern: 'save context',  kind: 'phrase', category: 'memory_save' },
  { pattern: 'save memory',   kind: 'phrase', category: 'memory_save' },
  { pattern: '/memory:save',  kind: 'phrase', category: 'memory_save' },
]);

/**
 * Resume / continue triggers.
 *
 * `/spec_kit:resume` and deep-research `resume` produce writes (iteration-NNN.md
 * and JSONL appends), so they require Gate 3 even though the surface name sounds
 * read-only.
 */
export const RESUME_TRIGGERS: readonly TriggerEntry[] = Object.freeze([
  { pattern: '/spec_kit:resume',    kind: 'phrase', category: 'resume' },
  { pattern: '/spec_kit:deep-research', kind: 'phrase', category: 'resume' },
  { pattern: 'spec_kit:deep-research',  kind: 'phrase', category: 'resume' },
  { pattern: '/spec_kit:deep-review',   kind: 'phrase', category: 'resume' },
  { pattern: 'spec_kit:deep-review',    kind: 'phrase', category: 'resume' },
  { pattern: 'resume the packet',        kind: 'phrase', category: 'resume' },
  { pattern: 'resume the phase folder',  kind: 'phrase', category: 'resume' },
  { pattern: 'reconstruct continuity',   kind: 'phrase', category: 'resume' },
  { pattern: ':auto',               kind: 'phrase', category: 'resume', note: 'Only matches with spec_kit prefix.' },
  { pattern: 'deep-research',       kind: 'phrase', category: 'resume' },
  { pattern: 'deep research',       kind: 'phrase', category: 'resume' },
  { pattern: 'deep-review',         kind: 'phrase', category: 'resume' },
  { pattern: 'deep review',         kind: 'phrase', category: 'resume' },
  { pattern: 'deep-loop',           kind: 'phrase', category: 'resume' },
  { pattern: 'research loop',       kind: 'phrase', category: 'resume' },
  { pattern: 'review loop',         kind: 'phrase', category: 'resume' },
  { pattern: 'iteration loop',      kind: 'phrase', category: 'resume' },
  { pattern: 'research sweep',      kind: 'phrase', category: 'resume' },
  { pattern: 'research cycle',      kind: 'phrase', category: 'resume' },
  { pattern: 'research run',        kind: 'phrase', category: 'resume' },
  { pattern: 'research wave',       kind: 'phrase', category: 'resume' },
  { pattern: 'review wave',         kind: 'phrase', category: 'resume' },
  { pattern: 'looped investigation',kind: 'phrase', category: 'resume' },
  { pattern: 'keep iterating',      kind: 'phrase', category: 'resume' },
  { pattern: 'autoresearch',        kind: 'phrase', category: 'resume' },
  { pattern: 'convergence',         kind: 'phrase', category: 'resume' },
  { pattern: 'resume iteration',    kind: 'phrase', category: 'resume' },
  { pattern: 'resume deep research',kind: 'phrase', category: 'resume' },
  { pattern: 'resume deep review',  kind: 'phrase', category: 'resume' },
  { pattern: 'continue iteration',  kind: 'phrase', category: 'resume' },
]);

/**
 * Read-only disqualifiers.
 *
 * These tokens, when present WITHOUT a corresponding file-write / memory-save /
 * resume trigger, mark the request as read-only. This prevents false positives
 * for prompts like "analyze the decomposition phase" or "review / audit / inspect
 * the code".
 *
 * Note: `analyze`, `decompose`, `phase` were previously positive triggers but
 * false-positived on read-only review prompts. They are intentionally omitted
 * from positive triggers; `analyze` is included here as a read-only disqualifier.
 */
export const READ_ONLY_DISQUALIFIERS: readonly TriggerEntry[] = Object.freeze([
  { pattern: 'review',  kind: 'token', category: 'read_only' },
  { pattern: 'audit',   kind: 'token', category: 'read_only' },
  { pattern: 'inspect', kind: 'token', category: 'read_only' },
  { pattern: 'analyze', kind: 'token', category: 'read_only' },
  { pattern: 'explain', kind: 'token', category: 'read_only' },
]);

/** Full canonical vocabulary, exported for docs / linting. */
export const GATE_3_VOCABULARY = Object.freeze({
  fileWrite:           FILE_WRITE_TRIGGERS,
  memorySave:          MEMORY_SAVE_TRIGGERS,
  resume:              RESUME_TRIGGERS,
  readOnlyDisqualifier:READ_ONLY_DISQUALIFIERS,
});

// ---------------------------------------------------------------
// 3. NORMALIZATION
// ---------------------------------------------------------------

/**
 * Normalize a prompt for matching: lowercase and collapse whitespace, but
 * preserve `/` and `:` so command forms like `/spec_kit:resume` survive.
 */
export function normalizePrompt(prompt: string): string {
  return canonicalFold(prompt)
    .toLowerCase()
    .replace(/\s+/g, ' ')
    .trim();
}

/** Tokenize a normalized prompt into alphanumeric + `/` + `:` words. */
export function tokenizePrompt(normalized: string): string[] {
  return normalized.split(/[^a-z0-9:/_-]+/).filter(Boolean);
}

// ---------------------------------------------------------------
// 4. CORE CLASSIFIER
// ---------------------------------------------------------------

/** Check if a single trigger entry matches a normalized prompt. */
export function matchesEntry(entry: TriggerEntry, normalized: string, tokens: string[]): boolean {
  if (entry.kind === 'phrase') {
    if (entry.pattern === ':auto' && entry.category === 'resume') {
      return normalized.includes(':auto') && normalized.includes('spec_kit');
    }
    return normalized.includes(entry.pattern);
  }
  // token match — must appear as a standalone word
  return tokens.includes(entry.pattern);
}

function triggerIndex(entry: TriggerEntry, normalized: string): number {
  return normalized.indexOf(entry.pattern);
}

function hasMixedWriteTail(
  normalized: string,
  writeMatches: TriggerEntry[],
  readOnlyMatches: TriggerEntry[],
): boolean {
  for (const readOnlyEntry of readOnlyMatches) {
    const readIndex = triggerIndex(readOnlyEntry, normalized);
    if (readIndex < 0) {
      continue;
    }

    for (const writeEntry of writeMatches) {
      const writeIndex = triggerIndex(writeEntry, normalized);
      if (writeIndex <= readIndex) {
        continue;
      }

      const between = normalized.slice(readIndex + readOnlyEntry.pattern.length, writeIndex);
      if (/\b(then|and|if)\b/.test(between) || between.includes(',')) {
        return true;
      }
    }
  }

  return false;
}

function hasWorkflowInvocationMarker(normalized: string): boolean {
  return /\b(run|use|start|begin|continue|resume|append|kick off|keep|launch)\b/.test(normalized);
}

function hasNegatedWriteAction(normalized: string, writeMatches: TriggerEntry[]): boolean {
  for (const writeEntry of writeMatches) {
    const writeIndex = triggerIndex(writeEntry, normalized);
    if (writeIndex < 0) {
      continue;
    }

    const prefix = normalized.slice(Math.max(0, writeIndex - 32), writeIndex);
    if (/\b(do not|don't|dont|without|no need to)\b/.test(prefix)) {
      return true;
    }
  }

  return /\bdo not (change|edit|save|write|update)\b/.test(normalized);
}

function hasFileTarget(normalized: string): boolean {
  return /`[^`]+\.(md|jsonl|json|ts|tsx|js|py|sh|txt|toml|ya?ml)`/.test(normalized)
    || /\b(file|folder|readme|docs?|corpus|checklist|implementation-summary|research\.md|tasks\.md)\b/.test(normalized);
}

exec
/bin/zsh -lc "sed -n '220,520p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/system-spec-kit/shared/gate-3-classifier.ts" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:

    for (const writeEntry of writeMatches) {
      const writeIndex = triggerIndex(writeEntry, normalized);
      if (writeIndex <= readIndex) {
        continue;
      }

      const between = normalized.slice(readIndex + readOnlyEntry.pattern.length, writeIndex);
      if (/\b(then|and|if)\b/.test(between) || between.includes(',')) {
        return true;
      }
    }
  }

  return false;
}

function hasWorkflowInvocationMarker(normalized: string): boolean {
  return /\b(run|use|start|begin|continue|resume|append|kick off|keep|launch)\b/.test(normalized);
}

function hasNegatedWriteAction(normalized: string, writeMatches: TriggerEntry[]): boolean {
  for (const writeEntry of writeMatches) {
    const writeIndex = triggerIndex(writeEntry, normalized);
    if (writeIndex < 0) {
      continue;
    }

    const prefix = normalized.slice(Math.max(0, writeIndex - 32), writeIndex);
    if (/\b(do not|don't|dont|without|no need to)\b/.test(prefix)) {
      return true;
    }
  }

  return /\bdo not (change|edit|save|write|update)\b/.test(normalized);
}

function hasFileTarget(normalized: string): boolean {
  return /`[^`]+\.(md|jsonl|json|ts|tsx|js|py|sh|txt|toml|ya?ml)`/.test(normalized)
    || /\b(file|folder|readme|docs?|corpus|checklist|implementation-summary|research\.md|tasks\.md)\b/.test(normalized);
}

function isPromptOnlyGeneration(normalized: string): boolean {
  if (!/\b(prompt|phrasing)\b/.test(normalized)) {
    return false;
  }
  if (hasFileTarget(normalized)) {
    return false;
  }
  return /\b(inline|in chat only|show it|just show|better phrasing|cleaner user prompt|prompt variant|prompt package|stronger system prompt)\b/.test(normalized)
    || /\b(create|generate|build|write)\b.*\b(prompt|phrasing)\b/.test(normalized);
}

/**
 * Classify a prompt against the Gate 3 trigger vocabulary.
 *
 * Decision order:
 * 1. Test positive triggers (file_write, memory_save, resume).
 * 2. If a resume or memory_save trigger matches → Gate 3 ALWAYS required
 *    (read_only disqualifiers cannot override).
 * 3. If only file_write triggers match:
 *    a. If any read_only disqualifier matches AND no file_write token is
 *       explicitly paired with a file target, Gate 3 is SUPPRESSED.
 *    b. Otherwise Gate 3 is required.
 * 4. If no positive trigger matches → Gate 3 not required.
 */
export function classifyPrompt(prompt: string): ClassificationResult {
  const normalized = normalizePrompt(prompt);
  const tokens = tokenizePrompt(normalized);

  const matched: TriggerEntry[] = [];
  const readOnlyMatched: TriggerEntry[] = [];

  let hasMemorySave = false;
  let hasResume = false;
  let hasFileWrite = false;

  for (const entry of MEMORY_SAVE_TRIGGERS) {
    if (matchesEntry(entry, normalized, tokens)) {
      matched.push(entry);
      hasMemorySave = true;
    }
  }
  for (const entry of RESUME_TRIGGERS) {
    if (matchesEntry(entry, normalized, tokens)) {
      matched.push(entry);
      hasResume = true;
    }
  }
  for (const entry of FILE_WRITE_TRIGGERS) {
    if (matchesEntry(entry, normalized, tokens)) {
      matched.push(entry);
      hasFileWrite = true;
    }
  }
  for (const entry of READ_ONLY_DISQUALIFIERS) {
    if (matchesEntry(entry, normalized, tokens)) {
      readOnlyMatched.push(entry);
    }
  }

  const fileWriteMatched = matched.filter((entry) => entry.category === 'file_write');
  const hasRecoverableMixedWriteTail = hasMixedWriteTail(normalized, fileWriteMatched, readOnlyMatched);
  if (hasFileWrite && (hasNegatedWriteAction(normalized, fileWriteMatched) || isPromptOnlyGeneration(normalized))) {
    return { triggersGate3: false, reason: readOnlyMatched.length > 0 ? 'read_only_override' : 'no_match', matched, readOnlyMatched };
  }

  // Memory save / resume: Gate 3 ALWAYS required (writes produced regardless).
  if (hasMemorySave) {
    return { triggersGate3: true, reason: 'memory_save_match', matched, readOnlyMatched };
  }
  if (hasResume) {
    if (readOnlyMatched.length > 0 && !hasWorkflowInvocationMarker(normalized) && !hasRecoverableMixedWriteTail) {
      return { triggersGate3: false, reason: hasFileWrite ? 'read_only_override' : 'no_match', matched, readOnlyMatched };
    }
    return { triggersGate3: true, reason: 'resume_match', matched, readOnlyMatched };
  }

  // File-write: read-only disqualifiers can override ONLY when there is no
  // direct file-write action (i.e., the file-write token appears alongside
  // a read-only verb like "review", "audit", "inspect").
  if (hasFileWrite) {
    if (readOnlyMatched.length > 0) {
      if (hasRecoverableMixedWriteTail) {
        return { triggersGate3: true, reason: 'file_write_match', matched, readOnlyMatched };
      }
      return { triggersGate3: false, reason: 'read_only_override', matched, readOnlyMatched };
    }
    return { triggersGate3: true, reason: 'file_write_match', matched, readOnlyMatched };
  }

  return { triggersGate3: false, reason: 'no_match', matched, readOnlyMatched };
}

// ---------------------------------------------------------------
// 5. JSON EXPORT (for non-TS consumers)
// ---------------------------------------------------------------

/** Serializable JSON snapshot of the vocabulary (for Python / YAML consumers). */
export interface Gate3VocabularySnapshot {
  version: string;
  fileWrite: readonly { pattern: string; kind: MatchKind }[];
  memorySave: readonly { pattern: string; kind: MatchKind }[];
  resume: readonly { pattern: string; kind: MatchKind }[];
  readOnlyDisqualifier: readonly { pattern: string; kind: MatchKind }[];
}

export const GATE_3_SCHEMA_VERSION = '1.0.0';

function getEntriesForCategory(category: TriggerCategory): readonly TriggerEntry[] {
  switch (category) {
    case 'file_write':
      return FILE_WRITE_TRIGGERS;
    case 'memory_save':
      return MEMORY_SAVE_TRIGGERS;
    case 'resume':
      return RESUME_TRIGGERS;
    case 'read_only':
      return READ_ONLY_DISQUALIFIERS;
    default:
      return assertNever(category, 'trigger-category');
  }
}

/** Return the vocabulary as a plain JSON snapshot. */
export function toJsonSnapshot(): Gate3VocabularySnapshot {
  const pick = (entries: readonly TriggerEntry[]) =>
    entries.map(({ pattern, kind }) => ({ pattern, kind }));
  return {
    version: GATE_3_SCHEMA_VERSION,
    fileWrite: pick(getEntriesForCategory('file_write')),
    memorySave: pick(getEntriesForCategory('memory_save')),
    resume: pick(getEntriesForCategory('resume')),
    readOnlyDisqualifier: pick(getEntriesForCategory('read_only')),
  };
}

codex
The transcript has two distinct failures, not one: first a malformed full-history fork request, then an unavailable typed agent. After that the model invented a fallback path and got stuck on Gate 3, which is the non-interactive failure mode.
exec
/bin/zsh -lc "sed -n '1,140p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure/004-sk-doc-playbook-markdown-agent-coverage/evidence/SD-019-cli-codex.txt" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
=== SD-019 dispatch: cli-codex @markdown via /create:changelog ===
=== START: 2026-05-11T07:36:05+02:00 ===

Reading additional input from stdin...
OpenAI Codex v0.130.0
--------
workdir: /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook
model: gpt-5.5
provider: openai
approval: never
sandbox: danger-full-access
reasoning effort: xhigh
reasoning summaries: none
session id: 019e1589-1771-74c1-9f7c-d25a6e5804f1
--------
user
Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-codex.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.
hook: SessionStart
hook: SessionStart
hook: SessionStart Completed
hook: SessionStart Completed
hook: UserPromptSubmit
hook: UserPromptSubmit
hook: UserPromptSubmit Completed
hook: UserPromptSubmit Completed
codex
I’ll route this through the `@markdown` agent as requested and keep the output isolated in `/tmp`, so the stub skill tree stays untouched.
2026-05-11T05:36:21.982264Z ERROR codex_core::tools::router: error=Full-history forked agents inherit the parent agent type, model, and reasoning effort; omit agent_type, model, and reasoning_effort, or spawn without a full-history fork.
collab: SpawnAgent
collab: SpawnAgent
2026-05-11T05:36:28.991568Z ERROR codex_core::tools::router: error=agent type is currently not available
codex
The dedicated `markdown` agent type isn’t exposed by this runner despite being named in the local instructions. I’m going to keep the behavior faithful to that agent by loading `sk-doc` and the changelog command resources directly, and I’ll report the routing gap plainly.
collab: SpawnAgent
codex
While that agent works, I’m checking the actual `sk-doc` command surface locally. The useful part here is evidence: template path, required sections, and whether `/create:changelog` has any special rules.
exec
/bin/zsh -lc "sed -n '1,240p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook
 succeeded in 0ms:
---
name: sk-doc
description: "Markdown and OpenCode component specialist: doc quality, content optimization, component scaffolds, install guides, playbooks."
allowed-tools: [Bash, Edit, Glob, Grep, Read, Task, Write]
version: 1.3.0.0
---

<!-- Keywords: sk-doc, markdown-quality, skill-creation, document-validation, ascii-flowchart, llms-txt, content-optimization, extract-structure -->

# Documentation Creation Specialist - Unified Markdown & Component Management

Unified specialist providing: (1) Document quality pipeline with structure enforcement and content optimization, (2) OpenCode component creation (skills, agents, commands) with scaffolding, validation and packaging, (3) ASCII flowchart creation for visualizing workflows, (4) Install guide creation for setup documentation and (5) Feature catalog and manual testing playbook creation for inventory and validation packages.

**Core Principle**: Structure first, then content, then quality.

**Architecture**: Scripts handle deterministic parsing/metrics. AI handles quality judgment and recommendations.

## 1. WHEN TO USE

### Use Case: Document Quality Management

Enforce markdown structure, optimize content for AI assistants, validate quality through script-assisted AI analysis.

**README Creation** - Use `readme_template.md` + `readme_creation.md` when:
- Creating new README for any folder or project
- User requests "create a README", "add documentation", "write a README"
- Folder needs comprehensive documentation
- Workflow: [readme_creation.md](./references/readme_creation.md) | Template: [readme_template.md](./assets/readme/readme_template.md)

**Skill README Creation** - Use `skill_readme_template.md` when:
- Creating or refreshing `.opencode/skills/[skill-name]/README.md`
- A skill README needs human-facing purpose, quick start, structure, examples, troubleshooting, FAQ or related-resource navigation
- Template: [skill_readme_template.md](./assets/skill/skill_readme_template.md)

**Frontmatter Validation** - Use `frontmatter_templates.md` when:
- Validating YAML frontmatter in any document
- Checking required fields for document types
- Fixing frontmatter syntax errors

**Changelog & Release Notes** - Use `changelog_template.md` when:
- Authoring a global component changelog at `.opencode/changelog/{NN--component}/v{VERSION}.md`
- Composing GitHub release notes that mirror the changelog body
- Choosing between compact (under 10 changes) and expanded (10+ changes or major) formats
- Template: [changelog_template.md](./assets/changelog_template.md). Used by `/create:changelog` (auto + confirm). Nested packet-local changelogs use the spec-kit templates at `.opencode/skills/system-spec-kit/templates/changelog/` instead.

**Validation Workflow** - Apply after Write/Edit operations:
- Auto-correct filename violations (ALL CAPS to lowercase, hyphens to underscores)
- Fix safe violations (separators, H2 case)
- Check critical violations (missing frontmatter, wrong section order)

**Manual Optimization** - Run when:
- README needs optimization for AI assistants
- Creating critical documentation (specs, knowledge, skills)
- Pre-release quality checks
- Generating llms.txt for LLM navigation

### Use Case: OpenCode Component Creation

Create and manage OpenCode components (skills, agents, commands). Each component type has templates and validation with quality standards.

**Component Types:**
- **Skills** (.opencode/skills/) - Knowledge bundles with workflows → [skill_creation.md](./references/skill_creation.md)
- **Agents** (.opencode/agents/) - AI personas with tool permissions → [agent_creation.md](./references/agent_creation.md)
- **Commands** (.opencode/commands/) - Slash commands for user invocation → [command_template.md](./assets/command_template.md)

For larger skills, split deep content into focused reference files and keep concise navigation in `SKILL.md` or `README.md`. When a skill has both cross-cutting standards and document-family guides, prefer `references/global/` for shared rules and the `references/` root for creation-specific workflows.

Start with: [skill_creation.md](./references/skill_creation.md) (Section 9)
Primary templates:
- [skill_md_template.md](./assets/skill/skill_md_template.md)
- [skill_readme_template.md](./assets/skill/skill_readme_template.md)
- [skill_reference_template.md](./assets/skill/skill_reference_template.md)
- [skill_asset_template.md](./assets/skill/skill_asset_template.md)

**Use when**:
- User requests skill creation ("create a skill", "make a new skill")
- User requests agent creation ("create an agent", "make a new agent")
- User requests command creation ("create a command", "add a slash command")
- Scaffolding component structure
- Validating component quality
- Packaging skill for distribution

**Skill Process (6 steps)**: Understanding (examples) → Planning (resources) → Initialization (`init_skill.py`) → Editing (populate) → Packaging (`package_skill.py`) → Iteration (test/improve)

**Agent Process**: Load `agent_creation.md` and `agent_template.md` → Define frontmatter (mode, permissions) → Create sections (workflow, capabilities, anti-patterns) → Validate → Test

**Command Process**: Load `command_template.md` → Define frontmatter (name, description) → Create execution logic → Add to command registry → Test

### Use Case: Flowchart Creation

Create ASCII flowcharts for visualizing workflows, user journeys and decision trees.

For styled HTML visuals (interactive diagrams, dashboard pages, or polished data-table renders), use a dedicated HTML workflow instead of forcing ASCII or markdown flowcharts.

**Use when**:
- Documenting multi-step processes with branching
- Creating decision trees with multiple outcomes
- Showing parallel execution with sync points
- Visualizing approval gates and revision cycles

**See**: [assets/flowcharts/](./assets/flowcharts/)

exec
/bin/zsh -lc "sed -n '2100,2198p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure/004-sk-doc-playbook-markdown-agent-coverage/evidence/SD-019-cli-codex.txt" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
## 3. HOW IT WORKS

### Prerequisites

```bash
# Verify installation
command -v codex || echo "Not installed. Run: npm i -g @openai/codex"

# Authentication — API key OR ChatGPT OAuth
export OPENAI_API_KEY=your-key-here
codex login
```

**Authentication options**: `OPENAI_API_KEY` env var (direct API), or ChatGPT OAuth via `codex login` (uses ChatGPT account credentials).

### Provider Auth Pre-Flight (Smart Fallback)

**MANDATORY before any first dispatch in a session.** The default OpenAI auth (API key OR ChatGPT OAuth) may not be configured on this machine — silently failing with `401 Unauthorized` or `not authenticated` mid-dispatch wastes a round-trip. Run this check once per session, cache the result, and re-run it only if a dispatch fails with an auth error.

```bash
# One-shot pre-flight: capture auth status for routing
[ -n "$OPENAI_API_KEY" ] && OPENAI_KEY_OK=1 || OPENAI_KEY_OK=0
CODEX_AUTH=$(codex auth status 2>&1)
echo "$CODEX_AUTH" | grep -qi "logged in\|chatgpt-oauth" && CODEX_OAUTH_OK=1 || CODEX_OAUTH_OK=0
```

**Decision tree** (apply in order — first match wins):

| State | OPENAI_KEY_OK | CODEX_OAUTH_OK | Action |
|-------|---------------|----------------|--------|
| Default available | 1 | * | Proceed with `codex exec --model gpt-5.5 -c model_reasoning_effort="medium" -c service_tier="fast"` |
| API key missing, OAuth ready | 0 | 1 | **ASK user** before substituting — never auto-fall-back silently. Surface options A/B/C below. |
| Both missing | 0 | 0 | **ASK user** to configure auth — surface the login commands, do NOT dispatch. |

**User prompt template — API key missing, OAuth configured:**

```
`$OPENAI_API_KEY` is not set, but ChatGPT OAuth via `codex login` is configured.
Pick one:
  A) Use the existing ChatGPT OAuth session (works for `codex exec` if your ChatGPT plan covers the model)
  B) Run `export OPENAI_API_KEY=sk-...` first, then retry the original dispatch
  C) Name a different model — paste the `--model <id>` you want to use
```

**User prompt template — both missing:**

```
No OpenAI auth is configured on this machine. Run one:
  - `export OPENAI_API_KEY=sk-...`  (recommended for direct API calls)
  - `codex login`                    (interactive ChatGPT OAuth flow; requires ChatGPT Plus/Pro/Business)
Which would you like to set up? Confirm when login finishes; the skill will retry the original dispatch.
```

**Error-recovery contract.** If a dispatch returns an auth error after pre-flight passed (key revoked or OAuth expired), invalidate the cache, rerun the pre-flight, and apply the same decision tree before retrying. Never substitute a model the user didn't approve.

### Default Invocation (Skill Default)

**Default model + effort + tier**: `gpt-5.5` · `medium` reasoning · `fast` service tier. Balances speed, cost, and quality for the typical delegation.

```bash
codex exec \
  --model gpt-5.5 \
  -c model_reasoning_effort="medium" \
  -c service_tier="fast" \
  -c approval_policy=never \
  --sandbox workspace-write \
  "<prompt>"
```

**User override** (honor explicit user phrasing verbatim):

| User says | Resolve to |

codex
Blocked on the repo’s spec-folder gate before writing `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md`.

What happened:
- Requested `@markdown` dispatch failed because the runner reported `markdown` as unavailable.
- I dispatched a fallback subagent, `Schrodinger` (`019e1589-b232-7f03-81bd-78ffcc280afd`), with explicit `@markdown`/`sk-doc` instructions.
- That agent stopped correctly on the file-creation gate: it needs you to confirm `D) Skip` before creating the `/tmp` changelog without a spec folder.

For this throwaway scaffold, the sensible answer is `D) Skip`. Confirm that and I’ll write only `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md`, with no `.opencode/skills/` changes.
hook: Stop
hook: Stop Completed
tokens used
83,441
Blocked on the repo’s spec-folder gate before writing `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md`.

What happened:
- Requested `@markdown` dispatch failed because the runner reported `markdown` as unavailable.
- I dispatched a fallback subagent, `Schrodinger` (`019e1589-b232-7f03-81bd-78ffcc280afd`), with explicit `@markdown`/`sk-doc` instructions.
- That agent stopped correctly on the file-creation gate: it needs you to confirm `D) Skip` before creating the `/tmp` changelog without a spec folder.

For this throwaway scaffold, the sensible answer is `D) Skip`. Confirm that and I’ll write only `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md`, with no `.opencode/skills/` changes.

=== END: 2026-05-11T07:38:05+02:00 ===
=== EXIT CODE: 0 ===
=== WALL CLOCK: 120s ===


exec
/bin/zsh -lc 'rg -n -C 4 "Known Issues|F-001|SD-019|Accepted limitation|cli-codex" /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure/spec.md' in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
62-| --- | --- | --- | --- |
63-| 1 | `001-sk-doc-reference-relocation/` | Complete | Move `sk-doc/references/specific` documents to `sk-doc/references` root and update all old-path references. |
64-| 2 | `002-sk-doc-skill-readme-asset/` | Complete | Analyze skill README conventions and create a dedicated sk-doc skill README asset with references from sk-doc docs and tests. |
65-| 3 | `003-markdown-agent-rename/` | Complete | Rename create-agent identity to markdown-agent identity across runtime agent mirrors and references while preserving `/create:*` commands. |
66:| 4 | `004-sk-doc-playbook-markdown-agent-coverage/` | Complete | Add `06--agent-dispatch/` section to the sk-doc manual testing playbook with three scenarios that dispatch `@markdown` across cli-claude-code, cli-codex, and cli-opencode; execute and capture evidence. |
67:| 5 | `005-deep-review-p1-p2-remediation/` | Complete | Remediate all 7 P1 and 9 P2 findings from the 102 phase-parent deep-review: status sync, handoff documentation, checklist marking, parent-level known-issues register, and SD-019 limitation documentation. |
68-
69-## 5. Phase Handoffs
70-
71-| From | To | Handoff Criteria | Verification |
72-| --- | --- | --- | --- |
73-| `001-sk-doc-reference-relocation` | `002-sk-doc-skill-readme-asset` | `references/specific` is removed, files are in `references/`, and old path references are gone. | Exact search for `references/specific` returns no implementation-scope hits. |
74-| `002-sk-doc-skill-readme-asset` | `003-markdown-agent-rename` | Dedicated skill README asset exists and is referenced from sk-doc creation guidance and testing docs. | File exists under `assets/skill/` and references resolve from `SKILL.md`, `references/skill_creation.md`, and manual testing docs. |
75:| `003-markdown-agent-rename` | `004-sk-doc-playbook-markdown-agent-coverage` | `@markdown` agent is wired across 4 runtime mirrors and routed by orchestrate.md. NOTE: SD-019 surfaced a cli-codex non-interactive @markdown dispatch gap (F-001) — documented as accepted limitation in 005-deep-review-p1-p2-remediation; codex `@markdown` dispatch under `codex exec` falls back to a sub-agent path that hits Gate 3. | `ls .opencode/agents/markdown.md .claude/agents/markdown.md .gemini/agents/markdown.md .codex/agents/markdown.toml` resolves all four. |
76:| `004-sk-doc-playbook-markdown-agent-coverage` | `005-deep-review-p1-p2-remediation` | Deep-review converged with verdict CONDITIONAL: 0 P0, 7 P1, 9 P2 findings; SD-019 cli-codex `@markdown` dispatch gap surfaced as F-001. | `.opencode/specs/.../102/review/deep-review-dashboard.md` exists; `004/implementation-summary.md` Review Outcome section cites 7 P1 + 9 P2. |
77-
78-## 6. Success Criteria
79-
80-- Each child phase has Level 2 documentation, a checklist, and a detailed resource map.
--
89-- `004-sk-doc-playbook-markdown-agent-coverage/spec.md`
90-- `005-deep-review-p1-p2-remediation/spec.md`
91-- `graph-metadata.json`
92-
93:## Known Issues
94-
95-This packet's deep-review (5 iterations, converged at iter 4, dashboard at `review/deep-review-dashboard.md`) surfaced the following findings. All are tracked here for downstream discoverability.
96-
97-### Confirmed pre-existing (from `004/implementation-summary.md`)
98-
99-| ID | Severity | Title | Status |
100-|----|----------|-------|--------|
101:| F-001 | P1 | cli-codex non-interactive `@markdown` dispatch ergonomics gap (SD-019 FAIL) | Accepted limitation — see 005 packet + SD-019 scenario `expected_skip_in_non_interactive` field |
102-| F-002 | P2 | opencode `--agent general` subagent-fallback message | Accepted — harmless ergonomics noise |
103-| F-003 | P2 | sk-doc compact-changelog format vs Keep-a-Changelog raw shape mismatch | Documented — sk-doc compact format is canonical |
104-
105-### Surfaced by 102 phase-parent deep-review (resolved in 005)
106-
107-| ID | Severity | Resolution |
108-|----|----------|------------|
109:| F-000-001 / F-001-001 | P1 | Phase 2 status synced Draft → Complete (this file) |
110-| F-000-002 / F-003-001 | P1 | Phase 1→2 handoff acceptance evidence added to `002/checklist.md` CHK-003 |
111:| F-001-005 | P1 | 003→004 handoff row annotated with SD-019 dispatch-gap note (this file) |
112:| F-003-002 | P1 | 004 REQ-004 partial-objective ambiguity resolved by SD-019 limitation documentation |
113-| F-004-001 | P1 | 004 completion_pct 90 → 100; open_questions cleared; status Complete |
114:| F-001-002 | P2 | 004/spec.md status Draft → Complete |
115:| F-001-003 | P2 | 004/checklist.md items marked with evidence |
116:| F-001-004 / F-004-002 | P2 | 002/checklist.md frontmatter completion_pct 0 → 100 |
117-| F-002-001 | P2 | SD-020 session IDs in evidence — accepted runtime metadata, no edit needed |
118-| F-003-003 / F-004-004 | P2 | Child specs renumbered "N of 3" → "N of 5" |
119-| F-003-004 | P2 | 003 prior-review cross-reference added (this file) |
120:| F-004-003 | P2 | This Known Issues section added |
121-
122-### Phase 3 prior deep-review
123-
124-The Phase 3 (`003-markdown-agent-rename/`) shipped with its own 4-iteration deep-review. Findings registry at `003/review/deep-review-findings-registry.json`; iteration files at `003/review/iterations/`; final dashboard at `003/review/deep-review-dashboard.md`. All Phase 3 findings were closed during that earlier review; cross-referenced here for completeness.

exec
/bin/zsh -lc "sed -n '1,220p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
---
name: sk-doc
description: "Markdown and OpenCode component specialist: doc quality, content optimization, component scaffolds, install guides, playbooks."
allowed-tools: [Bash, Edit, Glob, Grep, Read, Task, Write]
version: 1.3.0.0
---

<!-- Keywords: sk-doc, markdown-quality, skill-creation, document-validation, ascii-flowchart, llms-txt, content-optimization, extract-structure -->

# Documentation Creation Specialist - Unified Markdown & Component Management

Unified specialist providing: (1) Document quality pipeline with structure enforcement and content optimization, (2) OpenCode component creation (skills, agents, commands) with scaffolding, validation and packaging, (3) ASCII flowchart creation for visualizing workflows, (4) Install guide creation for setup documentation and (5) Feature catalog and manual testing playbook creation for inventory and validation packages.

**Core Principle**: Structure first, then content, then quality.

**Architecture**: Scripts handle deterministic parsing/metrics. AI handles quality judgment and recommendations.

## 1. WHEN TO USE

### Use Case: Document Quality Management

Enforce markdown structure, optimize content for AI assistants, validate quality through script-assisted AI analysis.

**README Creation** - Use `readme_template.md` + `readme_creation.md` when:
- Creating new README for any folder or project
- User requests "create a README", "add documentation", "write a README"
- Folder needs comprehensive documentation
- Workflow: [readme_creation.md](./references/readme_creation.md) | Template: [readme_template.md](./assets/readme/readme_template.md)

**Skill README Creation** - Use `skill_readme_template.md` when:
- Creating or refreshing `.opencode/skills/[skill-name]/README.md`
- A skill README needs human-facing purpose, quick start, structure, examples, troubleshooting, FAQ or related-resource navigation
- Template: [skill_readme_template.md](./assets/skill/skill_readme_template.md)

**Frontmatter Validation** - Use `frontmatter_templates.md` when:
- Validating YAML frontmatter in any document
- Checking required fields for document types
- Fixing frontmatter syntax errors

**Changelog & Release Notes** - Use `changelog_template.md` when:
- Authoring a global component changelog at `.opencode/changelog/{NN--component}/v{VERSION}.md`
- Composing GitHub release notes that mirror the changelog body
- Choosing between compact (under 10 changes) and expanded (10+ changes or major) formats
- Template: [changelog_template.md](./assets/changelog_template.md). Used by `/create:changelog` (auto + confirm). Nested packet-local changelogs use the spec-kit templates at `.opencode/skills/system-spec-kit/templates/changelog/` instead.

**Validation Workflow** - Apply after Write/Edit operations:
- Auto-correct filename violations (ALL CAPS to lowercase, hyphens to underscores)
- Fix safe violations (separators, H2 case)
- Check critical violations (missing frontmatter, wrong section order)

**Manual Optimization** - Run when:
- README needs optimization for AI assistants
- Creating critical documentation (specs, knowledge, skills)
- Pre-release quality checks
- Generating llms.txt for LLM navigation

### Use Case: OpenCode Component Creation

Create and manage OpenCode components (skills, agents, commands). Each component type has templates and validation with quality standards.

**Component Types:**
- **Skills** (.opencode/skills/) - Knowledge bundles with workflows → [skill_creation.md](./references/skill_creation.md)
- **Agents** (.opencode/agents/) - AI personas with tool permissions → [agent_creation.md](./references/agent_creation.md)
- **Commands** (.opencode/commands/) - Slash commands for user invocation → [command_template.md](./assets/command_template.md)

For larger skills, split deep content into focused reference files and keep concise navigation in `SKILL.md` or `README.md`. When a skill has both cross-cutting standards and document-family guides, prefer `references/global/` for shared rules and the `references/` root for creation-specific workflows.

Start with: [skill_creation.md](./references/skill_creation.md) (Section 9)
Primary templates:
- [skill_md_template.md](./assets/skill/skill_md_template.md)
- [skill_readme_template.md](./assets/skill/skill_readme_template.md)
- [skill_reference_template.md](./assets/skill/skill_reference_template.md)
- [skill_asset_template.md](./assets/skill/skill_asset_template.md)

**Use when**:
- User requests skill creation ("create a skill", "make a new skill")
- User requests agent creation ("create an agent", "make a new agent")
- User requests command creation ("create a command", "add a slash command")
- Scaffolding component structure
- Validating component quality
- Packaging skill for distribution

**Skill Process (6 steps)**: Understanding (examples) → Planning (resources) → Initialization (`init_skill.py`) → Editing (populate) → Packaging (`package_skill.py`) → Iteration (test/improve)

**Agent Process**: Load `agent_creation.md` and `agent_template.md` → Define frontmatter (mode, permissions) → Create sections (workflow, capabilities, anti-patterns) → Validate → Test

**Command Process**: Load `command_template.md` → Define frontmatter (name, description) → Create execution logic → Add to command registry → Test

### Use Case: Flowchart Creation

Create ASCII flowcharts for visualizing workflows, user journeys and decision trees.

For styled HTML visuals (interactive diagrams, dashboard pages, or polished data-table renders), use a dedicated HTML workflow instead of forcing ASCII or markdown flowcharts.

**Use when**:
- Documenting multi-step processes with branching
- Creating decision trees with multiple outcomes
- Showing parallel execution with sync points
- Visualizing approval gates and revision cycles

**See**: [assets/flowcharts/](./assets/flowcharts/)

### Use Case: Install Guide Creation

Create and validate installation documentation for MCP servers, plugins and tools using phase-based templates.

**Use when**:
- Creating documentation for MCP server installation
- Documenting plugin setup procedures
- Standardizing tool installation across platforms
- Need phase-based validation checkpoints

**5-Phase Process**: Overview → Prerequisites → Installation → Configuration → Verification

**See**: [install_guide_creation.md](./references/install_guide_creation.md)

### Use Case: Manual Testing Playbook Creation

Create manual testing playbooks with deterministic scenarios, structured evidence collection, and multi-agent execution planning.

**Manual Testing Playbook** - Use `testing_playbook/manual_testing_playbook_template.md` when:
- Creating manual testing scenarios for a skill
- Standardizing test evidence and verdict criteria
- Setting up multi-agent test execution planning

**Canonical Package**: Root `manual_testing_playbook.md` plus numbered category folders with one per-feature file per feature ID.

**See**:
- [manual_testing_playbook_creation.md](./references/manual_testing_playbook_creation.md)
- [manual_testing_playbook_template.md](./assets/testing_playbook/manual_testing_playbook_template.md)

### Use Case: Feature Catalog Creation

Create feature catalogs with a rooted feature inventory, numbered category sections, and per-feature reference files.

**Feature Catalog** - Use `assets/feature_catalog/feature_catalog_template.md` when:
- Creating a canonical current-state feature inventory for a skill or system
- Linking manual playbooks back to a stable feature reference
- Documenting current behavior with source-file anchors and stable slugs

**Canonical Package**: Root `FEATURE_CATALOG.md` plus numbered category folders with one per-feature file per catalog entry.

**See**:
- [feature_catalog_creation.md](./references/feature_catalog_creation.md)
- [feature_catalog_template.md](./assets/feature_catalog/feature_catalog_template.md)

### When NOT to Use (All Modes)

- Non-markdown files (only `.md` supported)
- Simple typo fixes (use Edit tool directly)
- Internal notes or drafts
- Auto-generated API docs
- Short 2-3 step processes (use bullet points)

---

## 2. SMART ROUTING

> Pattern: see [sk-doc smart-router resilience template](./assets/skill/skill_smart_router.md).

### Resource Domains

The router discovers markdown resources recursively from `references/` and `assets/` and then applies intent scoring from `RESOURCE_MAP`. Keep this section domain-focused rather than static file inventories.

- `references/global/` for documentation standards, validation rules, optimization guidance, voice rules, and shared execution workflows.
- `references/` root for document-family and component creation guides such as skill creation, agent creation, install guides, feature catalogs, and manual testing playbooks.
- `assets/readme/` for README and install-guide scaffolds; `assets/changelog_template.md`, `assets/frontmatter_templates.md`, and `assets/llmstxt_templates.md` at the assets/ root for cross-cutting templates.
- `assets/skill/` for skill creation templates, including `SKILL.md`, skill README, reference and asset scaffolds; `assets/agent_template.md` and `assets/command_template.md` at the assets/ root for agent and command creation templates.
- `assets/feature_catalog/` and `assets/testing_playbook/` at the assets/ root for feature catalog and manual testing playbook package templates.
- `assets/flowcharts/` for reusable ASCII flowchart patterns and diagram examples.

> **Cross-CLI consumption note** (per packets 071/072 stress-test data): when sk-doc is dispatched via an external CLI and the caller consumes the routing-trace output LITERALLY (e.g. attempts to `Read()` cited resource paths), prefer **cli-codex** (gpt-5.5/high/fast) — it scored 66.7% resource-accuracy vs cli-opencode 47.2% on the sk-doc router stress matrix. claude-opus-4.7 tends to hallucinate plausible-sounding paths that don't exist in this skill's filesystem; treat its routing trace as advisory and verify cited paths before reading. See `specs/skilled-agent-orchestration/072-sk-doc-router-rerun-refined-extraction/review-report-v2.md` for the full data + P1-072-001 hallucination finding.

### Resource Loading Levels

| Level       | When to Load             | Resources                   |
| ----------- | ------------------------ | --------------------------- |
| ALWAYS      | Every skill invocation   | Quick reference baseline    |
| CONDITIONAL | If intent signals match  | Mode-specific docs/templates|
| ON_DEMAND   | Only on explicit request | Extended standards/template |

### Smart Router Pseudocode

The authoritative routing logic for scoped loading, weighted intent scoring, and ambiguity handling.

- Pattern 1: Runtime Discovery - `discover_markdown_resources()` recursively scans `references/` and `assets/`.
- Pattern 2: Existence-Check Before Load - `load_if_available()` guards, checks `inventory`, and suppresses repeats with `seen`.
- Pattern 3: Extensible Routing Key - intent labels route to document families without static inventories.
- Pattern 4: Multi-Tier Graceful Fallback - `UNKNOWN_FALLBACK` requests disambiguation and missing families return a "no knowledge base" notice.

```python
from pathlib import Path

SKILL_ROOT = Path(__file__).resolve().parent
RESOURCE_BASES = (SKILL_ROOT / "references", SKILL_ROOT / "assets")
DEFAULT_RESOURCE = "references/global/quick_reference.md"

INTENT_SIGNALS = {
    "DOC_QUALITY": {"weight": 4, "keywords": ["dqi", "quality", "validate", "extract_structure"]},
    "OPTIMIZATION": {"weight": 3, "keywords": ["optimize", "llms.txt", "ai context"]},
    "SKILL_CREATION": {"weight": 4, "keywords": ["skill creation", "new skill", "init_skill", "package_skill"]},
    "AGENT_COMMAND": {"weight": 4, "keywords": ["create agent", "create command", "agent template", "command template"]},
    "FLOWCHART": {"weight": 3, "keywords": ["flowchart", "ascii diagram", "decision tree", "swimlane"]},
    "INSTALL_GUIDE": {"weight": 3, "keywords": ["install guide", "setup instructions", "prerequisite"]},
    "HVR": {"weight": 4, "keywords": ["human voice", "hvr", "voice rules", "banned words", "writing style"]},
    "PLAYBOOK": {"weight": 4, "keywords": ["playbook", "manual testing", "test scenarios", "manual test", "testing playbook"]},
    "FEATURE_CATALOG": {"weight": 4, "keywords": ["feature catalog", "feature inventory", "catalog snippet"]},
    "README_CREATION": {"weight": 3, "keywords": ["create readme", "readme creation", "write readme", "add documentation", "folder readme"]},
    "CHANGELOG": {"weight": 4, "keywords": ["changelog", "release notes", "changelog template", "release template", "create changelog", "github release"]},
}

RESOURCE_MAP = {
    "DOC_QUALITY": ["references/global/validation.md", "references/global/workflows.md", "references/global/core_standards.md", "references/global/evergreen_packet_id_rule.md"],
    "OPTIMIZATION": ["references/global/optimization.md", "assets/llmstxt_templates.md"],
    "SKILL_CREATION": ["references/skill_creation.md", "assets/skill/skill_md_template.md", "assets/skill/skill_readme_template.md", "assets/skill/skill_reference_template.md"],
    "AGENT_COMMAND": ["references/agent_creation.md", "assets/agent_template.md", "assets/command_template.md"],
    "FLOWCHART": ["assets/flowcharts/simple_workflow.md", "assets/flowcharts/decision_tree_flow.md"],
    "INSTALL_GUIDE": ["assets/readme/install_guide_template.md", "references/install_guide_creation.md"],
    "HVR": ["references/global/hvr_rules.md"],
    "PLAYBOOK": ["references/manual_testing_playbook_creation.md", "assets/testing_playbook/manual_testing_playbook_template.md"],

exec
/bin/zsh -lc "sed -n '1,220p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/assets/changelog_template.md" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
---
title: Changelog & Release Notes Templates
description: Templates and writing-style rules for global component changelogs at .opencode/changelog/{NN--component}/v{VERSION}.md and the matching GitHub release notes.
---

# Changelog & Release Notes Templates - Format Reference

Two formats (compact and expanded) for global component changelogs and the matching GitHub release notes, plus writing-style rules and a pointer to nested packet-local changelogs.

---

## 1. OVERVIEW

### Purpose

Global component changelog files live at `.opencode/changelog/{NN--component}/v{VERSION}.md` and double as the body of GitHub releases. This asset gives the `/create:changelog` command (and human authors) a copy-paste starting point for both layouts, plus the voice and structure rules that keep the 370+ existing files consistent.

### Usage

The `/create:changelog` workflow reads this template at Step 4 of `create_changelog_auto.yaml` and `create_changelog_confirm.yaml`. Human authors can copy a format block directly. Choose **compact** for releases under 10 changes and **expanded** for releases with 10+ changes or a major bump - see Section 5 for the full selection guide.

Nested packet-local changelogs are a different output mode and use the spec-kit templates instead (see Section 7).

**Authoritative source for writing style rules:** `PUBLIC_RELEASE.md` Section 7

---

## 2. CHANGELOG FILE FORMAT

**Key Points**:
- Files start directly with the summary paragraph - no version header or boilerplate
- Lead with **WHY** the release matters, not technical stats
- Pick compact or expanded based on change count and bump type

### Compact Format (under 10 changes)

**Template**:

```markdown
{One-paragraph summary explaining what this release does and why it matters.}

> Spec folder: `{path}` (Level {N})

---

## What Changed

#### {Category Name}

- **{Feature/Fix name}** -- {What was broken or missing}. {What we did}. {Why it matters}.

## Files Changed

| File           | What changed      |
| -------------- | ----------------- |
| `path/to/file` | Brief description |

## Upgrade

No migration required.
```

### Expanded Format (10+ changes or major releases)

Use this format when individual fixes need full explanation - typically for audit results, major refactors, or releases where understanding the "why" behind each change matters.

**Template**:

```markdown
{One-paragraph summary explaining what this release does and why it matters. Include the scope (how many fixes), the test impact, and one sentence about the approach.}

> Spec folder: `{path}` (Level {N})

---

## {Category Name}

{Optional 1-2 sentence introduction for the category.}

#### {Short heading}

{One flowing paragraph that explains what was broken or missing AND what was done about it. Write for a smart person who is not a developer. State the broken behavior first, then the new behavior. Use analogies if they help. No unexplained jargon -- first use of a technical term includes a parenthetical definition like "BM25 (exact word matching)" or "CTE (a reusable SQL subquery)." Technical specifics (file paths, function names, SQL syntax) go in the Files Changed table, not here.}

&nbsp;

#### {Next heading}

{Same pattern -- one merged paragraph covering the broken behavior and the fix.}

---

## Test Impact

| Metric            | Before | After |
| ----------------- | ------ | ----- |
| Tests passing     | {N}    | {N}   |
| Test files        | {N}    | {N}   |
| TypeScript errors | 0      | 0     |

{One sentence about new tests added and existing tests updated.}

---

## Schema Changes (if applicable)

| Change         | Details                         |
| -------------- | ------------------------------- |
| Schema version | {old} to {new}                  |
| New indexes    | {count} ({list})                |
| New columns    | {name} on {table} for {purpose} |

{One sentence confirming backward compatibility.}

---

<details>
<summary>Technical Details: Files Changed ({total} total)</summary>

### Source ({count} files)

| File           | Changes                                                  |
| -------------- | -------------------------------------------------------- |
| `path/to/file` | {What changed -- function names, behaviors, SQL queries} |

### Tests ({count} files)

{One sentence about test coverage.}

### Documentation ({count} files)

{One sentence about doc updates.}

</details>

---

## Upgrade

{Migration instructions or "No migration required."}

{List any behavioral changes users should be aware of.}
```

**Field Guidelines**:

**`{Category Name}`** (compact format, H4):
- Use plain category names from Section 4 vocabulary
- Examples: `Search`, `Saving Memories`, `Bug Fixes`

**`{Short heading}`** (expanded format, H4):
- 2-5 words, easy to scan at a glance
- No packet IDs, no numbering, no sentence-length headings

**`Files Changed` table**:
- Compact format: simple two-column table
- Expanded format: collapsible `<details>` with grouped Source/Tests/Documentation tables

---

## 3. GITHUB RELEASE NOTES FORMAT

Changelog files start directly with the summary paragraph - no version header or boilerplate. Use the file content as-is for the `gh release create` body.

At the end, append:

```
Full changelog: `.opencode/changelog/{component}/v{VERSION}.md`
```

---

## 4. WRITING STYLE RULES

These rules apply to both changelog files and GitHub release notes. See `PUBLIC_RELEASE.md` Section 7 for the authoritative version.

### Voice

- Write like you are explaining to **a smart person who is not a developer**
- Lead with **WHY** this release matters, not technical stats
- Every fix explained as: **what was broken**, **what we did**, **why it matters**

### Jargon

- No jargon without explanation
- First use includes parenthetical definition: "BM25 (exact word matching)", "CTE (a reusable SQL subquery)"
- Technical details (file paths, line numbers, function names) go in Files Changed, not in descriptions

### Structure

- **Analogies welcome** when they help understanding
- **Short bullet points** (1-3 sentences each) in compact format
- **Single merged paragraph** in expanded format -- combine the broken behavior and the fix into one flowing paragraph. Do NOT use `**Problem:** / **Fix:**` labels.
- **Short sub-headings** in expanded format: 2-5 words, easy to scan, not sentence-length
- **No numbered item titles** in expanded format unless the content truly depends on sequence
- **No metrics soup** -- do not pack 10 numbers into one sentence
- **H4 (`####`) for category subsections** under each H2 -- never H3
- **`&nbsp;` between H4 subsections within the same H2** -- this is the soft separator that renders as an invisible line on GitHub. Do NOT use `---` between H4s.
- **`---` only between H2 sections** -- place a `---` divider before each `##` heading. Do NOT place `---` (or `&nbsp;`) between an H2 (or its intro paragraph) and the first H4 underneath it.
- **No Oxford commas, em dashes, or semicolons** -- see HVR rules in `.opencode/skills/sk-doc/references/global/hvr_rules.md`

### Category Vocabulary (use plain names)

- `Search` -- search behavior, ranking, matching
- `Saving Memories` -- memory save, context preservation
- `Security` -- access control, input validation
- `Documentation` -- templates, guides, READMEs
- `Testing` -- test suites, validation
- `Commands` -- CLI workflows, user-facing commands
- `New Features` -- newly added capabilities
- `Bug Fixes` -- repairs, patches, corrections
- `Architecture` -- structural changes, refactoring
- `Breaking Changes` -- compatibility impacts, migration required

---

## 5. FORMAT SELECTION GUIDE

| Release Type                  | Format   | When to Use                                           |
| ----------------------------- | -------- | ----------------------------------------------------- |
| Hotfix (1-3 changes)          | Compact  | Quick bug fix, typo correction                        |

exec
/bin/zsh -lc "sed -n '1,220p' /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/references/changelog_creation.md" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 exited 1 in 0ms:
sed: /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/references/changelog_creation.md: No such file or directory

codex
One detail shifted under the evidence: `assets/changelog_template.md` exists, but the expected `references/changelog_creation.md` path does not. That matters for the prompt-fix: it should not promise loading a missing reference unless the scenario’s resource expectation is also updated.
exec
/bin/zsh -lc "rg --files /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc | rg 'changelog|create_changelog'" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/assets/changelog_template.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.0.2.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.0.3.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.0.8.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.1.0.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.0.4.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.3.0.1.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.0.5.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.3.0.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.0.9.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.4.1.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.0.6.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.1.2.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.1.3.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.0.7.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.4.0.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.3.0.2.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.0.0.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.2.0.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/changelog/v1.0.1.0.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/scripts/tests/test_changelog_validator.py

exec
/bin/zsh -lc "find /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/agents -maxdepth 1 -type f -name '*.toml' -print" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/agents/context.toml
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/agents/deep-agent-improvement.toml
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/agents/review.toml
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/agents/prompt-improver.toml
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/agents/deep-review.toml
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/agents/deep-research.toml
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/agents/deep-ai-council.toml
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/agents/orchestrate.toml
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/agents/code.toml
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/agents/debug.toml
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.codex/agents/markdown.toml

exec
/bin/zsh -lc "rg -n \"changelog_creation|create_changelog|CHANGELOG|changelog_template|/create:changelog\" /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc -g '*.md' -g '*.yaml'" in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md:40:**Changelog & Release Notes** - Use `changelog_template.md` when:
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md:44:- Template: [changelog_template.md](./assets/changelog_template.md). Used by `/create:changelog` (auto + confirm). Nested packet-local changelogs use the spec-kit templates at `.opencode/skills/system-spec-kit/templates/changelog/` instead.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md:167:- `assets/readme/` for README and install-guide scaffolds; `assets/changelog_template.md`, `assets/frontmatter_templates.md`, and `assets/llmstxt_templates.md` at the assets/ root for cross-cutting templates.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md:209:    "CHANGELOG": {"weight": 4, "keywords": ["changelog", "release notes", "changelog template", "release template", "create changelog", "github release"]},
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md:223:    "CHANGELOG": ["assets/changelog_template.md"],
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/03--unknown-fallback/003-disambiguation-required.md:44:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/03--unknown-fallback/002-no-keyword-match.md:42:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/assets/llmstxt_templates.md:586:- [Changelog](https://github.com/example/dataflow/blob/main/CHANGELOG.md): Version history and release notes
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/assets/llmstxt_templates.md:770:- [Changelog](https://github.com/example/doc-optimizer/blob/main/CHANGELOG.md): Version history and updates
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/assets/llmstxt_templates.md:798:- **Documentation**: Essential files (README, SKILL.md, CHANGELOG)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/README.md:209:│   ├── changelog_template.md                    # Global changelog and GitHub release notes
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/assets/changelog_template.md:16:Global component changelog files live at `.opencode/changelog/{NN--component}/v{VERSION}.md` and double as the body of GitHub releases. This asset gives the `/create:changelog` command (and human authors) a copy-paste starting point for both layouts, plus the voice and structure rules that keep the 370+ existing files consistent.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/assets/changelog_template.md:20:The `/create:changelog` workflow reads this template at Step 4 of `create_changelog_auto.yaml` and `create_changelog_confirm.yaml`. Human authors can copy a format block directly. Choose **compact** for releases under 10 changes and **expanded** for releases with 10+ changes or a major bump - see Section 5 for the full selection guide.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/assets/changelog_template.md:28:## 2. CHANGELOG FILE FORMAT
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/assets/changelog_template.md:249:## 7. NESTED PACKET-LOCAL CHANGELOGS
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/assets/changelog_template.md:288:- [.opencode/commands/create/changelog.md](../../../../command/create/changelog.md) - The `/create:changelog` command surface
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md:40:**Changelog & Release Notes** - Use `changelog_template.md` when:
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md:44:- Template: [changelog_template.md](./assets/changelog_template.md). Used by `/create:changelog` (auto + confirm). Nested packet-local changelogs use the spec-kit templates at `.opencode/skills/system-spec-kit/templates/changelog/` instead.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md:167:- `assets/readme/` for README and install-guide scaffolds; `assets/changelog_template.md`, `assets/frontmatter_templates.md`, and `assets/llmstxt_templates.md` at the assets/ root for cross-cutting templates.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md:209:    "CHANGELOG": {"weight": 4, "keywords": ["changelog", "release notes", "changelog template", "release template", "create changelog", "github release"]},
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/SKILL.md:223:    "CHANGELOG": ["assets/changelog_template.md"],
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/03--unknown-fallback/001-ambiguous-multi-intent.md:46:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:8:expected_intent: CHANGELOG
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:11:  - assets/changelog_template.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:12:  - references/changelog_creation.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:22:This scenario validates that `cli-codex` (gpt-5.5/fast/high) correctly routes a `/create:changelog` task to the `@markdown` agent and that the agent loads sk-doc CHANGELOG resources before scaffolding the output.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:33:- Prompt: `Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-codex.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:34:- Expected intent: `CHANGELOG`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:36:- Desired user-visible outcome: A scaffolded changelog file at `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md` with Keep-a-Changelog sections, plus a transcript showing `@markdown` Phase 0 verification ran before the YAML workflow loaded.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:42:| SD-019 | @markdown via cli-codex | Verify `@markdown` agent receives `/create:changelog` work dispatched through cli-codex. | See Setup. | See Setup. | `@markdown` Phase 0 verification text appears in transcript; CHANGELOG asset reference appears; output file written. | Transcript + output changelog content. | PASS when `@markdown` invocation appears AND output file exists AND has Keep-a-Changelog sections. PARTIAL if `@markdown` invoked but output incomplete. FAIL if a different agent answered. SKIP if `codex` binary unavailable. | Re-check `.codex/agents/markdown.toml` exists; verify `.codex/config.toml` registers `agents.markdown`; verify network-access + fast flags applied. |
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:53:PROMPT='Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-codex.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.'
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:73:grep -c 'changelog_template\|changelog_creation\|Keep-a-Changelog' "$EVIDENCE"
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:76:test -f /tmp/sk-test-dummy-CHANGELOG-cli-codex.md && \
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:77:  grep -cE '^## .*(Added|Changed|Fixed|Removed)' /tmp/sk-test-dummy-CHANGELOG-cli-codex.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:82:- **Intent picked**: `CHANGELOG`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:85:  - `.opencode/skills/sk-doc/assets/changelog_template.md`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:86:  - `.opencode/skills/sk-doc/references/changelog_creation.md`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/002-markdown-agent-cli-codex.md:87:- **Outcome**: CLI scaffolds a v0.1.0 changelog file with Added / Changed / Fixed / Removed sections at `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md`.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/manual_testing_playbook.md:66:- **SD-010** — `04--cross-cli-dispatch/001-short-prompt-baseline.md` — Short-prompt CHANGELOG baseline across all 3 CLIs.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/manual_testing_playbook.md:76:- **SD-018** — `06--agent-dispatch/001-markdown-agent-cli-claude-code.md` — `@markdown` agent dispatch via cli-claude-code; `/create:changelog` for stub `sk-test-dummy`.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:6:expected_intent: CHANGELOG
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:9:  - assets/changelog_template.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:10:  - references/changelog_creation.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:20:This scenario validates that `cli-opencode`, when pointed at the DeepSeek v4 Pro model through the direct DeepSeek API (NOT the opencode-go gateway), correctly routes a `/create:changelog` task to the `@markdown` agent and loads sk-doc CHANGELOG resources before scaffolding the output.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:31:- Prompt: `Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-opencode.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:32:- Expected intent: `CHANGELOG`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:34:- Desired user-visible outcome: A scaffolded changelog file at `/tmp/sk-test-dummy-CHANGELOG-cli-opencode.md` with Keep-a-Changelog sections, plus a JSON-format transcript showing the `@markdown` agent received the work.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:40:| SD-020 | @markdown via cli-opencode + DeepSeek v4 Pro direct | Verify `@markdown` agent receives `/create:changelog` work dispatched through cli-opencode with DeepSeek v4 Pro through DeepSeek API. | See Setup. | See Setup. | `@markdown` agent invocation appears in JSON transcript; CHANGELOG asset reference appears; output file written. | Transcript + output changelog content. | PASS when `@markdown` invocation appears AND output file exists AND has Keep-a-Changelog sections. PARTIAL if `@markdown` invoked but output incomplete. FAIL if a different agent answered or DeepSeek rejected the tool-name regex. SKIP if `opencode` binary or `deepseek` provider auth unavailable. | Verify `opencode providers list` shows `deepseek`; confirm `--pure` strips the MCP skills surface; confirm `</dev/null` redirect applied. |
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:53:PROMPT='Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-opencode.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.'
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:82:grep -c 'changelog_template\|changelog_creation\|Keep-a-Changelog' "$EVIDENCE"
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:85:test -f /tmp/sk-test-dummy-CHANGELOG-cli-opencode.md && \
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:86:  grep -cE '^## .*(Added|Changed|Fixed|Removed)' /tmp/sk-test-dummy-CHANGELOG-cli-opencode.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:91:- **Intent picked**: `CHANGELOG`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:94:  - `.opencode/skills/sk-doc/assets/changelog_template.md`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:95:  - `.opencode/skills/sk-doc/references/changelog_creation.md`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/003-markdown-agent-cli-opencode.md:96:- **Outcome**: CLI scaffolds a v0.1.0 changelog file with Added / Changed / Fixed / Removed sections at `/tmp/sk-test-dummy-CHANGELOG-cli-opencode.md`.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/references/global/quick_reference.md:179:│   ├── changelog_template.md (changelog/release-notes template)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:6:expected_intent: CHANGELOG
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:9:  - assets/changelog_template.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:10:  - references/changelog_creation.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:20:This scenario validates that `cli-claude-code` correctly routes a `/create:changelog` task to the `@markdown` agent (the dedicated documentation executor introduced in 102-sk-doc-skill-readme-and-structure/003-markdown-agent-rename), and that the agent loads sk-doc CHANGELOG resources before scaffolding the output.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:31:- Prompt: `Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-claude-code.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:32:- Expected intent: `CHANGELOG`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:34:- Desired user-visible outcome: A scaffolded changelog file at `/tmp/sk-test-dummy-CHANGELOG-cli-claude-code.md` with Keep-a-Changelog sections, plus a transcript showing `@markdown` Phase 0 verification ran before the YAML workflow loaded.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:40:| SD-018 | @markdown via cli-claude-code | Verify `@markdown` agent receives `/create:changelog` work dispatched through cli-claude-code. | See Setup. | See Setup. | `@markdown` Phase 0 verification text appears in transcript; CHANGELOG asset reference appears; output file written. | Transcript + output changelog content. | PASS when `@markdown` invocation appears AND output file exists AND has Keep-a-Changelog sections. PARTIAL if `@markdown` invoked but output incomplete. FAIL if a different agent answered. SKIP if `claude` binary unavailable. | Re-check `.claude/agents/markdown.md` exists; re-check `.opencode/commands/create/changelog.md` Phase 0 block. |
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:47:PROMPT='Use the @markdown agent to scaffold a v0.1.0 changelog for a stub skill named sk-test-dummy via /create:changelog. Write the result to /tmp/sk-test-dummy-CHANGELOG-cli-claude-code.md. Do NOT install the stub skill into the .opencode/skills/ tree. Report which agent received the work, which sk-doc resources were loaded, and the changelog sections produced.'
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:64:grep -c 'changelog_template\|changelog_creation\|Keep-a-Changelog' "$EVIDENCE"
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:67:test -f /tmp/sk-test-dummy-CHANGELOG-cli-claude-code.md && \
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:68:  grep -cE '^## .*(Added|Changed|Fixed|Removed)' /tmp/sk-test-dummy-CHANGELOG-cli-claude-code.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:73:- **Intent picked**: `CHANGELOG`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:76:  - `.opencode/skills/sk-doc/assets/changelog_template.md`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:77:  - `.opencode/skills/sk-doc/references/changelog_creation.md`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/06--agent-dispatch/001-markdown-agent-cli-claude-code.md:78:- **Outcome**: CLI scaffolds a v0.1.0 changelog file with Added / Changed / Fixed / Removed sections at `/tmp/sk-test-dummy-CHANGELOG-cli-claude-code.md`.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/05--token-cost-baseline/001-minimal-load.md:43:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/01--intent-detection/003-agent-command.md:45:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/02--resource-loading/003-mixed-references-assets.md:44:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/02--resource-loading/001-references-global-only.md:43:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/01--intent-detection/001-doc-quality.md:46:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/05--token-cost-baseline/002-medium-load.md:46:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/02--resource-loading/002-assets-only.md:44:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/05--token-cost-baseline/003-max-load.md:25:  - assets/changelog_template.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/05--token-cost-baseline/003-max-load.md:63:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/01--intent-detection/002-skill-creation.md:46:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/01--intent-detection/005-install-guide.md:44:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/01--intent-detection/004-optimization.md:44:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/001-short-prompt-baseline.md:4:title: 'Short-prompt baseline: CHANGELOG intent across all 3 CLIs'
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/001-short-prompt-baseline.md:5:expected_intent: CHANGELOG
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/001-short-prompt-baseline.md:7:  - assets/changelog_template.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/001-short-prompt-baseline.md:13:# SD-010: Short-Prompt Baseline (CHANGELOG)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/001-short-prompt-baseline.md:17:This scenario validates CHANGELOG routing across CLI dispatch paths for `SD-010`. It focuses on a short release-notes prompt that should load changelog guidance and template resources consistently.
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/001-short-prompt-baseline.md:29:- Expected intent: `CHANGELOG`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/001-short-prompt-baseline.md:36:| SD-010 | Short-prompt baseline: CHANGELOG intent across all 3 CLIs | Verify sk-doc routes the scenario to `CHANGELOG` with the expected resources. | `Draft a v2.3.0 changelog with added, changed, fixed, and removed sections.` | Run the setup block below against sk-doc and capture the routing trace. | Intent resolves to `CHANGELOG`; loaded resources match `expected_resources`. | CLI transcript with intent, resources, response shape, token counts where applicable. | PASS when intent/resources/output match the scenario criteria; PARTIAL for tolerated extra resources; FAIL for wrong intent or empty output. | Re-read `SKILL.md` smart-router RESOURCE_MAP and intent keywords, then compare against the routed prompt. |
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/001-short-prompt-baseline.md:43:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/001-short-prompt-baseline.md:57:- **Intent picked**: `CHANGELOG`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/001-short-prompt-baseline.md:59:  - `assets/changelog_template.md`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/001-short-prompt-baseline.md:69:- intent_picked == `CHANGELOG`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/003-multi-step-dispatch.md:5:expected_intent: SKILL_CREATION → DOC_QUALITY → CHANGELOG
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/003-multi-step-dispatch.md:12:  - assets/changelog_template.md
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/003-multi-step-dispatch.md:34:- Expected intent: `SKILL_CREATION → DOC_QUALITY → CHANGELOG`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/003-multi-step-dispatch.md:41:| SD-012 | Multi-step dispatch: 3 sequential sk-doc invocations | Verify sk-doc routes the scenario to `SKILL_CREATION → DOC_QUALITY → CHANGELOG` with the expected resources. | `Trace routing for three sequential sk-doc turns: create sk-foo, add validation rules, then generate a v0.1.0 changelog.` | Run the setup block below against sk-doc and capture the routing trace. | Intent resolves to `SKILL_CREATION → DOC_QUALITY → CHANGELOG`; loaded resources match `expected_resources`. | CLI transcript with intent, resources, response shape, token counts where applicable. | PASS when intent/resources/output match the scenario criteria; PARTIAL for tolerated extra resources; FAIL for wrong intent or empty output. | Re-read `SKILL.md` smart-router RESOURCE_MAP and intent keywords, then compare against the routed prompt. |
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/003-multi-step-dispatch.md:48:1. Which sk-doc intent the router would select for EACH of the 3 inputs in sequence (pick from RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/003-multi-step-dispatch.md:60:- **Intents picked (in order)**: `SKILL_CREATION` → `DOC_QUALITY` (validation rules) → `CHANGELOG`
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/003-multi-step-dispatch.md:71:- each turn's intent matches the expected order (SKILL_CREATION, DOC_QUALITY, CHANGELOG)
/Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/skills/sk-doc/manual_testing_playbook/04--cross-cli-dispatch/002-large-prompt-stress.md:46:1. Which sk-doc intent the router would select for the input (pick from the 11-intent RESOURCE_MAP: DOC_QUALITY, OPTIMIZATION, SKILL_CREATION, AGENT_COMMAND, FLOWCHART, INSTALL_GUIDE, HVR, PLAYBOOK, FEATURE_CATALOG, README_CREATION, CHANGELOG; or UNKNOWN_FALLBACK if no keywords match)

exec
/bin/zsh -lc 'codex --help' in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
WARNING: proceeding, even though we could not update PATH: Operation not permitted (os error 1)
Codex CLI

If no subcommand is specified, options will be forwarded to the interactive CLI.

Usage: codex [OPTIONS] [PROMPT]
       codex [OPTIONS] <COMMAND> [ARGS]

Commands:
  exec            Run Codex non-interactively [aliases: e]
  review          Run a code review non-interactively
  login           Manage login
  logout          Remove stored authentication credentials
  mcp             Manage external MCP servers for Codex
  plugin          Manage Codex plugins
  mcp-server      Start Codex as an MCP server (stdio)
  app-server      [experimental] Run the app server or related tooling
  remote-control  [experimental] Start a headless app-server with remote control enabled
  app             Launch the Codex desktop app (opens the app installer if missing)
  completion      Generate shell completion scripts
  update          Update Codex to the latest version
  sandbox         Run commands within a Codex-provided sandbox
  debug           Debugging tools
  apply           Apply the latest diff produced by Codex agent as a `git apply` to your local
                  working tree [aliases: a]
  resume          Resume a previous interactive session (picker by default; use --last to continue
                  the most recent)
  fork            Fork a previous interactive session (picker by default; use --last to fork the
                  most recent)
  cloud           [EXPERIMENTAL] Browse tasks from Codex Cloud and apply changes locally
  exec-server     [EXPERIMENTAL] Run the standalone exec-server service
  features        Inspect feature flags
  help            Print this message or the help of the given subcommand(s)

Arguments:
  [PROMPT]
          Optional user prompt to start the session

Options:
  -c, --config <key=value>
          Override a configuration value that would otherwise be loaded from `~/.codex/config.toml`.
          Use a dotted path (`foo.bar.baz`) to override nested values. The `value` portion is parsed
          as TOML. If it fails to parse as TOML, the raw string is used as a literal.
          
          Examples: - `-c model="o3"` - `-c 'sandbox_permissions=["disk-full-read-access"]'` - `-c
          shell_environment_policy.inherit=all`

      --enable <FEATURE>
          Enable a feature (repeatable). Equivalent to `-c features.<name>=true`

      --disable <FEATURE>
          Disable a feature (repeatable). Equivalent to `-c features.<name>=false`

      --remote <ADDR>
          Connect the TUI to a remote app server websocket endpoint.
          
          Accepted forms: `ws://host:port` or `wss://host:port`.

      --remote-auth-token-env <ENV_VAR>
          Name of the environment variable containing the bearer token to send to a remote app
          server websocket

  -i, --image <FILE>...
          Optional image(s) to attach to the initial prompt

  -m, --model <MODEL>
          Model the agent should use

      --oss
          Use open-source provider

      --local-provider <OSS_PROVIDER>
          Specify which local provider to use (lmstudio or ollama). If not specified with --oss,
          will use config default or show selection

  -p, --profile <CONFIG_PROFILE>
          Configuration profile from config.toml to specify default options

  -s, --sandbox <SANDBOX_MODE>
          Select the sandbox policy to use when executing model-generated shell commands
          
          [possible values: read-only, workspace-write, danger-full-access]

      --dangerously-bypass-approvals-and-sandbox
          Skip all confirmation prompts and execute commands without sandboxing. EXTREMELY
          DANGEROUS. Intended solely for running in environments that are externally sandboxed

  -C, --cd <DIR>
          Tell the agent to use the specified directory as its working root

      --add-dir <DIR>
          Additional directories that should be writable alongside the primary workspace

  -a, --ask-for-approval <APPROVAL_POLICY>
          Configure when the model requires human approval before executing a command

          Possible values:
          - untrusted:  Only run "trusted" commands (e.g. ls, cat, sed) without asking for user
            approval. Will escalate to the user if the model proposes a command that is not in the
            "trusted" set
          - on-failure: DEPRECATED: Run all commands without asking for user approval. Only asks for
            approval if a command fails to execute, in which case it will escalate to the user to
            ask for un-sandboxed execution. Prefer `on-request` for interactive runs or `never` for
            non-interactive runs
          - on-request: The model decides when to ask the user for approval
          - never:      Never ask for user approval Execution failures are immediately returned to
            the model

      --search
          Enable live web search. When enabled, the native Responses `web_search` tool is available
          to the model (no per‑call approval)

      --no-alt-screen
          Disable alternate screen mode
          
          Runs the TUI in inline mode, preserving terminal scrollback history. This is useful in
          terminal multiplexers like Zellij that follow the xterm spec strictly and disable
          scrollback in alternate screen buffers.

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

exec
/bin/zsh -lc 'codex exec --help' in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
WARNING: proceeding, even though we could not update PATH: Operation not permitted (os error 1)
Run Codex non-interactively

Usage: codex exec [OPTIONS] [PROMPT]
       codex exec [OPTIONS] <COMMAND> [ARGS]

Commands:
  resume  Resume a previous session by id or pick the most recent with --last
  review  Run a code review against the current repository
  help    Print this message or the help of the given subcommand(s)

Arguments:
  [PROMPT]
          Initial instructions for the agent. If not provided as an argument (or if `-` is used),
          instructions are read from stdin. If stdin is piped and a prompt is also provided, stdin
          is appended as a `<stdin>` block

Options:
  -c, --config <key=value>
          Override a configuration value that would otherwise be loaded from `~/.codex/config.toml`.
          Use a dotted path (`foo.bar.baz`) to override nested values. The `value` portion is parsed
          as TOML. If it fails to parse as TOML, the raw string is used as a literal.
          
          Examples: - `-c model="o3"` - `-c 'sandbox_permissions=["disk-full-read-access"]'` - `-c
          shell_environment_policy.inherit=all`

      --enable <FEATURE>
          Enable a feature (repeatable). Equivalent to `-c features.<name>=true`

      --disable <FEATURE>
          Disable a feature (repeatable). Equivalent to `-c features.<name>=false`

  -i, --image <FILE>...
          Optional image(s) to attach to the initial prompt

  -m, --model <MODEL>
          Model the agent should use

      --oss
          Use open-source provider

      --local-provider <OSS_PROVIDER>
          Specify which local provider to use (lmstudio or ollama). If not specified with --oss,
          will use config default or show selection

  -p, --profile <CONFIG_PROFILE>
          Configuration profile from config.toml to specify default options

  -s, --sandbox <SANDBOX_MODE>
          Select the sandbox policy to use when executing model-generated shell commands
          
          [possible values: read-only, workspace-write, danger-full-access]

      --dangerously-bypass-approvals-and-sandbox
          Skip all confirmation prompts and execute commands without sandboxing. EXTREMELY
          DANGEROUS. Intended solely for running in environments that are externally sandboxed

  -C, --cd <DIR>
          Tell the agent to use the specified directory as its working root

      --add-dir <DIR>
          Additional directories that should be writable alongside the primary workspace

      --skip-git-repo-check
          Allow running Codex outside a Git repository

      --ephemeral
          Run without persisting session files to disk

      --ignore-user-config
          Do not load `$CODEX_HOME/config.toml`; auth still uses `CODEX_HOME`

      --ignore-rules
          Do not load user or project execpolicy `.rules` files

      --output-schema <FILE>
          Path to a JSON Schema file describing the model's final response shape

      --color <COLOR>
          Specifies color settings for use in the output
          
          [default: auto]
          [possible values: always, never, auto]

      --json
          Print events to stdout as JSONL

  -o, --output-last-message <FILE>
          Specifies file where the last message from the agent should be written

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

exec
/bin/zsh -lc 'codex features list' in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
WARNING: proceeding, even though we could not update PATH: Operation not permitted (os error 1)
apply_patch_freeform                    under development  false
apply_patch_streaming_events            under development  false
apps                                    stable             true
apps_mcp_path_override                  under development  false
artifact                                under development  false
auth_elicitation                        under development  false
browser_use                             stable             true
browser_use_external                    stable             true
builtin_mcp                             under development  false
child_agents_md                         under development  true
chronicle                               under development  false
code_mode                               under development  true
code_mode_only                          under development  false
codex_git_commit                        under development  false
collaboration_modes                     removed            true
computer_use                            stable             true
default_mode_request_user_input         under development  false
elevated_windows_sandbox                removed            false
enable_fanout                           under development  false
enable_mcp_apps                         under development  false
enable_request_compression              stable             true
exec_permission_approvals               under development  false
experimental_windows_sandbox            removed            false
external_migration                      experimental       false
fast_mode                               stable             true
goals                                   experimental       false
guardian_approval                       stable             true
hooks                                   stable             true
image_detail_original                   removed            false
image_generation                        stable             true
in_app_browser                          stable             true
js_repl                                 removed            false
js_repl_tools_only                      removed            false
memories                                experimental       false
multi_agent                             stable             true
multi_agent_v2                          under development  false
personality                             stable             true
plugin_hooks                            under development  false
plugins                                 stable             true
prevent_idle_sleep                      experimental       false
realtime_conversation                   under development  false
remote_compaction_v2                    under development  false
remote_control                          under development  false
remote_models                           removed            false
remote_plugin                           under development  false
request_permissions_tool                under development  false
request_rule                            removed            false
responses_websocket_response_processed  under development  false
responses_websockets                    removed            false
responses_websockets_v2                 removed            false
runtime_metrics                         under development  false
search_tool                             removed            false
shell_snapshot                          stable             true
shell_tool                              stable             true
shell_zsh_fork                          under development  false
skill_env_var_dependency_prompt         under development  false
skill_mcp_dependency_install            stable             true
sqlite                                  removed            true
steer                                   removed            true
terminal_resize_reflow                  experimental       true
tool_call_mcp_elicitation               stable             true
tool_search                             stable             true
tool_search_always_defer_mcp_tools      under development  false
tool_suggest                            stable             true
tui_app_server                          removed            true
unavailable_dummy_tools                 stable             true
undo                                    removed            false
unified_exec                            stable             true
use_legacy_landlock                     deprecated         false
use_linux_sandbox_bwrap                 removed            false
web_search_cached                       deprecated         false
web_search_request                      deprecated         false
workspace_dependencies                  stable             true
workspace_owner_usage_nudge             under development  false

exec
/bin/zsh -lc 'codex debug --help' in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
WARNING: proceeding, even though we could not update PATH: Operation not permitted (os error 1)
Debugging tools

Usage: codex debug [OPTIONS] <COMMAND>

Commands:
  models        Render the raw model catalog as JSON
  app-server    Tooling: helps debug the app server
  prompt-input  Render the model-visible prompt input list as JSON
  help          Print this message or the help of the given subcommand(s)

Options:
  -c, --config <key=value>
          Override a configuration value that would otherwise be loaded from `~/.codex/config.toml`.
          Use a dotted path (`foo.bar.baz`) to override nested values. The `value` portion is parsed
          as TOML. If it fails to parse as TOML, the raw string is used as a literal.
          
          Examples: - `-c model="o3"` - `-c 'sandbox_permissions=["disk-full-read-access"]'` - `-c
          shell_environment_policy.inherit=all`

      --enable <FEATURE>
          Enable a feature (repeatable). Equivalent to `-c features.<name>=true`

      --disable <FEATURE>
          Disable a feature (repeatable). Equivalent to `-c features.<name>=false`

  -h, --help
          Print help (see a summary with '-h')

exec
/bin/zsh -lc 'codex debug prompt-input --help' in /Users/michelkerkmeester/MEGA/Development/Code_Environment/Public/.opencode/specs/skilled-agent-orchestration/102-sk-doc-skill-readme-and-structure
 succeeded in 0ms:
WARNING: proceeding, even though we could not update PATH: Operation not permitted (os error 1)
Render the model-visible prompt input list as JSON

Usage: codex debug prompt-input [OPTIONS] [PROMPT]

Arguments:
  [PROMPT]
          Optional user prompt to append after session context

Options:
  -c, --config <key=value>
          Override a configuration value that would otherwise be loaded from `~/.codex/config.toml`.
          Use a dotted path (`foo.bar.baz`) to override nested values. The `value` portion is parsed
          as TOML. If it fails to parse as TOML, the raw string is used as a literal.
          
          Examples: - `-c model="o3"` - `-c 'sandbox_permissions=["disk-full-read-access"]'` - `-c
          shell_environment_policy.inherit=all`

  -i, --image <FILE>...
          Optional image(s) to attach to the user prompt

      --enable <FEATURE>
          Enable a feature (repeatable). Equivalent to `-c features.<name>=true`

      --disable <FEATURE>
          Disable a feature (repeatable). Equivalent to `-c features.<name>=false`

  -h, --help
          Print help (see a summary with '-h')

codex
## Section A — Root Cause Verification

Your two-registry hypothesis is right in the practical sense: `.codex/config.toml` registers `agents.markdown`, but the `SpawnAgent` runtime path in SD-019 did not expose `markdown` as an available `agent_type`.

The transcript shows two separate failures:

1. `Full-history forked agents inherit...`
   This means Codex first tried to spawn with a full-history fork while also specifying `agent_type`, `model`, or `reasoning_effort`. That combination is invalid before `markdown` availability is even checked.

2. `agent type is currently not available`
   This is the real `markdown` blocker. After retrying, the router rejected the typed agent itself.

There is also a model-behavior issue: the prompt says “Use the `@markdown` agent”, so the AI reasonably reached for `SpawnAgent`. In `codex exec`, that is the wrong surface for this configured agent. The fallback generic sub-agent was not a resolver; it was an improvised workaround, and it then hit Gate 3.

A third interpretation: `.codex/config.toml` may be for interactive multi-agent/TUI context, while `codex exec`’s collab tool uses a separate tool-schema allowlist. That is slightly more precise than “config is read for CLI context”; the config is present, but not sufficient for this SpawnAgent route.

## Section B — Prompt-Fix Viability

Yes, the prompt-fix is viable if you make two changes explicit.

First, Codex can follow `.codex/agents/markdown.toml` inline. It is plain TOML with a `developer_instructions` block. A `gpt-5.5` Codex run can read it, read `sk-doc/SKILL.md`, read `assets/changelog_template.md`, and write the changelog directly.

Second, you must pre-answer Gate 3. The actual classifier triggers on file-write tokens like `write`, `create`, and `generate`; there is no `/tmp` exemption. So writing `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md` still trips Gate 3 unless the prompt says the user’s Gate 3 answer is `D) Skip`.

Risk that Codex still reaches for `SpawnAgent`: low if the rewritten prompt avoids “Use the @markdown agent” as an imperative and explicitly says “do not call SpawnAgent/collab/Task.” The old prompt strongly pulled the model toward sub-agent dispatch. The new one should frame the task as “inline execution of the markdown contract.”

One more issue: `references/changelog_creation.md` does not exist. `sk-doc/SKILL.md` maps `CHANGELOG` to `assets/changelog_template.md`. If SD-019 keeps expecting that missing reference, the prompt-fix can still fail on resource evidence.

## Section C — Alternative Remediations

- CLI flag/env var: I checked `codex --help`, `codex exec --help`, and `codex features list`. No `--agent`, `codex agent`, or obvious config/env bridge exists. Upside would be real dispatch; cost is unknown and probably upstream-dependent.

- Register `markdown` in SpawnAgent allowlist: no local mechanism visible. The allowlist appears to come from runtime/tool metadata, not `.codex/config.toml`.

- Restructure `.codex/agents/markdown.toml`: unlikely to help. The TOML is complete, and the error is not a parse/config error. Other agents are registered the same way.

- `codex agent markdown ...`: no such subcommand in v0.130.0.

- `codex exec --profile markdown`: profiles are config profiles, not agent dispatch. You could make a profile inject instructions, but that is just the prompt-fix moved into config.

- Spawn a generic sub-agent with inline markdown instructions: possible, but worse. It adds another agent boundary, can hit Gate 3 again, and still does not prove `@markdown` dispatch.

## Section D — Recommended Decision

Pick **2. SWAP TO “prompt-fix workaround.”**

Do not claim the runtime `SpawnAgent` issue is fixed. Classify F-001 as “resolved via inline workaround” and keep a note that typed `markdown` dispatch remains unavailable under this `codex exec` path.

Exact Setup prompt I would use:

```text
Run this as an inline Codex execution of the @markdown contract. Do NOT call SpawnAgent, collab: SpawnAgent, Task, or any sub-agent. If you are about to dispatch, stop and perform the work inline instead.

This is the user’s consolidated Gate 3 answer for this run: D) Skip spec-folder creation. The only allowed write is /tmp/sk-test-dummy-CHANGELOG-cli-codex.md. specFolder=none. Do not ask interactive questions; stdin is closed.

Follow .codex/agents/markdown.toml developer_instructions inline for /create:changelog.

Resolved setup bindings:
command_name=/create:changelog
execution_mode=AUTONOMOUS
target=sk-test-dummy
output_path=/tmp/sk-test-dummy-CHANGELOG-cli-codex.md
template_path=.opencode/skills/sk-doc/assets/changelog_template.md
spec_folder=none

Before any file reads, print these binding lines:
BINDING: command=/create:changelog
BINDING: target=sk-test-dummy
BINDING: output=/tmp/sk-test-dummy-CHANGELOG-cli-codex.md
BINDING: template=.opencode/skills/sk-doc/assets/changelog_template.md
BINDING: mode=AUTONOMOUS
BINDING: specFolder=none

Then read:
1. .codex/agents/markdown.toml
2. .opencode/skills/sk-doc/SKILL.md
3. .opencode/skills/sk-doc/assets/changelog_template.md

Create a compact v0.1.0 changelog for stub skill sk-test-dummy at /tmp/sk-test-dummy-CHANGELOG-cli-codex.md. Do NOT install or create anything under .opencode/skills/.

Final report must include:
AGENT_RECEIVED=inline-codex-following-.codex/agents/markdown.toml
SPAWN_AGENT_USED=no
SK_DOC_RESOURCES_LOADED=<actual existing paths loaded>
CHANGELOG_SECTIONS=<sections produced>
STATUS=OK PATH=/tmp/sk-test-dummy-CHANGELOG-cli-codex.md
```

## Section E — Caveats And Uncertainty

I did not run SD-019 or write `/tmp`; this is diagnostic only.

The prompt-fix changes the meaning of SD-019. It no longer proves real `@markdown` SpawnAgent dispatch. It proves Codex can execute the markdown-agent contract inline in non-interactive mode. That is a valid workaround, but the scenario rubric must say that plainly.

Current-session caveat: the active tool schema I see can differ from the SD-019 transcript. The transcript is still decisive for that failed run: v0.130.0 rejected `markdown` as unavailable in that `codex exec` SpawnAgent path.

The remaining unknown is upstream Codex behavior: there may be an internal config path that maps project agents into SpawnAgent, but it is not exposed by the visible CLI help or this repo’s TOML wiring.
hook: Stop
hook: Stop Completed
tokens used
188,975
## Section A — Root Cause Verification

Your two-registry hypothesis is right in the practical sense: `.codex/config.toml` registers `agents.markdown`, but the `SpawnAgent` runtime path in SD-019 did not expose `markdown` as an available `agent_type`.

The transcript shows two separate failures:

1. `Full-history forked agents inherit...`
   This means Codex first tried to spawn with a full-history fork while also specifying `agent_type`, `model`, or `reasoning_effort`. That combination is invalid before `markdown` availability is even checked.

2. `agent type is currently not available`
   This is the real `markdown` blocker. After retrying, the router rejected the typed agent itself.

There is also a model-behavior issue: the prompt says “Use the `@markdown` agent”, so the AI reasonably reached for `SpawnAgent`. In `codex exec`, that is the wrong surface for this configured agent. The fallback generic sub-agent was not a resolver; it was an improvised workaround, and it then hit Gate 3.

A third interpretation: `.codex/config.toml` may be for interactive multi-agent/TUI context, while `codex exec`’s collab tool uses a separate tool-schema allowlist. That is slightly more precise than “config is read for CLI context”; the config is present, but not sufficient for this SpawnAgent route.

## Section B — Prompt-Fix Viability

Yes, the prompt-fix is viable if you make two changes explicit.

First, Codex can follow `.codex/agents/markdown.toml` inline. It is plain TOML with a `developer_instructions` block. A `gpt-5.5` Codex run can read it, read `sk-doc/SKILL.md`, read `assets/changelog_template.md`, and write the changelog directly.

Second, you must pre-answer Gate 3. The actual classifier triggers on file-write tokens like `write`, `create`, and `generate`; there is no `/tmp` exemption. So writing `/tmp/sk-test-dummy-CHANGELOG-cli-codex.md` still trips Gate 3 unless the prompt says the user’s Gate 3 answer is `D) Skip`.

Risk that Codex still reaches for `SpawnAgent`: low if the rewritten prompt avoids “Use the @markdown agent” as an imperative and explicitly says “do not call SpawnAgent/collab/Task.” The old prompt strongly pulled the model toward sub-agent dispatch. The new one should frame the task as “inline execution of the markdown contract.”

One more issue: `references/changelog_creation.md` does not exist. `sk-doc/SKILL.md` maps `CHANGELOG` to `assets/changelog_template.md`. If SD-019 keeps expecting that missing reference, the prompt-fix can still fail on resource evidence.

## Section C — Alternative Remediations

- CLI flag/env var: I checked `codex --help`, `codex exec --help`, and `codex features list`. No `--agent`, `codex agent`, or obvious config/env bridge exists. Upside would be real dispatch; cost is unknown and probably upstream-dependent.

- Register `markdown` in SpawnAgent allowlist: no local mechanism visible. The allowlist appears to come from runtime/tool metadata, not `.codex/config.toml`.

- Restructure `.codex/agents/markdown.toml`: unlikely to help. The TOML is complete, and the error is not a parse/config error. Other agents are registered the same way.

- `codex agent markdown ...`: no such subcommand in v0.130.0.

- `codex exec --profile markdown`: profiles are config profiles, not agent dispatch. You could make a profile inject instructions, but that is just the prompt-fix moved into config.

- Spawn a generic sub-agent with inline markdown instructions: possible, but worse. It adds another agent boundary, can hit Gate 3 again, and still does not prove `@markdown` dispatch.

## Section D — Recommended Decision

Pick **2. SWAP TO “prompt-fix workaround.”**

Do not claim the runtime `SpawnAgent` issue is fixed. Classify F-001 as “resolved via inline workaround” and keep a note that typed `markdown` dispatch remains unavailable under this `codex exec` path.

Exact Setup prompt I would use:

```text
Run this as an inline Codex execution of the @markdown contract. Do NOT call SpawnAgent, collab: SpawnAgent, Task, or any sub-agent. If you are about to dispatch, stop and perform the work inline instead.

This is the user’s consolidated Gate 3 answer for this run: D) Skip spec-folder creation. The only allowed write is /tmp/sk-test-dummy-CHANGELOG-cli-codex.md. specFolder=none. Do not ask interactive questions; stdin is closed.

Follow .codex/agents/markdown.toml developer_instructions inline for /create:changelog.

Resolved setup bindings:
command_name=/create:changelog
execution_mode=AUTONOMOUS
target=sk-test-dummy
output_path=/tmp/sk-test-dummy-CHANGELOG-cli-codex.md
template_path=.opencode/skills/sk-doc/assets/changelog_template.md
spec_folder=none

Before any file reads, print these binding lines:
BINDING: command=/create:changelog
BINDING: target=sk-test-dummy
BINDING: output=/tmp/sk-test-dummy-CHANGELOG-cli-codex.md
BINDING: template=.opencode/skills/sk-doc/assets/changelog_template.md
BINDING: mode=AUTONOMOUS
BINDING: specFolder=none

Then read:
1. .codex/agents/markdown.toml
2. .opencode/skills/sk-doc/SKILL.md
3. .opencode/skills/sk-doc/assets/changelog_template.md

Create a compact v0.1.0 changelog for stub skill sk-test-dummy at /tmp/sk-test-dummy-CHANGELOG-cli-codex.md. Do NOT install or create anything under .opencode/skills/.

Final report must include:
AGENT_RECEIVED=inline-codex-following-.codex/agents/markdown.toml
SPAWN_AGENT_USED=no
SK_DOC_RESOURCES_LOADED=<actual existing paths loaded>
CHANGELOG_SECTIONS=<sections produced>
STATUS=OK PATH=/tmp/sk-test-dummy-CHANGELOG-cli-codex.md
```

## Section E — Caveats And Uncertainty

I did not run SD-019 or write `/tmp`; this is diagnostic only.

The prompt-fix changes the meaning of SD-019. It no longer proves real `@markdown` SpawnAgent dispatch. It proves Codex can execute the markdown-agent contract inline in non-interactive mode. That is a valid workaround, but the scenario rubric must say that plainly.

Current-session caveat: the active tool schema I see can differ from the SD-019 transcript. The transcript is still decisive for that failed run: v0.130.0 rejected `markdown` as unavailable in that `codex exec` SpawnAgent path.

The remaining unknown is upstream Codex behavior: there may be an internal config path that maps project agents into SpawnAgent, but it is not exposed by the visible CLI help or this repo’s TOML wiring.

=== END: 2026-05-11T11:14:47+02:00 ===
=== EXIT CODE: 0 ===
=== WALL CLOCK: 229s ===
