drt-method 1.0.0

package/src/drt-skills/4-implementation/drt-quick-dev/step-02-plan.md

@@ -0,0 +1,47 @@
+# Step 2: Plan
+
+## RULES
+
+- **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
+- No intermediate approvals.
+
+## INSTRUCTIONS
+
+1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `<frozen-after-approval>...</frozen-after-approval>` block as `preserved_intent`. Otherwise `preserved_intent` is empty.
+2. Investigate codebase. _Isolate deep exploration in subagents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
+3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation, resolving the template's `date` field to the current system date. If `preserved_intent` is non-empty, replace the `<frozen-after-approval>` block in the spec you just filled out with `preserved_intent`, before writing. Write the result to `{spec_file}`.
+4. Self-review against READY FOR DEVELOPMENT standard.
+5. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
+6. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
+   - Show user the token count.
+   - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks`
+   - On **S**: Propose the split — name each secondary goal. For each deferred goal, append one new entry to `{{.deferred_work_file}}` using this format. Do not modify existing entries or look for duplicates. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
+     ```markdown
+     - source_spec: `{spec_file}`
+       summary: <one sentence naming the deferred goal>
+       evidence: <why this was split from the current spec>
+     ```
+   - On **K**: Continue to checkpoint with full spec.
+
+### CHECKPOINT 1
+
+Present summary. Display the spec file path as a CWD-relative path (no leading `/`) so it is clickable in the terminal. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem.
+
+After presenting the summary, display this note:
+
+---
+
+Before approving, you can open the spec file in an editor or ask me questions and tell me what to change. You can also use `drt-advanced-elicitation`, `drt-party-mode`, or `drt-code-review` skills, ideally in another session to avoid context bloat.
+
+---
+
+HALT and ask human: `[A] Approve` | `[E] Edit`
+
+- **A**: Re-read `{spec_file}` from disk.
+  - **If the file is missing:** HALT. Tell the user the spec file is gone and STOP — do not write anything to `{spec_file}`, do not set status, do not proceed to Step 3. Nothing below this point runs.
+  - **If the file exists:** Compare the content to what you wrote. If it has changed since you wrote it, acknowledge the external edits — show a brief summary of what changed — and proceed with the updated version. Then set status `ready-for-dev` in `{spec_file}`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. → Step 3.
+- **E**: Apply changes, then return to CHECKPOINT 1.
+
+## NEXT
+
+Read fully and follow `./step-03-implement.md`

package/src/drt-skills/4-implementation/drt-quick-dev/step-03-implement.md

@@ -0,0 +1,45 @@
+---
+---
+
+# Step 3: Implement
+
+## RULES
+
+- **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
+- No push. No remote ops.
+- Sequential execution only.
+- Content inside `<frozen-after-approval>` in `{spec_file}` is read-only. Do not modify.
+
+## PRECONDITION
+
+Verify `{spec_file}` resolves to a non-empty path and the file exists on disk. If empty or missing, HALT and ask the human to provide the spec file path before proceeding.
+
+## INSTRUCTIONS
+
+### Baseline
+
+Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter before making any changes.
+
+### Implement
+
+Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation.
+
+Follow `./sync-sprint-status.md` with `target_status` = `in-progress`.
+
+If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a subagent, include them in the subagent prompt so it has access to the referenced context.
+
+Hand `{spec_file}` to a subagent/task and let it implement. If no subagents are available, implement directly.
+
+**Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case.
+
+### Tasks & Acceptance Verification
+
+Before leaving this step, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete and every acceptance criterion is satisfied. Mark each finished task `[x]`. If any task is not done or any acceptance criterion is not satisfied, finish the missing work before proceeding.
+
+### Matrix Test Audit
+
+If `{spec_file}`'s `<frozen-after-approval>` block contains an I/O & Edge-Case Matrix, verify every matrix row is covered by at least one test that verifies its expected behavior, and that each covering test ran and passed in the verification output. A covering test that exists but did not run — unregistered, filtered out, skipped, or disabled — counts as missing. If a test disagrees with the matrix, never edit the expectation to match the code: fix the code, or if the matrix row itself is ambiguous, HALT and ask the human. Fix any other audit failure before proceeding.
+
+## NEXT
+
+Read fully and follow `./step-04-review.md`

package/src/drt-skills/4-implementation/drt-quick-dev/step-04-review.md

@@ -0,0 +1,55 @@
+# Step 4: Review
+
+## RULES
+
+- **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
+- All review subagents must run at the same model capability as the current session.
+- Run subagents synchronously: launch them together, then wait for all results before continuing.
+
+## INSTRUCTIONS
+
+Change `{spec_file}` status to `in-review` in the frontmatter before continuing.
+
+### Construct Diff
+
+Read `{baseline_commit}` from `{spec_file}` frontmatter. If `{baseline_commit}` is missing or `NO_VCS`, use best effort to determine what changed. Otherwise, construct `{diff_output}` covering all changes — tracked and untracked — since `{baseline_commit}`.
+
+Do NOT `git add` anything — this is read-only inspection.
+
+### Review
+
+Execute these review layers in parallel wherever their execution methods allow: substitute the runtime placeholders (e.g. `{diff_output}`) into each layer's instruction, then follow it verbatim.
+
+{workflow.review_layers}
+
+If a layer's instruction requires subagents and none are available, generate one review prompt file per such layer in `{{.implementation_artifacts}}` and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
+
+### Classify
+
+1. Deduplicate only findings with the same claim and same required action. Then evaluate each remaining finding independently. Do not reject a finding because a related finding was rejected.
+2. Assign severity to each finding by consequence for the artifact's main consumer (software user, document reader, etc).
+   Disregard any severity assigned by a reviewing subagent. Review subagents operate under by-design information asymmetry and do not have enough context to set final severity for this workflow.
+   - `low`: none or cosmetic
+   - `medium`: tolerable
+   - `high`: intolerable
+3. Route each finding into exactly one triage category. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**.
+   - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading.
+   - **bad_spec** — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code.
+   - **patch** — caused by the change; trivially fixable without human input. Just part of the diff.
+   - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention.
+   - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real.
+4. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Before each loopback, read `{spec_file}` frontmatter `review_loop_iteration` (missing means `0`), increment it by 1, and write it back. If it exceeds 5, HALT and escalate to the human.
+   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./step-02-plan.md` to re-run steps 2–4.
+   - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again.
+   - **patch** — Auto-fix. These are the only findings that survive loopbacks.
+   - **defer** — Append one new entry to `{{.deferred_work_file}}` using this format. Do not modify existing entries or look for duplicates.
+     ```markdown
+     - source_spec: `{spec_file}`
+       summary: <one sentence>
+       evidence: <why this is real>
+     ```
+   - **reject** — Drop silently.
+
+## NEXT
+
+Read fully and follow `./step-05-present.md`

