drt-method 1.0.0

package/src/core-skills/drt-party-mode/scripts/resolve_party.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve the party-mode roster, lazily.
+
+Merges the installed DRT agents with the user's custom `party_members`
+into one collective, then projects only what the moment needs:
+
+  * default (no flag) — the active roster to load on entry: the
+    `default_party` group if one is configured, else the whole collective.
+    Other groups come back as names only, so nothing you aren't using is
+    loaded into the party.
+  * --list-groups — just id + name + size for every configured group. The
+    cheap menu for "which room?", with no member detail.
+  * --party <id> — full member detail for one chosen group, on demand
+    (e.g. when the user switches rooms). Unknown id returns the available
+    names instead of an error wall.
+
+The merge is deterministic (a keyed union; a custom member whose code
+matches an installed agent overrides it), so the orchestrator consumes a
+resolved roster instead of re-deriving it every session.
+
+Stdlib only (Python 3.11+ for tomllib). Shells out to the project's
+resolve_config.py and resolve_customization.py; falls back to reading
+customize.toml directly if the customization resolver is unavailable.
+
+  resolve_party.py --project-root P --skill S
+  resolve_party.py --project-root P --skill S --list-groups
+  resolve_party.py --project-root P --skill S --party writers-room
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    import tomllib
+except ImportError:  # pragma: no cover - guarded for <3.11
+    sys.stderr.write("error: Python 3.11+ is required (stdlib `tomllib`).\n")
+    sys.exit(3)
+
+
+def _run_json(cmd):
+    """Run a resolver script and parse its JSON stdout. None on any failure."""
+    try:
+        out = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if out.returncode != 0 or not out.stdout.strip():
+        return None
+    try:
+        return json.loads(out.stdout)
+    except json.JSONDecodeError:
+        return None
+
+
+def load_agents(project_root: Path):
+    """Installed agents as {code: entry}. Empty dict (with a flag) on failure."""
+    script = project_root / "_drt" / "scripts" / "resolve-config.js"
+    data = _run_json(["node", str(script), "--project-root", str(project_root), "--key", "agents"])
+    if data is None:
+        return {}, False
+    return data.get("agents", {}) or {}, True
+
+
+def load_workflow(project_root: Path, skill_root: Path):
+    """Merged [workflow] table. Falls back to the skill's base customize.toml."""
+    script = project_root / "_drt" / "scripts" / "resolve-customization.js"
+    data = _run_json(["node", str(script), "--skill", str(skill_root), "--key", "workflow"])
+    if data is not None and "workflow" in data:
+        return data["workflow"]
+    # Fallback: read the skill's base customize.toml directly (no override merge).
+    toml_path = skill_root / "customize.toml"
+    if toml_path.exists():
+        try:
+            with toml_path.open("rb") as f:
+                return tomllib.load(f).get("workflow", {})
+        except (OSError, tomllib.TOMLDecodeError):
+            pass
+    return {}
+
+
+def _alias(code: str) -> str:
+    """Short alias for an installed agent code: drt-agent-analyst -> analyst."""
+    for prefix in ("drt-agent-", "drt-"):
+        if code.startswith(prefix):
+            return code[len(prefix):]
+    return code
+
+
+def build_collective(agents: dict, party_members: list):
+    """One pool keyed by code. Custom members override matching installed agents.
+
+    Returns (collective, index, installed_codes):
+      * collective — every member (installed + custom), the pool groups draw
+        from and the orchestrator can summon by name.
+      * index — maps every resolvable token (code, prefix-stripped alias,
+        lower-cased name) to a canonical code.
+      * installed_codes — the codes occupying an installed-agent slot, in
+        order. This is the DEFAULT room: installed agents (with any custom
+        override applied in place), and NOT the pure-custom additions. So
+        shipping or defining custom members grows the pool without crowding
+        the default party.
+    """
+    collective = {}
+    index = {}
+    installed_codes = []
+
+    def register(code, entry):
+        collective[code] = entry
+        index[code] = code
+        index[code.lower()] = code
+        index[_alias(code).lower()] = code
+        name = entry.get("name")
+        if name:
+            index[name.lower()] = code
+
+    for code, info in agents.items():
+        register(code, {
+            "code": code,
+            "name": info.get("name", code),
+            "icon": info.get("icon", ""),
+            "title": info.get("title", ""),
+            "description": info.get("description", ""),
+            "module": info.get("module", ""),
+            "team": info.get("team", ""),
+            "source": "installed",
+        })
+        installed_codes.append(code)
+
+    for m in party_members or []:
+        code = m.get("code")
+        if not code:
+            continue
+        # A custom member overrides an installed agent it matches by code/alias/name.
+        canonical = index.get(code) or index.get(code.lower()) or code
+        entry = {"code": canonical, "source": "custom"}
+        for field in ("name", "icon", "title", "persona", "capabilities", "model"):
+            if m.get(field) is not None:
+                entry[field] = m[field]
+        entry.setdefault("name", canonical)
+        register(canonical, entry)
+        # An override keeps the installed slot; a brand-new custom does not join it.
+
+    return collective, index, installed_codes
+
+
+def resolve_members(member_tokens, collective, index):
+    """(resolved entries in listed order, unresolved tokens)."""
+    resolved, unresolved = [], []
+    for token in member_tokens or []:
+        code = index.get(token) or index.get(str(token).lower())
+        if code and code in collective:
+            resolved.append(collective[code])
+        else:
+            unresolved.append(token)
+    return resolved, unresolved
+
+
+def group_menu(groups):
+    """Names only — the cheap menu. Open-cast groups (no roster) are flagged."""
+    out = []
+    for g in groups or []:
+        if not isinstance(g, dict) or not g.get("id"):
+            continue
+        members = g.get("members", []) or []
+        entry = {"id": g["id"], "name": g.get("name", g["id"]),
+                 "member_count": len(members)}
+        if not members:
+            entry["open_cast"] = True
+        out.append(entry)
+    return out
+
+
+def find_group(groups, group_id):
+    for g in groups or []:
+        if isinstance(g, dict) and g.get("id") == group_id:
+            return g
+    return None
+
+
+def group_detail(g, collective, index):
+    """Full detail for one group: resolved members + the optional scene.
+
+    `scene` is a freeform line the orchestrator plays — setting, what's
+    happening, room dynamics, in-the-moment character notes. Surfaced only
+    here (when a group is the active/chosen roster), never in the menu.
+
+    `members` is optional. With none, the group is open-cast: `open_cast`
+    is flagged and the scene describes the pool the orchestrator casts from
+    on the fly (e.g. "figures from the Star Wars Rebels universe"). A few
+    listed members anchor the room; the scene can still invite more.
+    """
+    raw_members = g.get("members", []) or []
+    members, unresolved = resolve_members(raw_members, collective, index)
+    detail = {"active": g["id"], "name": g.get("name", g["id"]),
+              "members": members, "unresolved": unresolved,
+              "memory_enabled": bool(g.get("memory", False))}
+    if g.get("scene"):
+        detail["scene"] = g["scene"]
+    if not raw_members:
+        detail["open_cast"] = True
+    return detail
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Resolve the party-mode roster, lazily.")
+    ap.add_argument("--project-root", required=True)
+    ap.add_argument("--skill", required=True, help="Path to the drt-party-mode skill dir")
+    ap.add_argument("--party", help="Resolve full detail for this group id")
+    ap.add_argument("--list-groups", action="store_true", help="Group names only")
+    args = ap.parse_args()
+
+    project_root = Path(args.project_root).resolve()
+    skill_root = Path(args.skill).resolve()
+
+    workflow = load_workflow(project_root, skill_root)
+    groups = workflow.get("party_groups", []) or []
+    default_party = workflow.get("default_party", "") or ""
+    party_mode = workflow.get("party_mode", "session") or "session"
+    # The global party_memory flag governs only the DEFAULT installed-agent room;
+    # a named group carries its own `memory` flag (resolved in group_detail).
+    party_memory = bool(workflow.get("party_memory", True))
+
+    # Group menu never needs the (more expensive) installed-agent resolve.
+    if args.list_groups:
+        _emit({
+            "party_mode": party_mode,
+            "default_party": default_party,
+            "groups": group_menu(groups),
+        })
+        return
+
+    agents, agents_ok = load_agents(project_root)
+    collective, index, installed_codes = build_collective(agents, workflow.get("party_members", []))
+
+    if args.party:
+        g = find_group(groups, args.party)
+        if g is None:
+            _emit({"error": "unknown_group", "requested": args.party,
+                   "available": group_menu(groups)})
+            return
+        _emit({**group_detail(g, collective, index), "party_mode": party_mode})
+        return
+
+    # Default: the active roster to load on entry.
+    result = {"party_mode": party_mode, "groups": group_menu(groups),
+              "installed_agents_resolved": agents_ok}
+    g = find_group(groups, default_party) if default_party else None
+    if g is not None:
+        result.update(group_detail(g, collective, index))
+    else:
+        # No default group: the installed agents (custom additions stay in the
+        # pool but don't crowd the default room), exactly like a plain install.
+        result.update({"active": "installed",
+                       "members": [collective[c] for c in installed_codes],
+                       "memory_enabled": party_memory})
+    _emit(result)
+
+
+def _emit(obj):
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        reconfigure(encoding="utf-8")
+    sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
+
+
+if __name__ == "__main__":
+    main()

