sdg-agents 1.0.5

package/src/assets/dev-guides/ui-prompt-guide.md

@@ -0,0 +1,181 @@
+# UI Specification Guide — Designing Interfaces for AI Agents
+
+> **Audience:** Technical leads and engineers who need to communicate UI requirements through precise technical specifications.
+>
+> **Core principle:** AI agents operate as execution engines for provided design tokens and layout contracts. Precision in input density directly correlates with output accuracy.
+
+---
+
+## Why UI Specifications Fail
+
+Vague UI requests produce generic outputs. agents default to the most common training patterns when gaps exist in the specification. Standardizing the following inputs prevents architectural drift:
+
+1. **Visual System** — palette (OKLCH), preset, typography
+2. **Structural Content** — sections, component hierarchy, data sources
+3. **Execution State** — interactions, lifecycle states (loading/empty/error)
+4. **Negative Constraints** — explicit exclusions to prevent logic drift
+
+---
+
+## The UI Prompt Template
+
+Copy and fill this template when requesting any UI work (page, component, or screen):
+
+```markdown
+## UI Request
+
+### 1. Context
+
+What is this interface for? Who uses it? What problem does it solve?
+
+- Audience: [developers / consumers / internal ops / etc.]
+- Purpose: [data entry / data visualization / marketing / onboarding / etc.]
+
+### 2. Visual Identity
+
+- Palette: [Default Zinc+Blue | Custom: primary=___ secondary=___]
+  OR: "Match the existing project palette"
+- Preset: [BENTO | GLASS | CLEAN | MONO | NEOBRUTALISM | PAPER]
+  OR: "Follow the project preset"
+- Typography: [Precision/Dev | Premium/SaaS | Editorial | Bold | Corporate | Startup | Luxury]
+  OR: "Use project fonts"
+- Theme: [Light only | Dark only | Both (default)]
+
+### 3. Sections & Components
+
+List every visible section in order, top to bottom:
+
+- [ ] Section name — brief description of content
+- [ ] Section name — brief description of content
+
+### 4. Interactions & States
+
+- What happens on click/hover/focus?
+- Which states must be handled? [Loading | Empty | Error | Disabled]
+- Any animations? [None | Subtle entry | Explicit: ___]
+
+### 5. Constraints
+
+- What should NOT be included?
+- Fixed breakpoints or layout restrictions?
+- Any component or library limitations?
+
+### 6. Reference
+
+- Closest existing page/component to derive from: [page name or "none"]
+- Visual reference (if any): [URL or description]
+```
+
+---
+
+## Learn by Example
+
+### ❌ Weak Specification (Low Density)
+
+```markdown
+Create a dashboard for my SaaS app with cards showing metrics and a table.
+Make it look modern and professional with a dark theme.
+```
+
+> **Rationale for failure:** Missing palette definition forces arbitrary color selection. "Modern" and "professional" are subjective terms that trigger generic training defaults. Lack of section enumeration results in layout invention. Missing state definitions (loading/empty) creates incomplete execution contracts.
+
+---
+
+### ✅ Strong Specification (High Density)
+
+```markdown
+## UI Request
+
+### 1. Context
+
+Analytics dashboard for a B2B SaaS tool.
+Audience: internal ops team (power users, 8+ hours/day).
+Purpose: monitor pipeline health — volume, conversion rate, and blocked deals.
+
+### 2. Visual Identity
+
+- Palette: Default Zinc+Blue
+- Preset: BENTO + GLASS
+- Typography: Precision/Dev (JetBrains Mono display, Inter body)
+- Theme: Both (dark as default)
+
+### 3. Sections & Components
+
+- [ ] Header — app logo left, user avatar + notifications right
+- [ ] KPI Row — 3 metric cards: Total Leads, Conversion Rate, Avg Deal Size
+- [ ] Pipeline Chart — horizontal bar chart by stage (Bento cell, full width)
+- [ ] Deals Table — sortable columns: Deal, Owner, Stage, Value, Last Activity
+- [ ] Sidebar — collapsible, nav links: Overview / Deals / Reports / Settings
+
+### 4. Interactions & States
+
+- KPI cards: hover shows sparkline trend (last 30 days)
+- Table: row hover highlights, click opens deal detail drawer
+- All data sections: skeleton loading state required
+- Empty state for table: "No deals match your filters" + clear filters button
+
+### 5. Constraints
+
+- No pie charts — bar and line charts only
+- Table must be sticky-header on scroll
+- Sidebar collapsed by default on screens < 1280px
+- Do not add onboarding tooltips or modals
+
+### 6. Reference
+
+- Derive from existing DashboardPage component
+- Visual reference: Linear issue tracker table density
+```
+
+> **Rationale for success:** Palette specification ensures correct OKLCH token generation. Preset usage locks the visual language. Enumerated sections prevent layout invention. Explicit state requirements ensure full lifecycle handling. Negative constraints block common drift patterns. Reference gives the execution engine a starting point and a density target.
+
+---
+
+## Visual Identity Map
+
+Correlating UI requirements with technical standards:
+
+| You want...                       | Preset        | Palette suggestion        | Typography      |
+| :-------------------------------- | :------------ | :------------------------ | :-------------- |
+| Clean B2B SaaS dashboard          | BENTO + CLEAN | Zinc + Blue (H=250)       | Corporate       |
+| Polished, layered premium product | BENTO + GLASS | Zinc + Violet (H=290)     | Premium/SaaS    |
+| Developer tool or CLI companion   | MONO          | Zinc monochromatic        | Precision/Dev   |
+| Bold marketing or landing page    | NEOBRUTALISM  | High Chroma (Orange H=70) | Bold/Expressive |
+| Content-heavy editorial or docs   | PAPER         | Zinc + Amber (H=80)       | Editorial       |
+| Modern startup / Next.js app vibe | BENTO + CLEAN | Zinc + Blue (H=250)       | Startup/Modern  |
+| Luxury product or high-end brand  | GLASS + PAPER | Custom (ask agent)        | Luxury/Refined  |
+
+---
+
+## The 4 Most Common Drift Patterns (and How to Prevent Them)
+
+| Drift                | How it shows up                         | Prevention in prompt                           |
+| :------------------- | :-------------------------------------- | :--------------------------------------------- |
+| **Palette drift**    | Random colors, poor light/dark contrast | Always specify Palette or say "match project"  |
+| **Layout invention** | Agent adds sections you didn't ask for  | List every section explicitly; add Constraints |
+| **State omission**   | No loading/empty/error states           | Enumerate states in Interactions section       |
+| **Visual pollution** | Border + shadow + bg-color all together | Specify the preset — it constrains decoration  |
+
+---
+
+## Minimal Prompt (When You're in a Hurry)
+
+When speed matters more than precision, provide at minimum:
+
+```markdown
+## UI Request (Minimal)
+
+Context: [1 sentence — what and who]
+Palette: [Default | Custom H=___]
+Preset: [BENTO | GLASS | CLEAN | MONO | NEOBRUTALISM | PAPER]
+Sections: [section 1], [section 2], [section 3]
+Must-handle states: [Loading | Empty | Error]
+Do NOT include: [constraint 1], [constraint 2]
+```
+
+> **Rationale:** Palette + Preset are the two inputs that prevent the most common failures. Everything else can be iterated. Never omit these two.
+
+---
+
+> [!TIP]
+> **Technical iteration is continuous.** A well-structured specification achieves high-level accuracy in the first pass. Use targeted refinement prompts for specific sections that require higher density.