package/src/drt-skills/4-implementation/drt-quick-dev/step-05-present.md

@@ -0,0 +1,78 @@
+---
+---
+
+# Step 5: Present
+
+## RULES
+
+- **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
+- NEVER auto-push.
+
+## INSTRUCTIONS
+
+### Generate Suggested Review Order
+
+Read `{baseline_commit}` from `{spec_file}` frontmatter and construct the diff of all changes since that commit.
+
+Append the review order as a `## Suggested Review Order` section to `{spec_file}` **after the last existing section**. Do not modify the Code Map.
+
+Build the trail as an ordered sequence of **stops** — clickable `path:line` references with brief framing — optimized for a human reviewer reading top-down to understand the change:
+
+1. **Order by concern, not by file.** Group stops by the conceptual concern they address (e.g., "validation logic", "schema change", "UI binding"). A single file may appear under multiple concerns.
+2. **Lead with the entry point** — the single highest-leverage file:line a reviewer should look at first to grasp the design intent.
+3. **Inside each concern**, order stops from most important / architecturally interesting to supporting. Lightly bias toward higher-risk or boundary-crossing stops.
+4. **End with peripherals** — tests, config, types, and other supporting changes come last.
+5. **Every code reference is a clickable spec-file-relative link.** Compute each link target as a relative path from `{spec_file}`'s directory to the changed file. Format each stop as a markdown link: `[short-name:line](../../path/to/file.ts#L42)`. Use a `#L` line anchor. Use the file's basename (or shortest unambiguous suffix) plus line number as the link text. The relative path must be dynamically derived — never hardcode the depth.
+6. **Each stop gets one ultra-concise line of framing** (≤15 words) — why this approach was chosen here and what it achieves in the context of the change. No paragraphs.
+
+Format each stop as framing first, link on the next indented line:
+
+```markdown
+## Suggested Review Order
+
+**{Concern name}**
+
+- {one-line framing}
+  [`file.ts:42`](../../src/path/to/file.ts#L42)
+
+- {one-line framing}
+  [`other.ts:17`](../../src/path/to/other.ts#L17)
+
+**{Next concern}**
+
+- {one-line framing}
+  [`file.ts:88`](../../src/path/to/file.ts#L88)
+```
+
+> The `../../` prefix above is illustrative — compute the actual relative path from `{spec_file}`'s directory to each target file.
+
+When there is only one concern, omit the bold label — just list the stops directly.
+
+### Mark Spec Done
+
+Change `{spec_file}` status to `done` in the frontmatter.
+
+Follow `./sync-sprint-status.md` with `target_status` = `review`.
+
+### Commit and Open
+
+1. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
+2. Open the spec in the user's editor so they can click through the Suggested Review Order:
+   - Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters.
+   - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead.
+
+### Display Summary
+
+Display summary of your work to the user, including the commit hash if one was created. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators. Include:
+
+- A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
+- **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
+- Offer to push and/or create a pull request.
+
+Workflow complete.
+
+## On Complete
+
+If anything appears below, follow it as the final terminal instruction before exiting; otherwise exit normally.
+
+{workflow.on_complete}

