lda-wf/docs/historical/superpowers/plans/2026-06-22-agent-challenge-skill-bundle.md

Agent Challenge Skill Bundle Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Reorganize the workflow/CLI skills into a coherent, implementation-free instruction bundle that the challenge harness can copy reproducibly into trial workspaces.

Architecture: Keep skills/wf-cli focused on shell operation and skills/wf-workflow focused on domain lifecycle/authoring. An explicit YAML bundle manifest lists every copied file and destination; tests enforce existence, uniqueness, absence of implementation/test pointers, and current wf schema guidance.

Tech Stack: Markdown skills, YAML, Python 3.14, PyYAML, pytest.

---

File Structure

• Modify skills/wf-cli/SKILL.md: shell-first discovery and lifecycle commands.
• Modify skills/wf-workflow/SKILL.md: domain routing and progressive references.
• Modify skills/wf-workflow/references/system-model.md: concise object model.
• Modify skills/wf-workflow/references/workflow-lifecycle.md: end-to-end order.
• Modify skills/wf-workflow/references/capabilities-and-wrappers.md: capability contracts.
• Modify skills/wf-workflow/references/draft-workspaces.md: draft shape/edit path.
• Modify skills/wf-workflow/references/direct-plan-import.md: raw-plan shape.
• Modify skills/wf-workflow/references/troubleshooting.md: public-surface recovery.
• Create examples/agent_challenges/instruction_bundles/workflow_cli.yaml: explicit copy manifest.
• Create tests/examples/test_agent_challenge_skill_bundle.py: bundle and content contract.

Task 1: Define The Bundle Contract With Tests

Files:

• Create: tests/examples/test_agent_challenge_skill_bundle.py

• Create: examples/agent_challenges/instruction_bundles/workflow_cli.yaml

• Step 1: Write failing manifest tests

Create tests/examples/test_agent_challenge_skill_bundle.py:

from __future__ import annotations

from pathlib import Path

import yaml


ROOT = Path(__file__).resolve().parents[2]
MANIFEST = (
    ROOT
    / "examples"
    / "agent_challenges"
    / "instruction_bundles"
    / "workflow_cli.yaml"
)


def _bundle() -> dict[str, object]:
    loaded = yaml.safe_load(MANIFEST.read_text(encoding="utf-8"))
    assert isinstance(loaded, dict)
    return loaded


def _entries() -> list[dict[str, str]]:
    raw = _bundle()["files"]
    assert isinstance(raw, list)
    entries: list[dict[str, str]] = []
    for value in raw:
        assert isinstance(value, dict)
        assert isinstance(value.get("source"), str)
        assert isinstance(value.get("destination"), str)
        entries.append(value)
    return entries


def test_workflow_cli_bundle_has_unique_existing_files() -> None:
    bundle = _bundle()
    entries = _entries()

    assert bundle["version"] == 1
    assert bundle["id"] == "workflow-cli"
    assert len(entries) >= 8
    sources = [entry["source"] for entry in entries]
    destinations = [entry["destination"] for entry in entries]
    assert len(sources) == len(set(sources))
    assert len(destinations) == len(set(destinations))
    assert all((ROOT / source).is_file() for source in sources)
    assert all(not Path(destination).is_absolute() for destination in destinations)
    assert all(".." not in Path(destination).parts for destination in destinations)


def test_workflow_cli_bundle_uses_public_surfaces_not_implementation_files() -> None:
    contents = "\n".join(
        (ROOT / entry["source"]).read_text(encoding="utf-8")
        for entry in _entries()
    )

    assert "tests/" not in contents
    assert "src/" not in contents
    assert "test_" not in contents
    assert "wf schema" in contents
    assert "wf draft validate" in contents
    assert "wf deploy validate" in contents
    assert "wf run trace" in contents
    assert "empty command group" not in contents
    assert "no schema subcommands" not in contents


def test_bundle_destinations_form_two_skills() -> None:
    destinations = {entry["destination"] for entry in _entries()}

    assert "wf-cli/SKILL.md" in destinations
    assert "wf-workflow/SKILL.md" in destinations
    assert any(path.startswith("wf-workflow/references/") for path in destinations)

• Step 2: Run tests and verify the manifest is missing

uv run pytest tests/examples/test_agent_challenge_skill_bundle.py -q

Expected: fail because workflow_cli.yaml does not exist.

• Step 3: Add the explicit bundle manifest

Create examples/agent_challenges/instruction_bundles/workflow_cli.yaml:

version: 1
id: workflow-cli
description: Public workflow lifecycle and CLI instructions for agent trials.
files:
  - source: skills/wf-cli/SKILL.md
    destination: wf-cli/SKILL.md
  - source: skills/wf-workflow/SKILL.md
    destination: wf-workflow/SKILL.md
  - source: skills/wf-workflow/references/system-model.md
    destination: wf-workflow/references/system-model.md
  - source: skills/wf-workflow/references/workflow-lifecycle.md
    destination: wf-workflow/references/workflow-lifecycle.md
  - source: skills/wf-workflow/references/capabilities-and-wrappers.md
    destination: wf-workflow/references/capabilities-and-wrappers.md
  - source: skills/wf-workflow/references/draft-workspaces.md
    destination: wf-workflow/references/draft-workspaces.md
  - source: skills/wf-workflow/references/direct-plan-import.md
    destination: wf-workflow/references/direct-plan-import.md
  - source: skills/wf-workflow/references/troubleshooting.md
    destination: wf-workflow/references/troubleshooting.md

• Step 4: Run the existence/shape tests

uv run pytest tests/examples/test_agent_challenge_skill_bundle.py::test_workflow_cli_bundle_has_unique_existing_files tests/examples/test_agent_challenge_skill_bundle.py::test_bundle_destinations_form_two_skills -q

Expected: pass; public-surface content test may still fail until Tasks 2-3.

• Step 5: Commit the bundle contract

git add examples/agent_challenges/instruction_bundles/workflow_cli.yaml tests/examples/test_agent_challenge_skill_bundle.py
git commit -m "test: define agent challenge skill bundle"

Task 2: Make wf-cli A Public-Surface Skill

Files:

• Modify: skills/wf-cli/SKILL.md

• Test: tests/examples/test_agent_challenge_skill_bundle.py

• Step 1: Replace stale schema and discovery guidance

Keep the existing frontmatter and lifecycle command inventory. Replace the schema WIP rule with:

## Public Discovery Order

Use public CLI surfaces before broader documentation or implementation search:

1. `wf status`
2. `wf cap list --format ids`
3. `wf cap inspect <capability>`
4. `wf schema` to list workflow document/component shapes
5. `wf schema draft`, `wf schema raw`, or `wf schema <Component>`
6. `wf explain <diagnostic-code>` after validation failures

Use `wf schema <name> --verbose` only when the complete JSON Schema is required;
the default compact outline is preferred for agent context.

Add these rules under ## Rules:

- Prefer `wf schema` over searching tests or implementation code for draft/raw
  plan shape.
- Treat compact schema output as authoring guidance; use validation commands as
  the source of truth for a concrete document.
- If public commands and supplied skills are insufficient, report the exact
  blocker instead of guessing undocumented fields.

• Step 2: Remove challenge/evaluator-only policy from the product skill

Ensure skills/wf-cli/SKILL.md contains no instructions about challenge self-reports, contamination flags, model grading, prior trials, or test-file inspection. Those belong in the harness base/profile prompt.

• Step 3: Run the public-surface content test

uv run pytest tests/examples/test_agent_challenge_skill_bundle.py::test_workflow_cli_bundle_uses_public_surfaces_not_implementation_files -q

Expected: may still fail on workflow references; the wf-cli file itself no longer contains stale or implementation-oriented guidance.

• Step 4: Commit the CLI skill

git add skills/wf-cli/SKILL.md
git commit -m "docs: make wf cli skill schema-first"

Task 3: Reorganize Workflow References Around Public Models

Files:

• Modify: skills/wf-workflow/SKILL.md

• Modify: skills/wf-workflow/references/system-model.md

• Modify: skills/wf-workflow/references/workflow-lifecycle.md

• Modify: skills/wf-workflow/references/capabilities-and-wrappers.md

• Modify: skills/wf-workflow/references/draft-workspaces.md

• Modify: skills/wf-workflow/references/direct-plan-import.md

• Modify: skills/wf-workflow/references/troubleshooting.md

• Test: tests/examples/test_agent_challenge_skill_bundle.py

• Step 1: Add reference routing to the main workflow skill

Under ## References, make the routing explicit:

Read only the reference needed for the current task:

- Start with `system-model.md` when lifecycle vocabulary is unclear.
- Use `workflow-lifecycle.md` for operation order.
- Use `capabilities-and-wrappers.md` before selecting a source capability.
- Use `draft-workspaces.md` for iterative editing.
- Use `direct-plan-import.md` only when a complete raw plan is required.
- Use `troubleshooting.md` after a public validation/run failure.