package/src/assets/img/sdg-agents-icon-dark.svg

@@ -0,0 +1,55 @@
+<svg viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg">
+
+  <!-- Clipboard board - dark warm tone -->
+  <rect x="96" y="72" width="320" height="400" rx="28" fill="#3E3224"/>
+  <!-- Board inner face -->
+  <rect x="104" y="80" width="304" height="384" rx="24" fill="#4A3C2C"/>
+
+  <!-- Metal clip - muted steel -->
+  <rect x="186" y="48" width="140" height="56" rx="8" fill="#546E7A"/>
+  <rect x="186" y="48" width="140" height="28" rx="8" fill="#607D8B"/>
+  <!-- Clip hole -->
+  <rect x="218" y="34" width="76" height="36" rx="18" fill="#4A3C2C"/>
+  <rect x="228" y="42" width="56" height="20" rx="10" fill="#5C4A36"/>
+
+  <!-- Paper sheet - dark surface -->
+  <rect x="124" y="100" width="264" height="352" rx="12" fill="#1A1A1A"/>
+  <!-- Paper fold accent -->
+  <path d="M364 100L388 124L364 124Z" fill="#242424"/>
+
+  <!-- Title pill badge -->
+  <rect x="152" y="120" width="208" height="32" rx="16" fill="#7C8FE4"/>
+  <text x="256" y="141" text-anchor="middle" dominant-baseline="central" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="700" fill="#FFFFFF" letter-spacing="1.2">SPEC DRIVEN GUIDE</text>
+
+  <!-- Checklist rows -->
+  <!-- Row 1 - SPEC -->
+  <circle cx="168" cy="192" r="14" fill="#66BB6A"/>
+  <path d="M161 192L166 197L176 187" fill="none" stroke="#1A1A1A" stroke-width="2.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="196" y="197" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="700" fill="#E0DDD6" letter-spacing="1">SPEC</text>
+  <rect x="196" y="205" width="80" height="4" rx="2" fill="#333"/>
+
+  <!-- Row 2 - PLAN -->
+  <circle cx="168" cy="248" r="14" fill="#66BB6A"/>
+  <path d="M161 248L166 253L176 243" fill="none" stroke="#1A1A1A" stroke-width="2.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="196" y="253" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="700" fill="#E0DDD6" letter-spacing="1">PLAN</text>
+  <rect x="196" y="261" width="100" height="4" rx="2" fill="#333"/>
+
+  <!-- Row 3 - CODE -->
+  <circle cx="168" cy="304" r="14" fill="#66BB6A"/>
+  <path d="M161 304L166 309L176 299" fill="none" stroke="#1A1A1A" stroke-width="2.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="196" y="309" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="700" fill="#E0DDD6" letter-spacing="1">CODE</text>
+  <rect x="196" y="317" width="120" height="4" rx="2" fill="#333"/>
+
+  <!-- Row 4 - TEST -->
+  <circle cx="168" cy="360" r="14" fill="#66BB6A"/>
+  <path d="M161 360L166 365L176 355" fill="none" stroke="#1A1A1A" stroke-width="2.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="196" y="365" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="700" fill="#E0DDD6" letter-spacing="1">TEST</text>
+  <rect x="196" y="373" width="90" height="4" rx="2" fill="#333"/>
+
+  <!-- Row 5 - END -->
+  <circle cx="168" cy="416" r="14" fill="#66BB6A"/>
+  <path d="M161 416L166 421L176 411" fill="none" stroke="#1A1A1A" stroke-width="2.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="196" y="421" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="700" fill="#E0DDD6" letter-spacing="1">END</text>
+  <rect x="196" y="429" width="68" height="4" rx="2" fill="#333"/>
+
+</svg>