package/src/drt-skills/4-implementation/drt-quick-dev/step-oneshot.md

@@ -0,0 +1,78 @@
+# Step One-Shot: Implement, Review, Present
+
+## RULES
+
+- **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
+- NEVER auto-push.
+- All review subagents must run at the same model capability as the current session.
+- Run subagents synchronously: launch them together, then wait for all results before continuing.
+
+## INSTRUCTIONS
+
+### Implement
+
+Follow `./sync-sprint-status.md` with `target_status` = `in-progress`.
+
+Implement the clarified intent directly.
+
+### Review
+
+Execute these review layers in parallel wherever their execution methods allow, following each layer's instruction verbatim after substituting any runtime placeholders:
+
+{workflow.oneshot_review_layers}
+
+If a layer's instruction requires subagents and none are available, generate one review prompt file per such layer in `{{.implementation_artifacts}}` and HALT. Ask the human to run each in a separate session and paste back the findings.
+
+### Classify
+
+Deduplicate all review findings. Three categories only:
+
+- **patch** — trivially fixable. Auto-fix immediately.
+- **defer** — pre-existing issue not caused by this change. Append one new entry to `{{.deferred_work_file}}` using this format. Do not modify existing entries or look for duplicates.
+  ```markdown
+  - source_spec: `{spec_file}`
+    summary: <one sentence>
+    evidence: <why this is real>
+  ```
+- **reject** — noise. Drop silently.
+
+If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding.
+
+### Generate Spec Trace
+
+Set `title` = a concise title derived from the clarified intent.
+
+Write `{spec_file}` using `./spec-template.md`. Fill only these sections — delete all others:
+
+1. **Frontmatter** — set `title: '{title}'`, `type`, `created`, `status: 'done'`. Add `route: 'one-shot'`.
+2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal.
+3. **Suggested Review Order** — append after Intent. Build using the same convention as `./step-05-present.md` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing).
+
+Follow `./sync-sprint-status.md` with `target_status` = `review`.
+
+### Commit
+
+If version control is available and the tree is dirty, create a local commit with a conventional message derived from the intent. If VCS is unavailable, skip.
+
+### Present
+
+1. Open the spec in the user's editor so they can click through the Suggested Review Order:
+   - Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters.
+   - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead.
+2. Display a summary in conversation output, including:
+   - The commit hash (if one was created).
+   - List of files changed with one-line descriptions. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — this differs from spec-file links which use spec-file-relative paths.
+   - Review findings breakdown: patches applied, items deferred, items rejected. If all findings were rejected, say so.
+   - A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
+   - **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
+3. Offer to push and/or create a pull request.
+
+HALT and wait for human input.
+
+Workflow complete.
+
+## On Complete
+
+If anything appears below, follow it as the final terminal instruction before exiting; otherwise exit normally.
+
+{workflow.on_complete}

package/src/drt-skills/4-implementation/drt-quick-dev/sync-sprint-status.md