package/src/core-skills/drt-review-adversarial-general/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: drt-review-adversarial-general
+description: 'Perform a Cynical Review and produce a findings report. Use when the user requests a critical review of something'
+---
+
+# Adversarial Review (General)
+
+**Goal:** Cynically review content and produce findings.
+
+**Your Role:** You are a cynical, jaded reviewer with zero patience for sloppy work. The content was submitted by a clueless weasel and you expect to find problems. Be skeptical of everything. Look for what's missing, not just what's wrong. Use a precise, professional tone — no profanity or personal attacks.
+
+**Inputs:**
+- **content** — Content to review: diff, spec, story, doc, or any artifact
+- **also_consider** (optional) — Areas to keep in mind during review alongside normal adversarial analysis
+
+
+## EXECUTION
+
+### Step 1: Receive Content
+
+- Load the content to review from provided input or context
+- If content to review is empty, ask for clarification and abort
+- Identify content type (diff, branch, uncommitted changes, document, etc.)
+
+### Step 2: Adversarial Analysis
+
+Review with extreme skepticism — assume problems exist. Find at least ten issues to fix or improve in the provided content.
+
+### Step 3: Present Findings
+
+Output findings as a Markdown list: descriptions only, no severity, priority, or ranking.
+
+
+## HALT CONDITIONS
+
+- HALT if zero findings — this is suspicious, re-analyze or ask for guidance
+- HALT if content is empty or unreadable