package/src/assets/img/sdg-agents-icon-light.svg

@@ -0,0 +1,55 @@
+<svg viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg">
+
+  <!-- Clipboard board - warm flat tone -->
+  <rect x="96" y="72" width="320" height="400" rx="28" fill="#8B6F47"/>
+  <!-- Board inner face -->
+  <rect x="104" y="80" width="304" height="384" rx="24" fill="#A07D52"/>
+
+  <!-- Metal clip - flat silver -->
+  <rect x="186" y="48" width="140" height="56" rx="8" fill="#78909C"/>
+  <rect x="186" y="48" width="140" height="28" rx="8" fill="#90A4AE"/>
+  <!-- Clip hole -->
+  <rect x="218" y="34" width="76" height="36" rx="18" fill="#A07D52"/>
+  <rect x="228" y="42" width="56" height="20" rx="10" fill="#BFA476"/>
+
+  <!-- Paper sheet - crisp white with slight round -->
+  <rect x="124" y="100" width="264" height="352" rx="12" fill="#FFFFFF"/>
+  <!-- Paper fold accent -->
+  <path d="M364 100L388 124L364 124Z" fill="#E8E5DE"/>
+
+  <!-- Title pill badge -->
+  <rect x="152" y="120" width="208" height="32" rx="16" fill="#1D2E3D"/>
+  <text x="256" y="136" text-anchor="middle" dominant-baseline="central" font-family="system-ui, -apple-system, sans-serif" font-size="13" font-weight="700" fill="#D1D5DB" letter-spacing="1.2">SPEC DRIVEN GUIDE</text>
+
+  <!-- Checklist rows -->
+  <!-- Row 1 - SPEC -->
+  <circle cx="168" cy="192" r="14" fill="#34D399"/>
+  <path d="M161 192L166 197L176 187" fill="none" stroke="#fff" stroke-width="2.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="196" y="197" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="700" fill="#37474F" letter-spacing="1">SPEC</text>
+  <rect x="196" y="205" width="80" height="4" rx="2" fill="#E0E0E0"/>
+
+  <!-- Row 2 - PLAN -->
+  <circle cx="168" cy="248" r="14" fill="#34D399"/>
+  <path d="M161 248L166 253L176 243" fill="none" stroke="#fff" stroke-width="2.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="196" y="253" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="700" fill="#37474F" letter-spacing="1">PLAN</text>
+  <rect x="196" y="261" width="100" height="4" rx="2" fill="#E0E0E0"/>
+
+  <!-- Row 3 - CODE -->
+  <circle cx="168" cy="304" r="14" fill="#34D399"/>
+  <path d="M161 304L166 309L176 299" fill="none" stroke="#fff" stroke-width="2.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="196" y="309" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="700" fill="#37474F" letter-spacing="1">CODE</text>
+  <rect x="196" y="317" width="120" height="4" rx="2" fill="#E0E0E0"/>
+
+  <!-- Row 4 - TEST -->
+  <circle cx="168" cy="360" r="14" fill="#34D399"/>
+  <path d="M161 360L166 365L176 355" fill="none" stroke="#fff" stroke-width="2.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="196" y="365" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="700" fill="#37474F" letter-spacing="1">TEST</text>
+  <rect x="196" y="373" width="90" height="4" rx="2" fill="#E0E0E0"/>
+
+  <!-- Row 5 - END -->
+  <circle cx="168" cy="416" r="14" fill="#34D399"/>
+  <path d="M161 416L166 421L176 411" fill="none" stroke="#fff" stroke-width="2.8" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="196" y="421" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="700" fill="#37474F" letter-spacing="1">END</text>
+  <rect x="196" y="429" width="68" height="4" rx="2" fill="#E0E0E0"/>
+
+</svg>