Before authoring JSON, query the live public model with `wf schema`; the
references explain semantics while the command reflects the current shape.

• Step 2: Remove duplicate command inventories from the domain skill

Keep lifecycle semantics in wf-workflow/SKILL.md, but leave full shell syntax to wf-cli/SKILL.md and the focused references. Keep only one representative command per branch (draft versus raw) in the domain skill.

• Step 3: Add schema commands to draft and raw references

At the start of draft-workspaces.md, add:

Inspect the current draft model before writing or patching JSON:

    wf schema draft
    wf schema DraftUseStep

Use `--verbose` only when a complete JSON Schema is required.

At the start of direct-plan-import.md, add:

Inspect the current raw-plan and component models before writing JSON:

    wf schema raw
    wf schema NodeUse
    wf schema InputPathBinding
    wf schema OutputBinding

Use `--verbose` only when a complete JSON Schema is required.

• Step 4: Keep troubleshooting on public evidence

Ensure troubleshooting.md directs agents to:

wf status
wf cap inspect
wf draft validate
wf deploy validate
wf run inspect
wf run trace --from <n> --limit <n>
wf explain <code>

Remove directions to inspect tests/, src/, implementation examples, or historical plans.

• Step 5: Keep reference responsibilities distinct

Verify:

• system-model.md defines objects and boundaries, not command transcripts;

• workflow-lifecycle.md defines order and branch points;

• draft-workspaces.md owns draft shape/mapping semantics;

• direct-plan-import.md owns raw-plan shape/mapping semantics;

• capabilities-and-wrappers.md owns source/capability distinctions;

• troubleshooting.md owns recovery commands.

• Step 6: Run all bundle tests

uv run pytest tests/examples/test_agent_challenge_skill_bundle.py -q

Expected: all pass.

• Step 7: Commit workflow skill reorganization

git add skills/wf-workflow tests/examples/test_agent_challenge_skill_bundle.py
git commit -m "docs: reorganize workflow agent instructions"

Task 4: Verify Copyability And Record Completion

Files:

• Modify: tests/examples/test_agent_challenge_skill_bundle.py

• Modify: docs/current_roadmap.md

• Move after completion: docs/superpowers/plans/2026-06-22-agent-challenge-skill-bundle.md to docs/historical/superpowers/plans/2026-06-22-agent-challenge-skill-bundle.md

• Step 1: Add a copy smoke test

Append:

import shutil


def test_workflow_cli_bundle_copies_to_agent_skill_root(tmp_path: Path) -> None:
    destination_root = tmp_path / ".agent" / "skills"
    for entry in _entries():
        source = ROOT / entry["source"]
        destination = destination_root / entry["destination"]
        destination.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy2(source, destination)

    assert (destination_root / "wf-cli" / "SKILL.md").is_file()
    assert (destination_root / "wf-workflow" / "SKILL.md").is_file()
    assert (
        destination_root
        / "wf-workflow"
        / "references"
        / "direct-plan-import.md"
    ).is_file()

• Step 2: Run focused verification

uv run pytest tests/examples/test_agent_challenge_skill_bundle.py -q
uv run ruff check tests/examples/test_agent_challenge_skill_bundle.py
uv run ruff format --check tests/examples/test_agent_challenge_skill_bundle.py
uv run basedpyright --level error tests/examples/test_agent_challenge_skill_bundle.py
git diff --check

Expected: all tests/checks pass; only accepted Windows CRLF warnings may appear.

• Step 3: Update the roadmap

Add:

- Completed: workflow/CLI agent instructions now form an explicit copyable
  bundle for controlled challenge profiles, use `wf schema` for public shape
  discovery, and avoid implementation/test-file guidance.

• Step 4: Archive and commit the plan

New-Item -ItemType Directory -Force docs/historical/superpowers/plans | Out-Null
Move-Item docs/superpowers/plans/2026-06-22-agent-challenge-skill-bundle.md docs/historical/superpowers/plans/2026-06-22-agent-challenge-skill-bundle.md
git add docs/current_roadmap.md docs/superpowers/plans/2026-06-22-agent-challenge-skill-bundle.md docs/historical/superpowers/plans/2026-06-22-agent-challenge-skill-bundle.md tests/examples/test_agent_challenge_skill_bundle.py
git commit -m "docs: record agent challenge skill bundle"