design-architect

name

design-architect

description

Design-before-code protocol. Routes new features, refactors, and complex changes through the appropriate design artifact BEFORE implementation begins. Use when the user asks to design a feature, write an RFC, think through architecture, plan a new skill, structure a large refactor, or define the implementation approach before coding. Triggers: "design", "RFC", "architecture", "new skill", "new feature", "large change", "need a plan", "design-architect", "tech spec", "ADR".

design-architect — Design-Before-Implementation Protocol

Purpose

The agent must stop and design before writing code when it detects a qualifying task. This skill does NOT replace existing templates (PLANS.md, RFC, runbooks) — it routes to the correct template and verifies the quality of the design artifact.

When to Activate

Activate when:

1. Creating a new skill
2. New feature / capability touching >2 files
3. Refactor affecting >1 module
4. Task with estimated effort >1h
5. Working with external API contracts or schema changes
6. User explicitly requests design / RFC / architecture
7. Agent detects high uncertainty (multiple equally viable approaches)

Do NOT activate:

• Bug fix with clear single-file scope
• Documentation-only updates
• Routine graph node creation (graph-writer)
• Research queries (autoresearch)
• Task with explicit detailed instructions from the user

---

Execution Protocol

Step 1 — Classification (Route)

Determine two routing dimensions:

1. Track — where the main design artifact lives
2. Artifact mode — in what form to record decisions within that track

Full track routing table: references/ROUTING_MATRIX.md

Track	When	Template
A — ExecPlan	>4h, multi-module, progress tracking	PLANS.md (root)
B — RFC	Cross-project, infra, feature transfer, new API	99_process/RFC_TEMPLATE_feature_transfer_cold_start.md
C — Runbook	Bounded task for a subagent	99_process/agent_runbooks/_template.md
D — Brief	<2h, moderate complexity	references/LIGHTWEIGHT_DESIGN_BRIEF.md

Artifact mode rules:

• ADR mode — when you need to record an architectural decision, trade-off, or choice between alternatives
• Tech-spec mode — when you need an implementation handoff, engineering spec, or precise description of interfaces / rollout / testing
• Default mode — if neither a separate ADR nor tech-spec form is needed, stay with the base track template

How to choose artifact mode:

• If the key question is "what do we choose and why" → ADR mode
• If the key question is "how exactly to build / deploy this" → Tech-spec mode
• If both levels are needed → ADR first, then Tech-spec

If the task is a new code component of an existing skill → additionally apply the contract-first protocol (design draft → schema → eval criteria → code). Ref: skills/autoresearch/references/DESIGN_FLOW.md.

Step 1.5 — ArchGate EMOGSSB (Architectural Decision Gate)

Mandatory for Track A, B, and any decision touching infrastructure, new integrations, or contract changes between components. Optional for Track C, D.

Full protocol: references/ARCHGATE_EMOGSSB.md

Summary:

1. Identify 1-2 critical characteristics (red flag)
2. Evaluate 7 EMOGSSB characteristics: Evolvability / Scalability / Learnability / Generativity / Speed / Modernity / Security
3. Each: pass / weak / blocker
4. Blocker in a critical characteristic = STOP — do not proceed to scaffolding

If ArchGate passes → proceed to Step 2. If STOP → reformulate the decision and return to Step 1.

Step 2 — Scaffolding

Read the chosen track template and fill in the required sections.

Minimum for any track:

• Problem / purpose (1-3 sentences)
• Scope (in / out)
• Definition of Done (verifiable)
• Safety / rollback

Then overlay the artifact mode, if needed:

• references/adr-template.md — for ADR mode
• references/technical-spec-template.md — for Tech-spec mode

Artifact mode does not replace the track. It refines the form of the design artifact within the track.

Examples:

• Track A + ADR — large ExecPlan where the key decision is separately recorded as an ADR block
• Track B + ADR — RFC containing a formal decision record
• Track D + Tech-spec — short brief extended into an implementation spec
• Track C + Tech-spec — runbook for a subagent with a clear implementation handoff

Before proceeding to Step 3 — run the pre-flight checklist: references/DESIGN_CHECKLIST.md

Step 3 — Review Checkpoint

Hard gate. Present the design artifact to the user and wait for confirmation. Without an explicit "go" / "greenlight" / "approved" — do not start implementation.

What to show:

• Chosen track and why
• Chosen artifact mode (default / ADR / Tech-spec) and why
• Completed design artifact
• Key decisions and trade-offs
• Estimated effort

Step 4 — Transition to Implementation

After approval:

1. If Track A — design becomes a living document (update Progress / Decision Log)
2. If Track B — RFC file remains as a decision archive
3. If Track C — runbook is handed off to the subagent
4. If Track D — brief can be inline, not necessarily saved as a separate file

---

Ontology Constraints

If the design artifact will lead to graph node creation — declare in advance:

• Node type(s) from config/ontology.yaml
• Cluster(s)
• Relation type(s)

Compact reference: skills/graph-writer/SKILL.md (canonical vocabulary tables).

---

Related Skills

Skill	When to engage
autoresearch	If design needs a research phase — first delegate to autoresearch, then return to design
graph-writer	For graph nodes arising from design — hand off to graph-writer after approval
config-guardian	If design includes config changes — use config-guardian for safe execution
repo-task-proof-loop	For autonomous code → verify → PR cycle after design approval

---

Example Flow

Request: "I want a new skill for monitoring email campaigns"

Agent executes:

1. Step 1 — Route: New skill, estimated ~3h → Track A (ExecPlan) + contract-first for code
2. Step 2 — Scaffold: Fills in ExecPlan in PLANS.md:
   • Purpose: monitor open rate / bounce rate for email campaigns
   • Scope: read-only monitoring only, not sending
   • Milestones: SKILL.md → references/ → code → tests → integration
   • DoD: skill works with python3 -m skills.email-monitor.check --campaign-id X
   • Rollback: delete skills/email-monitor/ directory
3. Step 3 — Review: Shows ExecPlan to the user, waits for "go"
4. Step 4 — Implementation: Starts with design draft in references/, then code

---

🇺🇦 Українською

Протокол "спочатку проектуй, потім кодуй". Маршрутизує нові фічі, рефактори та складні зміни через відповідний design-артефакт (ExecPlan, RFC, Runbook або Brief) до початку реалізації. Включає ArchGate перевірку та обов'язковий review checkpoint перед кодуванням.