package/src/assets/img/sdg-icon.svg

@@ -0,0 +1,110 @@
+<svg viewBox="0 0 512 560" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <!-- Gradient background -->
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#6C63FF" />
+      <stop offset="50%" stop-color="#48BFE3" />
+      <stop offset="100%" stop-color="#56CFB2" />
+    </linearGradient>
+
+    <!-- Glass fill -->
+    <linearGradient id="glass" x1="0" y1="0" x2="0.3" y2="1">
+      <stop offset="0%" stop-color="#ffffff" stop-opacity="0.35" />
+      <stop offset="100%" stop-color="#ffffff" stop-opacity="0.12" />
+    </linearGradient>
+
+    <!-- Paper glass fill - more opaque -->
+    <linearGradient id="paper" x1="0" y1="0" x2="0.2" y2="1">
+      <stop offset="0%" stop-color="#ffffff" stop-opacity="0.75" />
+      <stop offset="100%" stop-color="#ffffff" stop-opacity="0.5" />
+    </linearGradient>
+
+    <!-- Clip metallic -->
+    <linearGradient id="clip" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#ffffff" stop-opacity="0.6" />
+      <stop offset="100%" stop-color="#ffffff" stop-opacity="0.25" />
+    </linearGradient>
+
+    <!-- Check gradient -->
+    <linearGradient id="chk" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#34D399" />
+      <stop offset="100%" stop-color="#10B981" />
+    </linearGradient>
+
+    <!-- Soft blur for background shapes -->
+    <filter id="blur1">
+      <feGaussianBlur in="SourceGraphic" stdDeviation="40" />
+    </filter>
+    <filter id="blur2">
+      <feGaussianBlur in="SourceGraphic" stdDeviation="30" />
+    </filter>
+
+    <!-- Rounded clip for background -->
+    <clipPath id="bgClip">
+      <rect x="0" y="0" width="512" height="560" rx="0" />
+    </clipPath>
+  </defs>
+
+  <!-- Background -->
+  <rect x="0" y="0" width="512" height="560" fill="#1A1A2E" />
+
+  <!-- Blurred color blobs -->
+  <g clip-path="url(#bgClip)">
+    <circle cx="120" cy="140" r="160" fill="#6C63FF" opacity="0.5" filter="url(#blur1)" />
+    <circle cx="400" cy="420" r="140" fill="#48BFE3" opacity="0.4" filter="url(#blur1)" />
+    <circle cx="360" cy="120" r="100" fill="#56CFB2" opacity="0.35" filter="url(#blur2)" />
+    <circle cx="140" cy="460" r="120" fill="#A78BFA" opacity="0.3" filter="url(#blur2)" />
+  </g>
+
+  <!-- Clipboard board - glass -->
+  <rect x="106" y="82" width="300" height="400" rx="24" fill="url(#glass)" stroke="rgba(255,255,255,0.2)" stroke-width="1.5" />
+
+  <!-- Paper sheet - brighter glass -->
+  <rect x="122" y="118" width="268" height="348" rx="16" fill="url(#paper)" stroke="rgba(255,255,255,0.3)" stroke-width="1" />
+
+  <!-- Clip -->
+  <rect x="206" y="62" width="100" height="44" rx="10" fill="url(#clip)" stroke="rgba(255,255,255,0.35)" stroke-width="1.2" />
+  <rect x="228" y="52" width="56" height="26" rx="13" fill="rgba(255,255,255,0.15)" stroke="rgba(255,255,255,0.4)" stroke-width="1.2" />
+
+  <!-- Title -->
+  <text x="256" y="162" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="15" font-weight="600" fill="rgba(255,255,255,0.9)" letter-spacing="2">SPEC DRIVEN GUIDE</text>
+
+  <!-- Thin separator -->
+  <line x1="160" y1="178" x2="352" y2="178" stroke="rgba(255,255,255,0.2)" stroke-width="1" stroke-linecap="round" />
+
+  <!-- Row 1 - SPEC -->
+  <g>
+    <rect x="152" y="200" width="24" height="24" rx="7" fill="url(#chk)" opacity="0.9" />
+    <path d="M158 212L164 218L172 206" fill="none" stroke="#fff" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" />
+    <text x="192" y="217" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="500" fill="rgba(255,255,255,0.85)" letter-spacing="2">SPEC</text>
+  </g>
+
+  <!-- Row 2 - PLAN -->
+  <g>
+    <rect x="152" y="248" width="24" height="24" rx="7" fill="url(#chk)" opacity="0.9" />
+    <path d="M158 260L164 266L172 254" fill="none" stroke="#fff" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" />
+    <text x="192" y="265" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="500" fill="rgba(255,255,255,0.85)" letter-spacing="2">PLAN</text>
+  </g>
+
+  <!-- Row 3 - CODE -->
+  <g>
+    <rect x="152" y="296" width="24" height="24" rx="7" fill="url(#chk)" opacity="0.9" />
+    <path d="M158 308L164 314L172 302" fill="none" stroke="#fff" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" />
+    <text x="192" y="313" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="500" fill="rgba(255,255,255,0.85)" letter-spacing="2">CODE</text>
+  </g>
+
+  <!-- Row 4 - TEST -->
+  <g>
+    <rect x="152" y="344" width="24" height="24" rx="7" fill="url(#chk)" opacity="0.9" />
+    <path d="M158 356L164 362L172 350" fill="none" stroke="#fff" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" />
+    <text x="192" y="361" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="500" fill="rgba(255,255,255,0.85)" letter-spacing="2">TEST</text>
+  </g>
+
+  <!-- Row 5 - END -->
+  <g>
+    <rect x="152" y="392" width="24" height="24" rx="7" fill="url(#chk)" opacity="0.9" />
+    <path d="M158 404L164 410L172 398" fill="none" stroke="#fff" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" />
+    <text x="192" y="409" font-family="system-ui, -apple-system, sans-serif" font-size="16" font-weight="500" fill="rgba(255,255,255,0.85)" letter-spacing="2">END</text>
+  </g>
+
+</svg>