package/src/core-skills/drt-review-edge-case-hunter/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: drt-review-edge-case-hunter
+description: 'Walk every branching path and boundary condition in content, report only unhandled edge cases. Orthogonal to adversarial review - method-driven not attitude-driven. Use when you need exhaustive edge-case analysis of code, specs, or diffs.'
+---
+
+# Edge Case Hunter Review
+
+**Goal:** You are a pure path tracer. Never comment on whether code is good or bad; only list missing handling.
+When a diff is provided, scan only the diff hunks and list boundaries that are directly reachable from the changed lines and lack an explicit guard in the diff.
+When no diff is provided (full file or function), treat the entire provided content as the scope.
+Ignore the rest of the codebase unless the provided content explicitly references external functions.
+A brief secondary deletion check runs as Step 4 when the diff removes code.
+
+**Inputs:**
+- **content** — Content to review: diff, full file, or function
+- **also_consider** (optional) — Areas to keep in mind during review alongside normal edge-case analysis
+
+**MANDATORY: Execute steps in the Execution section IN EXACT ORDER. DO NOT skip steps or change the sequence. When a halt condition triggers, follow its specific instruction exactly. Each action within a step is a REQUIRED action to complete that step.**
+
+**Your method is exhaustive path enumeration — mechanically walk every branch, not hunt by intuition. Report ONLY paths and conditions that lack handling — discard handled ones silently. Do NOT editorialize or add filler. Do not assign severity labels, rankings, or priority levels.**
+
+
+## EXECUTION
+
+### Step 1: Receive Content
+
+- Load the content to review strictly from provided input
+- If content is empty, or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
+- Identify content type (diff, full file, or function) to determine scope rules
+
+### Step 2: Exhaustive Path Analysis
+
+**Walk every branching path and boundary condition within scope — report only unhandled ones.**
+
+- If `also_consider` input was provided, incorporate those areas into the analysis
+- Walk all branching paths: control flow (conditionals, loops, error handlers, early returns) and domain boundaries (where values, states, or conditions transition). Derive the relevant edge classes from the content itself — don't rely on a fixed checklist. Examples: missing else/default, unguarded inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
+- Consider implicit branches: the diff special-cases or changes the handling of one or more members of a fixed set of values — enums, status codes, sentinels, type tags, flags, value ranges. The rest of the set is implicit branches (e.g. the diff changes the `RED` and `YELLOW` cases of a `RED`/`YELLOW`/`GREEN` enum; `GREEN` is the implicit branch)
+- For each path: determine whether the content handles it
+- Collect only the unhandled paths as findings — discard handled ones silently
+
+### Step 3: Validate Completeness
+
+- Revisit every edge class from Step 2 — e.g., missing else/default, null/empty inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
+- Add any newly found unhandled paths to findings; discard confirmed-handled ones
+
+### Step 4: Deletion Check
+
+If the diff removed or replaced meaningful code (ignore pure renames and whitespace): load `references/deletion-check.md` and follow it.
+
+### Step 5: Present Findings
+
+Output all findings as a single JSON array following the Output Format specification exactly.
+
+
+## OUTPUT FORMAT
+
+Return ONLY a valid JSON array of objects. Each edge-case finding contains exactly these four fields:
+
+```json
+[{
+  "location": "file:start-end (or file:line when single line, or file:hunk when exact line unavailable)",
+  "trigger_condition": "one-line description (max 15 words)",
+  "guard_snippet": "minimal code sketch that closes the gap (single-line escaped string, no raw newlines or unescaped quotes)",
+  "potential_consequence": "what could actually go wrong (max 15 words)"
+}]
+```
+
+No extra text, no explanations, no markdown wrapping. An empty array `[]` is valid when nothing is found. Deletion findings from Step 4, if any, go in the same array with the extra fields defined in `references/deletion-check.md`.
+
+
+## HALT CONDITIONS
+
+- If content is empty or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop

package/src/core-skills/drt-review-edge-case-hunter/references/deletion-check.md

@@ -0,0 +1,14 @@
+# Deletion Check
+
+Secondary pass for the Edge Case Hunter — runs only when the diff removed meaningful code. Subordinate to the edge-case pass; findings are usually few or none.
+
+For each chunk of removed or replaced code (ignore pure renames and whitespace), ask: did it carry behavior or a contract that the change neither re-established nor intentionally retired? Add a finding for any resulting regression, orphaned reference, or newly-dead code. Skip anything already covered by your edge-case findings.
+
+Append each finding to the same JSON array as the edge-case findings, with the four standard fields plus:
+
+- `kind`: `"deletion"`
+- `confidence`: `"high"`, `"medium"`, or `"low"` — these are inferences; rate them
+
+For a deletion finding the standard fields read as: `location` = the removed item; `trigger_condition` = the behavior or contract it enforced; `guard_snippet` = where or how to re-establish it; `potential_consequence` = the regression or orphan.
+
+Add nothing if nothing qualifies.

package/src/core-skills/drt-review-verification-gap/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: drt-review-verification-gap
+description: 'Review a code change for changed behavior that could regress without reliable verification catching it. Use when checking whether a change is adequately verified.'
+---
+
+# Verification Gap Review
+
+**Goal:** Find changed behavior that could break without reliable verification catching it. Ask one question — "if the behavior this change is supposed to produce broke where it's actually used, would verification fail?" Do not hunt for correctness bugs, but report genuine problems you notice while tracing verification.
+
+The main verification gap shapes are:
+
+1. **Regression gap:** the changed code regresses where it's used, and no test covering that use would fail.
+2. **Missing-adoption gap:** a place that should now use the new behavior doesn't; it handles the same case its own way, or not at all, and no test would flag the omission.
+3. **Broken-verification gap:** a test appears to cover the changed behavior, but would not actually protect it because it is skipped, flaky, not run in the normal verification path, or too weak to observe the regression.
+
+## Evidence Rules
+
+- Read a test before claiming what it covers, runs, asserts, or misses.
+- Before claiming no test exists, search the whole repo by the symbol under test and by import references; expected file locations are not enough.
+- Never assert what you did not verify. If a finding cannot be grounded, drop it.
+- In a finding, say what you actually checked — "none of the tests I read cover this" — and show how far you looked. Say a test doesn't exist anywhere only when the symbol/import-reference search actually shows that.
+- Do not assign severity, confidence, priority, or ranking.
+
+## Review Sequence
+
+### Step 1: Screen for behavioral change
+
+If the change is non-behavioral, stop here and output the clean result (see Output Format). Call it non-behavioral only when the changed code does not alter return values, thrown errors, caller-visible side effects, or observable state (including iteration order and emitted messages). After the changed code meets that test, stop; do not inspect callers or tests for extra confirmation.
+
+Common non-behavioral examples: formatting, comments, whitespace; pure renames; trivial getters/setters and pass-throughs; type-only or compiler-enforced changes with no runtime effect; etc.
+
+### Step 2: Find the behavior that changed
+
+Identify what behavior changed compared to the previous version: output, side effect, branch, error path, schema/event shape, config default, validation/authorization rule, external contract, etc. If the change affects more than one behavior, handle each separately.
+
+Treat broad-impact changes as behavioral even when no single changed line looks important: dependency, toolchain, build/config, data-file, etc.
+
+### Step 3: Trace where that behavior is used
+
+Trace the changed behavior to the places that observe it. Start with direct callers and registered entry points (routes, commands, DI), contract consumers (schemas, events, APIs, database readers), and reverse-dependency info if already available.
+
+Follow a path only while the changed behavior is reachable and unverified. Stop when a test at that boundary would fail, the consumer does not observe the changed behavior, or the next hop is guesswork (dynamic dispatch, reflection, outside-repo consumers, etc.). Prefer the nearest observable boundary, often one to three hops away, especially across contract, integration, or service edges. If there are more than five similar consumers, group obvious repeats and check representative paths; expand only when a consumer observes the behavior differently.
+
+### Step 4: Qualify the consumer, then check its test
+
+For each consumer, name the smallest realistic regression this consumer would observe: invert the branch, drop the default, omit the field, return the old error code, skip the integration call, etc. This is the Demonstration. If no such regression exists, drop the path; untested downstream code is not a finding.
+
+A `Missing-adoption gap` qualifies not by the adoption failure alone but by a supersession signal: the change gives clear evidence the new behavior is meant to replace the local one — PR intent, naming or docs, a replaced sibling site, deleted duplicate logic, or a test defining the new rule — and the local site shares the same observable contract. Without a supersession signal and a shared observable contract, it is a refactor suggestion, not a verification-gap finding. Once both hold, check whether any test for that site would flag the non-adoption; missing coverage of the non-adoption is the gap itself, not a disqualifier.
+
+Find and read the relevant test. Ask whether the Demonstration would make an assertion fail.
+
+- If yes, the behavior is verified. No finding.
+- For a regression-style Demonstration: if no test runs the path, the test is skipped/flaky/not run normally, or the test runs the code without checking the changed result, report a `Regression gap` or `Broken-verification gap`.
+- For a qualifying Missing-adoption case: if none of the site tests you found assert it adopts the new behavior, report a `Missing-adoption gap`.
+
+A test counts only if it runs normally and an assertion observes the changed output, branch, or contract. These do not count: no execution; success/no-throw/snapshot-only checks; mock/log-call checks; human-only checks; tests that mock away the integration; e2e tests that pass through without checking the changed output; stale assertions or fixtures.
+
+Common patterns:
+
+- **Caller-path gap** — helper test covers the branch, but caller values skip it.
+- **Contract drift** — payload/schema/event changes must be verified at the consumer.
+- **Migration compatibility** — tests only create new-format rows or fresh schemas.
+- **Phantom exception** — handled partial-failure path has no test.
+- **Missing-adoption gap** — sibling site should use the new rule/helper and does not.
+- **Removed verification** — deleted test or weakened assertion leaves behavior unpinned.
+
+### Step 5: Confirm each finding is real
+
+Before writing a finding, re-open the specific tests or search results the finding relies on. Verify the Demonstration would not make any test you checked fail, or that the absence claim is backed by the symbol/import-reference search. Do not claim more than you verified; drop any finding you cannot ground.
+
+Do not report: compiler/type-checker-enforced cases; behavior already verified by an integration, contract, or e2e test; implementation-detail or mock-only tests; low coverage or a missing test file by itself; legacy untested code the change did not affect.
+
+Report genuine problems you noticed while tracing verification, even if they are not verification gaps. Put them under `Other findings` in the output. This permits reporting what you already reached, not extra hunting.
+
+## OUTPUT FORMAT
+
+Emit each verification-gap finding as one block. No general advice, no severity or confidence.
+
+```markdown
+### <one-line title naming the gap>
+
+- **Changed surface:** the exact behavior or contract that changed — `file:line`.
+- **Impacted consumer or site:** named concretely with `file:line` (e.g. "the `createInvoice` mutation used by the billing dashboard at `billing/dashboard.ts:88`," not "callers of this function").
+- **Existing test evidence:**
+  - `Regression gap`: what the relevant test actually asserts, with `file:line`; or, if none, the symbol/import-reference searches run and their result.
+  - `Missing-adoption gap`: tests for the impacted site, and whether any assert it adopts the new behavior.
+  - `Broken-verification gap`: the apparent test or verification path, and why it does not count.
+- **Missing verification:** the precise assertion or check that's absent.
+- **Demonstration:**
+  - `Regression gap` / `Broken-verification gap`: the concrete regression that would ship undetected, and why the tests you checked would not fail.
+  - `Missing-adoption gap`: the case the site mishandles by not adopting the new behavior, and that none of the tests you read assert adoption.
+- **Consequence:** the concrete thing that ships wrong — a regression the checked evidence would not catch, or a site that should use the new behavior and doesn't.
+- **Suggested test shape:** (optional) the kind of test that would close the gap, fit to the repo's own way of verifying — don't impose a generic test pyramid.
+```
+
+If you noticed genuine non-gap problems while tracing verification, append:
+
+```markdown
+## Other findings
+
+- <description only; no severity, confidence, priority, or ranking>
+```
+
+When you find no verification gaps and no other findings, output exactly this single line, not an empty response:
+
+`No verification gaps found.`

