interop

Load dh:dh-cli-usage before using <sam_cli/> or <dh_scripts/>.

/dh:interop — Superpowers Plan Interop Adapter

Routes a Superpowers plan file through the /work-backlog-item pipeline to produce a SAM task plan, then writes back-references into the original plan. Does not re-implement any pipeline logic — delegates entirely to /work-backlog-item.

The plan file path is provided as $ARGUMENTS.

Invocation: /dh:interop <path-to-plan-file>

---

Step 1 — Validate the argument

If $ARGUMENTS is empty, abort immediately:

ERROR: `/dh:interop` requires a path to a Superpowers plan file.
Usage: `/dh:interop docs/superpowers/plans/YYYY-MM-DD-slug.md`

Use the Read tool to open the file at the path given in $ARGUMENTS. If the file does not exist or cannot be read, abort:

ERROR: Cannot read plan file: {path}

Make no changes to the file or backlog before this check passes.

---

Step 2 — Extract fields from the plan file

Extract the following fields by exact pattern match against the raw file text. No inference.

flowchart TD
    Read([Raw file text in memory]) --> ExtractTitle[Extract Title<br>Pattern: first line matching ^# .+]
    ExtractTitle --> HasTitle{Title found?}
    HasTitle -->|No| AbortTitle["ABORT: Missing required field<br>ERROR: Plan file has no # heading — title is required"]
    HasTitle -->|Yes| ExtractGoal[Extract Goal<br>Pattern: line matching ^\*\*Goal:\*\*\s*.+]
    ExtractGoal --> HasGoal{Goal found?}
    HasGoal -->|No| AbortGoal["ABORT: Missing required field<br>ERROR: Plan file has no **Goal:** field — goal is required"]
    HasGoal -->|Yes| ExtractSpec[Extract Spec<br>Pattern: line matching ^\*\*Spec:\*\*\s*.+]
    ExtractSpec --> HasSpec{Spec found?}
    HasSpec -->|No| WarnSpec["Log warning: no **Spec:** field found — continuing"]
    HasSpec -->|Yes| SpecOK[Spec captured]
    WarnSpec --> ExtractBacklog
    SpecOK --> ExtractBacklog[Extract Backlog item<br>Pattern: line matching ^\*\*Backlog item:\*\*\s*#\d+]
    ExtractBacklog --> HasBacklog{Backlog item found?}
    HasBacklog -->|Yes — integer N captured| ExtractChunks
    HasBacklog -->|No| CreateBacklog[Step 3 — create backlog item]
    CreateBacklog --> ExtractChunks
    ExtractChunks[Extract Chunks<br>Pattern: all lines matching ^## Chunk \d+: .+] --> HasChunks{At least one chunk found?}
    HasChunks -->|No| WarnChunks["Log warning: no ## Chunk N: headings found<br>Chunk annotation step will be skipped"]
    HasChunks -->|Yes| ChunksOK[All chunk numbers and names captured]
    WarnChunks --> Proceed([Proceed to Step 3])
    ChunksOK --> Proceed