package/src/assets/instructions/commands/sdg-docs.md

@@ -0,0 +1,69 @@
+# Technical Documentation — Context Preparation
+
+Executing documentation for: $ARGUMENTS. This command prepares the context for the **Docs Cycle**.
+
+## Step 0 — Document Classification
+
+1. **Context Check**: Identify the document type needed based on the goal:
+   - **CHANGELOG**: Release entry or version synchronization → `CHANGELOG.md` at project root.
+   - **FEAT (Especificação da Funcionalidade)**: Document _what_ was built and _how_ it fits the pipeline → `docs/specs/FEAT-NNN-slug.md`.
+   - **ADR (Architecture Decision Record)**: Document _why_ a technical path was chosen (trade-offs) → `docs/decisions/ADR-NNN-slug.md`.
+2. **Numbering**: Use sequential zero-padded numbers (`ADR-001`, `FEAT-042`). Check existing files to find the next available number.
+3. **Current Alignment**: Read existing files in the target directory to maintain style and numbering consistency.
+
+---
+
+## Phase: SPEC (Draft Specialization)
+
+Follow the **Phase: SPEC** from the **Working Protocol**, using these templates for the "Drafting" logic:
+
+### Template A: CHANGELOG (Keep a Changelog)
+
+```md
+## [vX.Y.Z] - YYYY-MM-DD
+
+### Added | Changed | Fixed | Removed
+
+- [Brief entries from Unreleased]
+```
+
+### Template B: FEAT (Especificação da Funcionalidade)
+
+```md
+# FEAT-[NNN]: [Feature Name]
+
+## Status: Draft | Review | Approved
+
+## Goal / Context / Solution / Verification
+```
+
+### Template C: ADR (Architecture Decision Record)
+
+```md
+# ADR-[NNN]: [Decision Title]
+
+## Context (Why) / Decision (What) / Consequences (Impact)
+```
+
+---
+
+---
+
+## Phase: END (Hardened)
+
+Follow the **Phase: END** from the **Working Protocol**. Documentation must be accurate and mirror the code state perfectly. Sync the backlog and **WAIT** for authorization before `commit`/`push`.
+
+---
+
+> [!TIP]
+> **Multi-Agent Optimization (Claude Code only)**
+>
+> The Docs Cycle is entirely analytical — there is no CODE phase, so Fast is never invoked. All phases run under the **Planning** role.
+>
+> | Phase      | Role         | Why                                                       |
+> | :--------- | :----------- | :-------------------------------------------------------- |
+> | SPEC + END | **Planning** | Document classification, structure review, accuracy check |
+>
+> Planning's strength here is accuracy and coherence: cross-referencing code state, CHANGELOG history, and ADR decisions before committing any documentation artifact.
+>
+> Read `.ai/instructions/core/agent-roles.md` for the full protocol.

package/src/assets/instructions/commands/sdg-feat.md

@@ -0,0 +1,45 @@
+# Feature Execution — Context Preparation
+
+We are initializing a new feature: $ARGUMENTS. This command prepares the context for the development lifecycle following the **Working Protocol**.
+
+## Step 0 — Context Preparation
+
+1. **Roadmap Check**: If `ROADMAP.md` exists, read it to identify where this feature fits in the project's long-term vision.
+2. **Domain Scope**:
+   - **Backend** (API/Domain/DB) → read `.ai/instructions/competencies/backend.md`
+   - **Frontend** (UI/UX) → read `.ai/instructions/competencies/frontend.md`
+   - **Fullstack** → read both
+3. **Architecture Standards**: If `.ai/instructions/flavor/principles.md` exists, read the established data pipeline (Vertical Slice, MVC, etc.).
+4. **Code Style Load** (mandatory — do not skip):
+   - **Engineering Standards** → read `.ai/instructions/core/engineering-standards.md`
+   - **Code Style & NarrativeCascade** → read `.ai/instructions/core/code-style.md`
+5. **Quality & Debugging**:
+   - **Testing Strategy** → read `.ai/instructions/core/testing-principles.md`
+   - **Observability** → read `.ai/instructions/core/observability.md`
+
+---
+
+## Phase: SPEC (Especificação da Funcionalidade)
+
+Follow the **Phase: SPEC** from the **Working Protocol**, with these mandatory additions:
+
+- **Domain Modeling**: Explicitly define the primary entities and aggregate roots involved.
+- **Configuration Contract**: Define the environment variables required for this feature (keys must be **abstract**; pro-tip: `AUTH_SECRET` over `CLERK_SECRET`).
+- **Contract-First**: Define the Public Interface (API endpoints, public methods, or Component Props) before listing implementation steps.
+- **Storytelling**: The SPEC must describe the "User Journey" or the "Data Life Cycle".
+- **Backend SPEC (mandatory addition)**: If the domain includes API work, define the response contract before listing implementation steps:
+  - Use the Contract template from `backend.md`'s ContractFirst rule
+  - Define: endpoint method + path, input fields with types, output shape (envelope fields), and all error codes with conditions
+  - This contract must appear in the SPEC and be approved before PLAN begins
+- **Frontend SPEC (mandatory addition)**: If the domain includes UI work, define the section structure before any code:
+  - List each section by type (`section.hero`, `section.cards`, `section.form`, etc.)
+  - Define the layout skeleton: grid columns, main content blocks, and their data sources
+  - Identify which states must be handled: Loading / Empty / Error
+  - This wireframe contract must appear in the SPEC and be approved before PLAN begins
+- **Testing SPEC (mandatory addition)**: Explicitly define at least three scenarios: One Happy Path, one Edge Case, and one Expected Failure.
+  - Format as: `Scenario [Name] (Input: { ... }) -> Expected: [Result/State]`
+  - This testing contract must appear in the SPEC and be approved before PLAN begins
+
+---
+
+> Read `.ai/instructions/core/agent-roles.md` for the multi-agent handoff protocol (Planning + Fast roles).

package/src/assets/instructions/commands/sdg-fix.md

@@ -0,0 +1,41 @@
+# Incident Correction — Context Preparation
+
+We are correcting a recorded incident: $ARGUMENTS. This command prepares the context for the **Fix Cycle** defined in the **Working Protocol**.
+
+## Step 0 — Incident Analysis
+
+1. **Reproduction Scenario**: Read existing logs or provided data to define the exact steps to reproduce the issue.
+2. **Domain Scope**:
+   - **Backend** (Logic/Data) → read `.ai/instructions/competencies/backend.md`
+   - **Frontend** (UI/UX) → read `.ai/instructions/competencies/frontend.md`
+   - **Fullstack** → read both
+3. **Architecture Standards**: If `.ai/instructions/flavor/principles.md` exists, read the architectural principles.
+4. **Code Style & Standards** (mandatory):
+   - **Engineering Standards** → read `.ai/instructions/core/engineering-standards.md`
+   - **Code Style & Narrative Scansion** → read `.ai/instructions/core/code-style.md`
+5. **Diagnostic Standards**:
+   - **Testing Principles** → read `.ai/instructions/core/testing-principles.md`
+   - **Observability** → read `.ai/instructions/core/observability.md`
+
+---
+
+## Phase: SPEC (Fix Specialization)
+
+Follow the **Phase: SPEC** from the **Working Protocol**, with these mandatory additions:
+
+- **Root Cause Analysis (RCA)**: Explicitly identify the layer, file, and line where the contract or logic breaks.
+- **Observed vs Expected**: Contrast the current broken behavior with the desired outcome.
+- **Minimal Surface**: Ensure the proposed fix targets ONLY the bug. No refactors allowed in this cycle.
+- **Configuration Contract**: If this fix introduces or changes any environment variable, list it here with its abstract key and purpose. Keys must hide vendor/infrastructure details (e.g., `AUTH_PROVIDER_SECRET` over `CLERK_SECRET`). No committed templates.
+
+---
+
+## Phase: PLAN (Regression Focus)
+
+Follow the **Phase: PLAN** from the **Working Protocol**, with this mandatory addition:
+
+- **Regression Test**: Include a task specifically for a test that reproduces the bug (Characterization Test). Use the patterns from `testing-principles.md`. This task must appear in the PLAN before approval.
+
+---
+
+> Read `.ai/instructions/core/agent-roles.md` for the multi-agent handoff protocol (Planning + Fast roles).