package/src/core-skills/drt-shard-doc/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: drt-shard-doc
+description: 'Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document'
+---
+
+# Shard Document
+
+**Goal:** Split large markdown documents into smaller, organized files based on level 2 sections using `npx @kayvan/markdown-tree-parser`.
+
+## CRITICAL RULES
+
+- MANDATORY: Execute ALL steps in the EXECUTION section IN EXACT ORDER
+- DO NOT skip steps or change the sequence
+- HALT immediately when halt-conditions are met
+- Each action within a step is a REQUIRED action to complete that step
+
+## EXECUTION
+
+### Step 1: Get Source Document
+
+- Ask user for the source document path if not provided already
+- Verify file exists and is accessible
+- Verify file is markdown format (.md extension)
+- If file not found or not markdown: HALT with error message
+
+### Step 2: Get Destination Folder
+
+- Determine default destination: same location as source file, folder named after source file without .md extension
+  - Example: `/path/to/architecture.md` --> `/path/to/architecture/`
+- Ask user for the destination folder path (`[y]` to confirm use of default: `[suggested-path]`, else enter a new path)
+- If user accepts default: use the suggested destination path
+- If user provides custom path: use the custom destination path
+- Verify destination folder exists or can be created
+- Check write permissions for destination
+- If permission denied: HALT with error message
+
+### Step 3: Execute Sharding
+
+- Inform user that sharding is beginning
+- Execute command: `npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]`
+- Capture command output and any errors
+- If command fails: HALT and display error to user
+
+### Step 4: Verify Output
+
+- Check that destination folder contains sharded files
+- Verify index.md was created in destination folder
+- Count the number of files created
+- If no files created: HALT with error message
+
+### Step 5: Report Completion
+
+- Display completion report to user including:
+  - Source document path and name
+  - Destination folder path
+  - Number of section files created
+  - Confirmation that index.md was created
+  - Any tool output or warnings
+- Inform user that sharding completed successfully
+
+### Step 6: Handle Original Document
+
+> **Critical:** Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion.
+
+Present user with options for the original document:
+
+> What would you like to do with the original document `[source-document-name]`?
+>
+> Options:
+> - `[d]` Delete - Remove the original (recommended - shards can always be recombined)
+> - `[m]` Move to archive - Move original to a backup/archive location
+> - `[k]` Keep - Leave original in place (NOT recommended - defeats sharding purpose)
+>
+> Your choice (d/m/k):
+
+#### If user selects `d` (delete)
+
+- Delete the original source document file
+- Confirm deletion to user: "Original document deleted: [source-document-path]"
+- Note: The document can be reconstructed from shards by concatenating all section files in order
+
+#### If user selects `m` (move)
+
+- Determine default archive location: same directory as source, in an `archive` subfolder
+  - Example: `/path/to/architecture.md` --> `/path/to/archive/architecture.md`
+- Ask: Archive location (`[y]` to use default: `[default-archive-path]`, or provide custom path)
+- If user accepts default: use default archive path
+- If user provides custom path: use custom archive path
+- Create archive directory if it does not exist
+- Move original document to archive location
+- Confirm move to user: "Original document moved to: [archive-path]"
+
+#### If user selects `k` (keep)
+
+- Display warning to user:
+  - Keeping both original and sharded versions is NOT recommended
+  - The discover_inputs protocol may load the wrong version
+  - Updates to one will not reflect in the other
+  - Duplicate content taking up space
+  - Consider deleting or archiving the original document
+- Confirm user choice: "Original document kept at: [source-document-path]"
+
+## HALT CONDITIONS
+
+- HALT if npx command fails or produces no output files