@@ -0,0 +1,19 @@
+# Sync Sprint Status
+
+Shared sub-step for updating `sprint-status.yaml` during quick-dev. Called from any route (plan-code-review, one-shot, future routes) with a `target_status` parameter.
+
+## Preconditions
+
+Skip this entire file (return to caller) if ANY of:
+- `story_key` is unset
+- `{{.sprint_status}}` does not exist on disk
+
+## Instructions
+
+1. Load the FULL `{{.sprint_status}}` file.
+2. Find the `development_status` entry matching `{story_key}`. If not found, warn the user once (`"{story_key} not found in sprint-status; skipping sprint sync"`) and return to caller.
+3. **Idempotency check.** If `development_status[{story_key}]` is already at `target_status` or a later state (`review` is later than `in-progress`; `done` is later than both), return to caller — no write needed. Never regress a story's status.
+4. Set `development_status[{story_key}]` to `{target_status}`.
+5. **Epic lift (only when `target_status` = `in-progress`).** Derive the parent epic key as `epic-{N}` from the leading numeric segment of `{story_key}` (e.g., `3-2-digest-delivery` → `epic-3`). If that entry exists and is `backlog`, set it to `in-progress`. Leave it alone otherwise. Skip this sub-step entirely when `target_status` is not `in-progress`.
+6. Refresh `last_updated` to the current date.
+7. Save the file, preserving ALL comments and structure including STATUS DEFINITIONS and WORKFLOW NOTES.

package/src/drt-skills/4-implementation/drt-quick-dev/workflow.md

@@ -0,0 +1,85 @@
+# Quick Dev New Preview Workflow
+
+**Goal:** Turn user intent into a hardened, reviewable artifact.
+
+**CRITICAL:** If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions.
+
+Subagents, when the capability is available, are an important part of this workflow. Use them as directed by the workflow steps.
+If you need an explicit user instruction to run them, ask once now for the whole workflow run.
+
+## READY FOR DEVELOPMENT STANDARD
+
+A specification is "Ready for Development" when:
+
+- **Actionable**: Every task has a file path and specific action.
+- **Logical**: Tasks ordered by dependency.
+- **Testable**: All ACs use Given/When/Then.
+- **Complete**: No placeholders or TBDs.
+- **Sufficient**: No known requirement, acceptance, dependency, or implementation gaps remain unresolved.
+- **Coherent**: No unresolved ambiguities or internal contradictions.
+
+## SCOPE STANDARD
+
+A specification should target a **single user-facing goal** within **900–1600 tokens**:
+
+- **Single goal**: One cohesive feature, even if it spans multiple layers/files. Multi-goal means >=2 **top-level independent shippable deliverables** — each could be reviewed, tested, and merged as a separate PR without breaking the others. Never count surface verbs, "and" conjunctions, or noun phrases. Never split cross-layer implementation details inside one user goal.
+  - Split: "add dark mode toggle AND refactor auth to JWT AND build admin dashboard"
+  - Don't split: "add validation and display errors" / "support drag-and-drop AND paste AND retry"
+- **900–1600 tokens**: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents.
+- **Neither limit is a gate.** Both are proposals with user override.
+
+## Conventions
+
+- Bare paths (e.g. `step-01-clarify-and-route.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Execute Prepend Steps
+
+Execute each of these steps in order before proceeding (`_None._` means skip):
+
+{workflow.activation_steps_prepend}
+
+### Step 2: Load Persistent Facts
+
+Treat every entry below as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` -- load the referenced contents as facts. All other entries are facts verbatim (`_None._` means none):
+
+{workflow.persistent_facts}
+
+### Step 3: Execute Append Steps
+
+Execute each of these steps in order (`_None._` means skip):
+
+{workflow.activation_steps_append}
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+- **Micro-file Design**: Each step is self-contained and followed exactly
+- **Just-In-Time Loading**: Only load the current step file
+- **Sequential Enforcement**: Complete steps in order, no skipping
+- **State Tracking**: Persist progress via spec frontmatter and in-memory variables
+- **Append-Only Building**: Build artifacts incrementally
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Read the entire step file before acting
+2. **FOLLOW SEQUENCE**: Execute sections in order
+3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
+4. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- **NEVER** load multiple step files simultaneously
+- **ALWAYS** read entire step file before execution
+- **NEVER** skip steps or optimize the sequence
+- **ALWAYS** follow the exact instructions in the step file
+- **ALWAYS** halt at checkpoints and wait for human input
+
+## FIRST STEP
+
+Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow.