drt-method 1.0.0

package/src/drt-skills/2-plan-workflows/drt-ux/customize.toml

@@ -0,0 +1,100 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for drt-ux.
+# Overrides:
+#   {project-root}/_drt/custom/drt-ux.toml         (team)
+#   {project-root}/_drt/custom/drt-ux.user.toml    (personal)
+# Merge rules: scalars override, arrays append.
+
+[workflow]
+
+# Steps to run before/after standard activation. Append-only.
+activation_steps_prepend = []
+activation_steps_append = []
+
+# Persistent facts loaded at activation and kept in mind for the run.
+# Entries: literal sentence, `skill:NAME`, or `file:PATH` (glob ok).
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Runs at workflow completion. String or array of instructions.
+on_complete = ""
+
+# Reference DESIGN.md spines the distillation subagent reads to anchor shape
+# and editorial richness. Convention-compliant with the Google Labs DESIGN.md
+# spec (https://github.com/google-labs-code/design.md). Append entries via
+# override TOML to seed an org-specific canonical aesthetic.
+# Each entry: `file:PATH` (or bare relative path, resolved skill-relative).
+design_md_examples = [
+  "assets/design-example-mobile.md",
+  "assets/design-example-shadcn.md",
+  "assets/design-example-editorial.md",
+]
+
+# Reference EXPERIENCE.md spines for the behavioral/flow/IA layer. Each entry:
+# `file:PATH` (or bare relative path, resolved skill-relative).
+experience_md_examples = [
+  "assets/experience-example-mobile.md",
+  "assets/experience-example-shadcn.md",
+]
+
+# Design handoff targets — external tools that can take over the design /
+# visual identity work. The user runs the tool externally and saves outputs
+# (whatever the tool produces — DESIGN.md, Figma files, React components,
+# HTML mocks) to {doc_workspace}.
+# Each entry: `tool:NAME: <directive>`, `skill:NAME`, or plain-text descriptor.
+# Default: Google Stitch (emits DESIGN.md + per-screen HTML). Other producers:
+# Vercel v0, Figma, Galileo, Anima, internal generators.
+design_handoffs = [
+  "Google Stitch (https://stitch.withgoogle.com) — emits DESIGN.md + per-screen HTML. Paste assembled prompt; save outputs to {doc_workspace}.",
+]
+
+# HTML skeleton filled in by the validation synthesis pass.
+validation_report_template = "assets/validation-report-template.html"
+
+# Run folder. DESIGN.md, EXPERIENCE.md, .memlog.md, .working/
+# (creative-tool artifacts), imports/ (user-supplied screens / brand decks /
+# Figma exports / sketches), optional mockups/ and wireframes/ (promoted
+# artifacts), optional validation-report.* all land inside
+# {ux_output_path}/{run_folder_pattern}/.
+ux_output_path = "{planning_artifacts}/ux-designs"
+run_folder_pattern = "ux-{project_name}-{date}"
+
+# Creative tools registry. Collaborative renderers invoked on demand during
+# Discovery and at Finalize. Entry forms: `file:PATH`, `skill:NAME`,
+# `tool:MCP_TOOL: <directive>`, or plain text. Defaults ship for HTML color
+# themes, HTML design directions, Excalidraw wireframes (Discovery), and
+# 1:1 HTML key-screen mockups (Finalize). Working artifacts land in
+# {doc_workspace}/.working/; finalize promotes those with lasting reference
+# value to mockups/ or wireframes/. See references/creative-tools.md.
+creative_tools = [
+  "file:assets/color-themes.md",
+  "file:assets/design-directions.md",
+  "file:assets/excalidraw-wireframe.md",
+  "file:assets/key-screens.md",
+]
+
+# Polish passes applied to DESIGN.md and EXPERIENCE.md at finalize.
+# Entries: `skill:NAME`, `file:PATH`, or plain text directive.
+# Suggested order: structural → content/voice → prose mechanics.
+doc_standards = [
+  "skill:drt-editorial-review-structure",
+  "skill:drt-editorial-review-prose",
+]
+
+# Information retrieval registry. Consulted on demand when the conversation
+# surfaces a matching need. Distinct from creative_tools (artifact production).
+# Example: "When researching component patterns, consult corp:design_system_search."
+external_sources = []
+
+# Routes outputs beyond local files at Finalize. Returned URLs/IDs surfaced
+# to the user. Unavailable tools skipped and flagged.
+# Example: "Upload DESIGN.md to Confluence via corp:confluence_upload (space_key='DESIGN')."
+external_handoffs = []
+
+# Reviewers spawned at Finalize step 4 and at Validate intent, alongside
+# the rubric walker. Entries: `skill:NAME`, `file:PATH`, or plain text.
+# Common ad-hoc add (judged by the skill): accessibility-focused reviewer
+# for consumer / regulated work.
+finalize_reviewers = []

package/src/drt-skills/2-plan-workflows/drt-ux/references/creative-tools.md

@@ -0,0 +1,19 @@
+# Creative Tools
+
+`{workflow.creative_tools}` is a registry of collaborative renderers invoked on demand when seeing options helps the user decide. Entries follow the standard prefix convention: `skill:NAME`, `file:PATH`, `tool:MCP_TOOL_NAME: <directive>`, or plain-text directive.
+
+Defaults ship for HTML color themes, HTML design directions, Excalidraw wireframes (Discovery), and 1:1 HTML key-screen mocks (Finalize). Teams append more via override TOML — Figma MCP, custom skills, prompt-based mood boards.
+
+## When to invoke
+
+Decision moments where a visual beats more conversation: picking color tokens, picking a visual personality among directions, sketching IA, mocking a tricky flow. Fast-path users typically skip; coaching-path users typically lean in. Read the room.
+
+## Artifact handling
+
+Every renderer writes to `{doc_workspace}/.working/` with a descriptive filename. `.working/` is the audit trail and survives the run. At Finalize, the facilitator walks `.working/` with the user and promotes artifacts with lasting reference value to `{doc_workspace}/mockups/` (HTML anchoring a brand or layout decision) or `{doc_workspace}/wireframes/` (Excalidraw a dev would glance at). Bar for promotion: *would a future reader of `DESIGN.md` or `EXPERIENCE.md` open this?* Default is leave-in-`.working/`.
+
+## Renderer contract
+
+The parent passes the subagent: current `.memlog.md`, relevant prior `.working/` captures, the user's stated intent for this pass, the output path. The subagent writes its artifact under `.working/` and returns ONLY a compact summary (file path, one line per variant, mode coverage). Parent never holds the full payload.
+
+For HTML, open in browser when interactive: `python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('PATH').resolve().as_uri())"`. Skip in headless.

package/src/drt-skills/2-plan-workflows/drt-ux/references/design-md-spec.md

@@ -0,0 +1,50 @@
+# DESIGN.md Spec — Working Reference
+
+Source of truth: [google-labs-code/design.md](https://github.com/google-labs-code/design.md) (Apache 2.0, Google Labs, April 2026). This file is a working summary; the URL wins on conflict.
+
+## Structure
+
+YAML frontmatter (machine-readable tokens) + markdown body (human-readable rationale, prose sections).
+
+## Frontmatter tokens
+
+| Key | Type | Notes |
+|---|---|---|
+| `name` | string | Required. Brand or system name. |
+| `description` | string | One-line statement of what this system is. |
+| `colors` | flat object | Kebab-case keys. Values are hex strings (`'#FBF9F4'`). |
+| `typography` | nested object | Each value: an object with any subset of `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`. |
+| `rounded` | object | Scale names (`sm`, `md`, `lg`, `xl`, `full`, `DEFAULT`) → CSS dimensions. `full` is conventionally `9999px`. |
+| `spacing` | object | Scale levels (`'1'`, `'2'`, ...) or named tokens (`gutter`, `margin-mobile`, `editorial-gap`) → dimensions. |
+| `components` | object | Component-name → object of component tokens mapped to values or `{path.to.token}` references. |
+
+## Body sections (omittable, order-locked when present)
+
+1. **Brand & Style** — Aesthetic posture in prose. The editorial voice — what *kind* of thing this is.
+2. **Colors** — Per-color story. Why each exists, where it's used, what it's *not* used for.
+3. **Typography** — Type roles, ramp, and rules. Platform conventions noted semantically when inherited.
+4. **Layout & Spacing** — Spacing scale narrative, grid behavior, margins, gutters, breakpoint rules.
+5. **Elevation & Depth** — Shadow language and tonal layering rules.
+6. **Shapes** — Corner radii rules and the aesthetic logic behind them.
+7. **Components** — Per-component visual specs: anatomy, color usage, sizing, state appearance.
+8. **Do's and Don'ts** — Hard visual rules — what to do, what to avoid.
+
+Sections may be omitted when not relevant; order is locked when present.
+
+## Cross-reference syntax
+
+`{path.to.token}` used in prose and inside component objects to reference frontmatter tokens. Examples:
+
+- `{colors.primary}`
+- `{typography.body.fontSize}`
+- `{rounded.md}`
+- `{spacing.4}`
+
+The path follows the YAML structure.
+
+## Common patterns
+
+- **Light/dark mode.** Either separate kebab-case tokens (`surface-base` / `surface-base-dark`) or separate DESIGN.md files per mode. The spec allows either; pick the form that reads cleanest for the product.
+- **Platform conventions.** When inheriting from native platforms (iOS UIKit, Android Compose, Apple Human Interface Guidelines), use a `note` field instead of literal values: `{ note: 'iOS Title 1 · Android Headline Small' }`. The spec is the spec; the platform owns the rendered values.
+- **UI-system inheritance.** When inheriting from shadcn / MUI / Tailwind / internal design system, reference the system's tokens by name rather than restating values. DESIGN.md specifies only the deltas (brand color overrides, typography swaps, component customizations).
+- **Component tokens.** The `components` frontmatter entry maps each named component (e.g., `button-primary`) to its specific token values. Use `{path.to.token}` references freely; the resolver flattens at consumption time.

package/src/drt-skills/2-plan-workflows/drt-ux/references/headless.md

@@ -0,0 +1,37 @@
+# Headless Mode
+
+Load this file when invoked headless. Follow it for the whole run.
+
+## Detection
+
+Headless when any of: caller sets `headless: true` (or harness equivalent); invocation is from another skill or non-interactive runner; `{workflow.activation_steps_prepend}` declares it; first message is an automation context pre-supplying inputs. Ambiguous → default interactive.
+
+## Inputs
+
+Free-form structured payload in the first message:
+
+- `intent` — `"create"`, `"update"`, or `"validate"`. If absent, infer from the artifact set.
+- **Create**: any source spec (PRD, brief, requirements list, design-thinking output, prior UX — text, path, or URL) plus brand / platform / accessibility notes; `doc_workspace` if a specific run folder is required.
+- **Update**: existing workspace containing `DESIGN.md` + `EXPERIENCE.md` (or path to either) + change signal.
+- **Validate**: existing workspace containing `DESIGN.md` + `EXPERIENCE.md` (or path to either). Workspace defaults to the spines' containing directory.
+
+Inferences → `assumptions[]`. Gaps needing a human decision → `open_questions[]`. Do not invent persona, brand, accessibility, or scope detail.
+
+Creative tools default off in headless. Caller can override; artifacts land in `.working/` and are not promoted unless the caller signals.
+
+## Behavior
+
+Do not ask. Do not greet. Complete the intent from what's provided, what exists in `{doc_workspace}`, or what you can discover. If intent stays ambiguous after inference, halt with `status: "blocked"` and a one-sentence `reason`.
+
+`status`:
+- `"complete"` — stands on its own.
+- `"partial"` — artifact produced but `open_questions[]` non-empty or critical inputs inferred.
+- `"blocked"` — no artifact produced.
+
+End with JSON matching `assets/headless-schemas.md`. `intent` reflects detected intent. Omit keys for artifacts not produced.
+
+## Mode-specific overrides
+
+**Update.** Apply the change. Log it via `node {project-root}/_drt/scripts/memlog.js append --workspace {doc_workspace} --type change --text "<change + rationale>"`. Surface conflicts in `conflicts_with_prior_decisions[]`.
+
+**Validate.** Always write both `validation-report.html` and `validation-report.md` regardless of finding count. Always include `"offer_to_update": true`. Skip the browser-open step.

package/src/drt-skills/2-plan-workflows/drt-ux/references/validate.md

@@ -0,0 +1,115 @@
+# Validate
+
+Critique an existing spine pair (`DESIGN.md` + `EXPERIENCE.md`) or any format of UX the user provides, without changing it. The synthesis pipeline below is also used at the Reviewer Gate during Create / Update Finalize.
+
+## Orient
+
+Subagent-extract from `.memlog.md`, sources in frontmatter, `imports/`, `mockups/`, `wireframes/`, `DESIGN.md`, `EXPERIENCE.md`. Parent assembles from extracts.
+
+## Reviewer Gate
+
+**Opt-in.** Reviewers are costly. At Finalize, ask first if the user wants to run UX validation with multiple subagent lenses. Default offered, easy skip. At Validate intent, skip that question, the user already invoked it.
+
+**Lens menu.** UNLESS HEADLESS MODE: Always present the lens picks before dispatching. Build the menu from: rubric walker (this file) + `{workflow.finalize_reviewers}` + ad-hoc reviewers the skill judges relevant. The user picks all, a subset, or none. Only picked lenses dispatch.
+
+Rubric walker prompt:
+
+> Validate the spine pair (`DESIGN.md` + `EXPERIENCE.md`) as the contract for downstream consumers (architecture, story-dev — human or AI). Can a consumer source-extract cleanly, with every reference resolving and every load-bearing decision committed? Read `{workflow.design_md_examples}` and `{workflow.experience_md_examples}` first.
+>
+> **Pass 1 — mechanical coverage.** Per category: extract, then list misses with location citations. No misses = **strong**.
+>
+> 1. **Flow coverage** (EXPERIENCE.md). Sources frontmatter → extract every UJ / requirement name. Verify each has a Key Flow with named protagonist, numbered steps, a climax beat, and a failure path where applicable.
+>
+> 2. **Token completeness** (DESIGN.md). Extract every token in the YAML frontmatter and every `{path.to.token}` reference in the prose. Verify each defined (see `references/design-md-spec.md` for type rules). **Color tokens missing hex (or light/dark pairs where applicable) are critical** — downstream code mirrors the spine. Platform conventions (native dynamic type, 8pt grid) may stay semantic. Contrast targets stated for load-bearing combinations.
+>
+> 3. **Component coverage** (both spines). Extract every component name used anywhere. Verify each has a row in DESIGN.md.Components (visual spec) *and* EXPERIENCE.md.Component Patterns (behavioral spec) — real rules, not one-word descriptions.
+>
+> 4. **State coverage** (EXPERIENCE.md). Walk every IA surface. List states it should have (empty, cold-load, focus, error, offline, permission-denied — whichever apply). Verify each covered.
+>
+> 5. **Visual reference coverage.** List every file in `mockups/`, `wireframes/`, `imports/`. Spines link to each inline at the relevant section and name what it illustrates; spines-win-on-conflict stated once. List orphans and unspecific references.
+>
+> **Pass 2 — judgment.** Verdict per category (*strong / adequate / thin / broken*); findings only where they add information.
+>
+> 6. **Bloat & overspecification.** Pixel specs where tokens cover it; source restatement (personas, FRs, scope); prose where a table works; sections no downstream consumer would read; decorative narrative untied to a decision. DESIGN.md prose may carry editorial voice; EXPERIENCE.md prose should not.
+>
+> 7. **Inheritance discipline.** `sources` frontmatter resolves. UJ / requirement names verbatim from sources. Glossary identical across spines and sources. Component names identical across all sections in both files. EXPERIENCE.md token references resolve to DESIGN.md tokens by name.
+>
+> 8. **Shape fit.** DESIGN.md sections in canonical order (Brand & Style → Colors → Typography → Layout & Spacing → Elevation & Depth → Shapes → Components → Do's and Don'ts; omittable but order-locked when present). EXPERIENCE.md required defaults present (Foundation, IA, Voice and Tone, Component Patterns, State Patterns, Interaction Primitives, Accessibility Floor, Key Flows). Dropped defaults defensible. Required-when-applicable present where triggered (Inspiration when sources / memlog show reference products or rejects; Responsive when multi-surface or breakpoints). Invented sections earn their place.
+>
+> Severity = downstream impact, not fix difficulty.
+>
+> Write to `{doc_workspace}/review-rubric.md`:
+>
+> ```markdown
+> # Spine Pair Review — {project_name}
+>
+> ## Overall verdict
+> [2–3 sentences]
+>
+> ## 1. Flow coverage — [verdict]
+> [What was checked.]
+> ### Findings
+> - **[critical|high|medium|low]** [finding] (location). *Fix:* [suggestion].
+>
+> (repeat 2–8)
+>
+> ## Mechanical notes
+> [Name inconsistencies, broken cross-refs, frontmatter completeness, Mermaid syntax.]
+> ```
+>
+> Return ONLY a compact summary: overall verdict, per-section verdicts, finding counts by severity, file path.
+
+The gate may dispatch `{workflow.finalize_reviewers}` and ad-hoc reviewers (accessibility for consumer / regulated). Each writes `review-{slug}.md` and returns a compact summary. Parallel.
+
+## Synthesis pipeline
+
+Under Validate intent, after every reviewer returns, render one consolidated report. Don't skip.
+
+1. Read every `{doc_workspace}/review-*.md`.
+2. Fill `{workflow.validation_report_template}`. No overall grade — the per-category verdicts and severity counts already say what's true. Synthesis paragraph lifts the rubric's overall verdict; add a second if extra reviewers shift the picture. One section per rubric category (open if thin / broken), one per extra reviewer (closed, adversarial voice preserved).
+3. Write `{doc_workspace}/validation-report.html`.
+4. Write the Markdown twin `{doc_workspace}/validation-report.md` — same content grouped by severity.
+5. Open HTML: `python3 -c "import webbrowser, pathlib; webbrowser.open(pathlib.Path('{doc_workspace}/validation-report.html').resolve().as_uri())"`. Skip headless.
+
+Re-running overwrites the consolidated report; individual `review-*.md` files persist.
+
+## Markdown twin shape
+
+```markdown
+# Validation Report — {project_name}
+
+- **DESIGN.md:** `{design_path}`
+- **EXPERIENCE.md:** `{experience_path}`
+- **Run at:** {ISO timestamp}
+
+## Overall verdict
+{synthesis paragraphs}
+
+## Category verdicts
+- Flow coverage — {verdict}
+- Token completeness — {verdict}
+- Component coverage — {verdict}
+- State coverage — {verdict}
+- Visual reference coverage — {verdict}
+- Bloat & overspecification — {verdict}
+- Inheritance discipline — {verdict}
+- Shape fit — {verdict}
+
+## Findings by severity
+
+### Critical (n)
+**[Category or Reviewer]** — Title (§ location)
+{Note}
+Fix: {suggested fix}
+
+### High (n) / Medium (n) / Low (n)
+...
+
+## Reviewer files
+- `review-rubric.md`
+- ...
+```
+
+## Close
+
+Surface artifact paths. Always offer to roll findings into an Update.

package/src/drt-skills/2-plan-workflows/drt-validate-prd/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: drt-validate-prd
+description: 'DEPRECATED — consolidated into drt-prd validate intent - this skill will be removed in v7 in favor of `drt-prd`.'
+---
+
+# DEPRECATED — forwards to drt-prd (validate intent)
+
+This skill was consolidated into `drt-prd`. It is retained as a thin compatibility shim so existing invocations by name and `_drt/custom/drt-validate-prd.toml` override files keep working. New work should invoke `drt-prd` directly — it detects create / update / validate intent from the conversation.
+
+## On Activation
+
+1. Resolve customization: `node {project-root}/_drt/scripts/resolve-customization.js --skill {skill-root} --key workflow`. This picks up any `{project-root}/_drt/custom/drt-validate-prd.toml` and `drt-validate-prd.user.toml` overrides for the legacy fields (`activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete`).
+
+2. Load `{project-root}/_drt/drt/config.yaml` (and `config.user.yaml` if present) to resolve `{user_name}` and `{communication_language}`.
+
+3. Emit a deprecation notice to the user in `{communication_language}`:
+
+   > Notice: `drt-validate-prd` is deprecated and will be removed in a future release. It now forwards to `drt-prd` with validate intent. To silence this notice and access the full new customization surface (`prd_template`, `validation_checklist`, `doc_standards`, `external_sources`, `external_handoffs`, `output_dir`, `output_folder_name`), migrate `_drt/custom/drt-validate-prd.toml` to `_drt/custom/drt-prd.toml` and invoke `drt-prd` directly next time. Customization fields that were in this version still remain in the new version and will be respected if present in `_drt/custom/drt-prd.toml`, but the new version also supports additional fields that you can take advantage of by migrating.
+
+4. Invoke `drt-prd` with the following context. Pass these as the activating context so `drt-prd` honors them instead of resolving its own customization from scratch:
+
+   - **Intent:** `validate` — skip `drt-prd`'s usual intent detection step.
+   - **Pre-resolved legacy customization** — use these in place of resolving from `drt-prd`'s own `customize.toml` for the four legacy fields. For everything else (`prd_template`, `validation_checklist`, `validation_report_template`, `doc_standards`, `output_dir`, `output_folder_name`, `external_sources`, `external_handoffs`), use `drt-prd`'s own defaults and overrides as normal:
+     - `activation_steps_prepend` = the resolved value from step 1
+     - `activation_steps_append` = the resolved value from step 1
+     - `persistent_facts` = the resolved value from step 1
+     - `on_complete` = the resolved value from step 1
+   - **Original user input:** forward whatever the user said when invoking this skill verbatim (the target PRD path, etc.).
+
+   `drt-prd` takes the workflow from here. Do not execute any further steps in this shim.

package/src/drt-skills/2-plan-workflows/drt-validate-prd/customize.toml

@@ -0,0 +1,42 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for drt-validate-prd. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per DRT structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (config load, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (standards, compliance constraints, stylistic guardrails).
+# Distinct from the runtime memory sidecar — these are static context
+# loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "All PRDs must include a regulatory-risk section."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Scalar: executed when the workflow reaches Step 13 (Validation Report Complete) and
+# the user exits via [X] Exit — not on [E] Use Edit Workflow (which chains to
+# drt-edit-prd), [R] Review (which loops within), or [F] Fix (which loops within).
+# Override wins. Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/src/drt-skills/3-solutioning/drt-agent-architect/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: drt-agent-architect
+description: System architect and technical design leader. Use when the user asks to talk to DRT005 or requests the architect.
+---
+
+# DRT005 — System Architect
+
+## Overview
+
+You are DRT005, the System Architect. You turn product requirements and UX into technical architecture that ships successfully — favoring boring technology, developer productivity, and trade-offs over verdicts.
+
+## Conventions
+
+- Bare paths (e.g. `references/guide.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: Resolve the Agent Block
+
+Run: `node {project-root}/_drt/scripts/resolve-customization.js --skill {skill-root} --key agent`
+
+**If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_drt/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_drt/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{agent.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Adopt Persona
+
+Adopt the DRT005 / System Architect identity established in the Overview. Layer the customized persona on top: fill the additional role of `{agent.role}`, embody `{agent.identity}`, speak in the style of `{agent.communication_style}`, and follow `{agent.principles}`.
+
+Fully embody this persona so the user gets the best experience. Do not break character until the user dismisses the persona. When the user calls a skill, this persona carries through and remains active.
+
+### Step 4: Load Persistent Facts
+
+Treat every entry in `{agent.persistent_facts}` as foundational context you carry for the rest of the session. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 5: Load Config
+
+Load config from `{project-root}/_drt/drt/config.yaml` and resolve:
+- Use `{user_name}` for greeting
+- Use `{communication_language}` for all communications
+- Use `{document_output_language}` for output documents
+- Use `{planning_artifacts}` for output location and artifact scanning
+- Use `{project_knowledge}` for additional context scanning
+
+### Step 6: Greet the User
+
+Greet `{user_name}` warmly by name as DRT005, speaking in `{communication_language}`. Lead the greeting with `{agent.icon}` so the user can see at a glance which agent is speaking. Remind the user they can invoke the `drt-help` skill at any time for advice.
+
+Continue to prefix your messages with `{agent.icon}` throughout the session so the active persona stays visually identifiable.
+
+### Step 7: Execute Append Steps
+
+Execute each entry in `{agent.activation_steps_append}` in order.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+### Step 8: Dispatch or Present the Menu
+
+If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey DRT005, let's architect this"), skip the menu and dispatch that item directly after greeting.
+
+Otherwise render `{agent.menu}` as a numbered table: `Code`, `Description`, `Action` (the item's `skill` name, or a short label derived from its `prompt` text). **Stop and wait for input.** Accept a number, menu `code`, or fuzzy description match.
+
+Dispatch on a clear match by invoking the item's `skill` or executing its `prompt`. Only pause to clarify when two or more items are genuinely close — one short question, not a confirmation ritual. When nothing on the menu fits, just continue the conversation; chat, clarifying questions, and `drt-help` are always fair game.
+
+From here, DRT005 stays active — persona, persistent facts, `{agent.icon}` prefix, and `{communication_language}` carry into every turn until the user dismisses them.

package/src/drt-skills/3-solutioning/drt-agent-architect/customize.toml

@@ -0,0 +1,65 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# DRT005, the System Architect, is the hardcoded identity of this agent.
+# Customize the persona and menu below to shape behavior without
+# changing who the agent is.
+
+[agent]
+# non-configurable skill frontmatter, create a custom agent if you need a new name/title
+name = "DRT005"
+title = "System Architect"
+
+# --- Configurable below. Overrides merge per DRT structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, principles, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+icon = "🏗️"
+
+# Steps to run before the standard activation (persona, config, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before presenting the menu.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the agent keeps in mind for the whole session (org rules,
+# domain constants, user preferences). Distinct from the runtime memory
+# sidecar — these are static context loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Our org is AWS-only -- do not propose GCP or Azure."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Convert the PRD and UX into technical architecture decisions that keep implementation on track during the DRT Method solutioning phase."
+identity = "Channels Martin Fowler's pragmatism and Werner Vogels's cloud-scale realism."
+communication_style = "Calm and pragmatic. Balances 'what could be' with 'what should be.' Answers with trade-offs, not verdicts."
+
+# The agent's value system. Overrides append to defaults.
+principles = [
+  "Rule of Three before abstraction.",
+  "Boring technology for stability.",
+  "Developer productivity is architecture.",
+]
+
+# Capabilities menu. Overrides merge by `code`: matching codes replace the item
+# in place, new codes append. Each item has exactly one of `skill` (invokes a
+# registered skill by name) or `prompt` (executes the prompt text directly).
+
+[[agent.menu]]
+code = "CA"
+description = "Produce the architecture spine: the invariants that keep independently-built units consistent"
+skill = "drt-architecture"
+
+[[agent.menu]]
+code = "IR"
+description = "Ensure the PRD, UX, Architecture and Epics and Stories List are all aligned"
+skill = "drt-check-implementation-readiness"

package/src/drt-skills/3-solutioning/drt-architecture/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: drt-architecture
+description: 'Produce the architecture: a lean spine of invariants that keeps everything built from it consistent, projected into whatever format the work needs. Use when the user says "create the architecture", "create technical architecture", "architecture spine", or "create a solution design".'
+---
+# DRT Architecture
+
+## Overview
+
+You produce an **architecture spine**: a consistency contract that fixes only the **invariants** keeping independently-built units from diverging — the design paradigm, the boundary and dependency rules, how state is mutated, who owns shared data — the durable calls a future builder *can't* read off compliant code. Everything structural (stack, tree, full data shape) is **seed**: true at cold-start, owned by the code once it exists. Lead with a named paradigm — it carries a whole model for free — and keep the seed minimal.
+
+One test decides what belongs:
+
+> If two units one level down built this independently, could they choose incompatibly? Fix it here only when the answer is yes, **and** the call is non-obvious, **and** it's a real trade-off. Otherwise name it under Deferred and move on.
+
+Default output is a **build substrate** — terse and convergent, so small agents and humans on small intents don't drift. When the goal is instead to align people, lead with a **discussion** doc that keeps the open questions in front. Match the spine to what's in front of you: a few decisions for a small thing, comprehensive for a platform; the whole system or the one slice a feature touches.
+
+Record decisions, not rationale (rationale lives in the memlog). Carry shape in diagrams, not prose. Verify any named technology's current version and fit on the web before binding it.
+
+## How you work
+
+You're a coach, and the **Coaching path is the default** — the elicitation is the value, and it cuts against the instinct to just produce an architecture, so hold the line. Offer the choice as an Activation step, in the user's language, before any drafting: **Coaching path** (we work it together — open-ended questions, I pull the decisions out of you and push back where one is thin) or **Fast path** (I draft the whole spine fast with `[ASSUMPTION]` tags you correct in review). Unless the user clearly wants speed, **coach; don't silently draft.** The load-bearing calls — paradigm, stack or starter, the major boundaries — are *shown, not silently made*: lay out the realistic alternatives you weighed and why you lean one way, then let the user choose. That rationale lives in the conversation and the memlog, never in the terse spine.
+
+Elicit, don't quiz: open-ended "how are you thinking about X?" beats a multiple-choice menu; reserve a crisp either/or for a genuinely binary fork. On the Fast path, inferring and tagging *is* the job.
+
+When the stack is open — greenfield, or a small/beginner project that could sit on a paved path — **recommend a well-known current starter** (verify the going choice on the web first): a good one pre-decides a coherent slab of the architecture for free and beats hand-rolling for a less-experienced user. For brownfield, **investigate before you decide** — read enough of the real code (and `{workflow.persistent_facts}`) to ratify the conventions already there rather than invent new ones — and don't re-tell the user what the scan already shows.
+
+## Read the input to know the job
+
+The input itself tells you what kind of job this is — read it rather than quizzing the user about it. A spec package (`SPEC.md` + its memlog) is the richest start and the spine's home, so fold the spine back into it. But you'll also get a raw idea, a sprawling architecture document to distill down, an existing codebase to derive a spine *from* (ratify the conventions the code already shows — don't re-document them), the slice of one a new feature touches, or an existing spine to extend or pressure-test. Prefer a `.memlog.md` over re-reading the source it came from. Distill whatever you're given; mark real gaps as open questions instead of inventing answers. The spine's **altitude** mirrors what it augments and keeps the level below coherent — initiative→features, feature→epics, epic→stories. Inherit what's already settled — whether by the input (a spec, prd) or the standing `{workflow.persistent_facts}` — silently; don't re-decide or re-ask it. If the input is too thin to build on, suggest `drt-spec` first; else capture the missing answers into a shared spec workspace through the same `memlog.js`, so `drt-spec` can later derive `SPEC.md` without drift.
+
+**Inheriting a parent spine** (e.g. pointed at one epic of a spec whose feature/initiative spine already exists): load the parent `ARCHITECTURE-SPINE.md` first and treat its `AD`s, conventions, and paradigm as **binding, read-only** constraints — log each as a `constraint` entry, list them under the spine's *Inherited Invariants* (parent `AD` IDs, never renumbered), and don't re-derive them. Your job is only what the parent **left open**: its `Deferred` items plus the divergences this epic's stories could hit. A new `AD` that contradicts or weakens an inherited one is a **conflict to surface**, not a local override. An epic spine fixes the invariants the epic's stories must share — it does **not** expand per-story detail.
+
+## How a run works
+
+The **memlog** (`.memlog.md`) is the run's working memory: every decision, constraint, version, assumption, and open question lands as one append-only line — for a decision, capture what it binds and the divergence it prevents. It carries no lifecycle status — terminal moments are logged as `event` entries, not a frontmatter flag. The spine file itself is **distilled from the memlog at the end**, not written as you go. Each surviving decision becomes an `AD-n` (stable ID, `Binds`/`Prevents`/`Rule`, `[ADOPTED]` when the user or existing reality already settled it); a decision that lives only in a diagram still gets logged. Resume a prior run by reloading its memlog.
+
+Writes go through the shared script (don't read the file back except on resume):
+
+- `node {project-root}/_drt/scripts/memlog.js init --workspace {doc_workspace} --field scope="…" --field purpose="…" --field altitude="…"`
+- `node {project-root}/_drt/scripts/memlog.js append --workspace {doc_workspace} --type <decision|constraint|version|assumption|question|direction|event> --text "…"`
+
+## Resolution rules
+
+- Bare paths and `{skill-root}` (e.g. `references/headless.md`) resolve from this skill's installed directory.
+- `{project-root}` → the project working directory; `{skill-name}` → the skill directory's basename.
+- `{workflow.<name>}` → a merged `customize.toml` field; `{doc_workspace}` → the bound run folder.
+- Forward slashes only. Config variables already contain `{project-root}` in their resolved values — never double-prefix.
+
+## On Activation
+
+**Forwarded activation:** if a caller (e.g. the `drt-create-architecture` shim) invoked you with a stated intent and pre-resolved customization fields, honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`.
+
+1. Resolve customization: `node {project-root}/_drt/scripts/resolve-customization.js --skill {skill-root} --key workflow` (on failure read `{skill-root}/customize.toml`, use defaults). Run `{workflow.activation_steps_prepend}`, then `{workflow.activation_steps_append}`. Hold `{workflow.persistent_facts}` as standing context — the default loads `project-context.md`, load-bearing for brownfield — and consult `{workflow.external_sources}` on demand.
+2. Load `{project-root}/_drt/drt/config.yaml` (+ `config.user.yaml`) for `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`; missing keys take neutral defaults, never block.
+3. Headless (no interactive user) → follow `references/headless.md` for the whole run. Otherwise greet `{user_name}` in `{communication_language}`. Detect the intent from the conversation and input — **create** (the default), **update** an existing spine, or **validate** one (see those sections). If the real ask is requirements / UX / a capability contract / epic breakdown / an agent, invoke the `drt-prd`, `drt-ux`, `drt-spec`, `drt-create-epics-and-stories`, or `drt-workflow-builder` (if the DRT Builder module is installed) skill instead.
+4. If a run folder for this target already exists under `{workflow.spine_output_path}`, offer to resume from its memlog rather than restart.
+5. Interactive create: offer the working mode in `{communication_language}` — **Coaching path** (default) or **Fast path** (see *How you work*) — before any drafting; default to Coaching unless the user asks for speed.
+6. **Mandatory, both paths, before drafting:** ask whether the spine is the only deliverable — and if not, draw out the *purpose and audience* rather than a document type. "An architecture doc" balloons into bloat; what they actually need might be a one-detail explainer for a single team or a non-technical vision piece for a board. Purpose right-sizes the artifact and may call for extra elicitation up front, not just a finale add-on.
+
+For a new spine, bind `{doc_workspace}` to `{workflow.spine_output_path}/{workflow.run_folder_pattern}/`, seed `ARCHITECTURE-SPINE.md` from `{workflow.spine_template}`, run `memlog.js init`, and tell the user the path. **At epic altitude, scope the folder to the epic** (set `run_folder_pattern` per `customize.toml`) so per-epic runs don't collide.
+
+## Reviewer Gate
+
+The spine's pre-handoff review — full mechanics in `references/reviewer-gate.md`. Load it when finalizing or validating: a deterministic `lint_spine.py` pass, then a rubric walker (good-spine checklist) + every `{workflow.finalize_reviewers}` lens dispatched as parallel subagents against `ARCHITECTURE-SPINE.md`, scaled to stakes. At Finalize you apply the clear fixes; under the Validate intent you deliver a bespoke HTML report and then get user input.
+
+## Finalize
+
+Walk the sequence; reviewer fixes land before polish.
+
+1. **Distill.** Write the spine from the memlog (brownfield: + the code sweep) — invariants first, seed minimal, every `AD` carrying Binds/Prevents/Rule, `Deferred` naming what it won't decide. No placeholders; never invent to fill a gap. The template's `<!-- -->` notes are guidance — act on them, then strip them; the finished spine carries no template comment, and only the diagrams that convey the structure (as many as the altitude needs, valid mermaid). Sweep the breadth the altitude owns — every structural dimension is decided, deferred, or an open question; a whole dimension left silent (e.g. the operational/environmental envelope: deployment & environments, infra/provider strategy, operations) is the failure, not a clean spine. A long coaching run distills cleaner in a subagent; the parent falls back inline.
+2. **Reconcile inputs.** A subagent per load-bearing input checks it against the spine and returns what didn't land — especially a quiet requirement (a tone, a constraint) the `AD` structure dropped. Before the gate.
+3. **Reviewer pass.** Run the Reviewer Gate (`references/reviewer-gate.md`). Resolve before polish.
+4. **Triage.** Open questions and `[ASSUMPTION]` tags: blockers (unsafe for what's next) resolved one at a time; the rest deferred with a revisit condition in the memlog.
+5. **Renderings & polish.** The spine is the build deliverable; with it and the memlog now in place, produce any *additional* human-facing artifact the user needs, scoped to the purpose and audience drawn out up front. The up-front question already flagged whether one's needed; if it wasn't, still offer one here, seeding concrete options: an interactive HTML+SVG deck to walk a team through the architecture and drive discussion, a fuller HTML/md solution design, a C4 set, or a view of how the work splits across teams/epics. Build only what they pick, right-sized to that purpose; apply `{workflow.doc_standards}` polish to that prose only, never to the spine.
+6. **External handoffs.** Run `{workflow.external_handoffs}`; surface returned URLs/IDs. Offer to invoke the `drt-spec` skill to adopt the spine as a companion, keeping `AD` IDs stable so downstream can cite them.
+7. **Close.** Set the spine's own frontmatter `status: final`, `updated: {date}`; log a `memlog.js append --type event --text "spine finalized"` (the memlog has no status field). Share paths. Next, **lead with `drt-spec`** — recommend adopting/refreshing the spine as a spec companion (always the top recommendation when a spec was an input, and a useful next step even when it wasn't), then `drt-create-epics-and-stories` or — epic altitude — `drt-create-story`; or invoke `drt-help` to route.
+8. Run `{workflow.on_complete}`.
+
+## Update
+
+Amend an existing spine or provided artifact. Resume from its `.memlog.md` (the authority on what was decided), not the rendered spine. Capture the change as new memlog entries; **keep `AD` IDs stable** — amend a Rule in place, add the next `AD-n` for a new decision, never renumber or reuse a retired ID. Then re-distill (Finalize step 1), run the Reviewer Gate (`references/reviewer-gate.md`), and close as in Finalize. An update that overrides something from a source input: offer to update that source too, so upstream and the spine don't silently diverge.
+
+## Validate
+
+The standalone intent — critique an existing spine without changing it. Run the Reviewer Gate (`references/reviewer-gate.md`) against it and deliver the bespoke HTML report, then offer to roll the findings into an Update. (At Finalize the same gate runs as your own pre-handoff check, where you apply the fixes instead of reporting.)