Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[1.1.0] — 2026-04-15

Summary

Version 1.1 introduces a complete architectural overhaul of the frontend SDD (Specification-Driven Development) pipeline. The core shift moves from narrative-based User Stories to formally executable Task Contracts, replacing free-text agent communication with structured, schema-validated envelopes. The update also delivers a hardened frontend design system aligned with Tailwind v4, a new validation skill, and an 8-layer automated test suite covering all artifact types.

Added

SDD Artifacts

feature.spec.md template — replaces screen.md; prescriptive 9-section structure:
- §1 Metadata (epic, personas, task_contracts, status)
- §2 UI States — locked table with UI-NN identifiers
- §3 Transitions — locked table with FL-NN identifiers and guard conditions
- §4 Props Contract
- §5 Validations
- §6 Error Mapping (error.code → state → user message)
- §7 Component Dependencies (references to component.spec.md)
- §8 Accessibility (WCAG 2.1 AA)
- §9 BDD Scenarios — locked, must cover all states declared in §2
component.spec.md template — formal contract for reusable components:
- §1 Purpose and Responsibilities
- §2 When to Use / When Not to Use
- §3 Props Contract (type, default, required) + §3.1 Data Contract
- §4 Component States (idle + named states with transition parameters)
- §5 Events Emitted (payload type, trigger, consumer action)
- §6 Variants and Compositions
- §7 Do / Don't
- §8 BDD Scenarios (minimum 3: default render, error state, keyboard navigation)
- §9 Accessibility Contract (label, keyboard, focus management, ARIA states)
- §10 Internal Dependencies
decisions.md template — session-scoped decision log for architectural trade-offs

Skills

/u-fe-validate — standalone frontend validation skill:
- Input: TARGET (file glob), SPECS_DIR (design system path), RULES subset
- Detects 72 rules across two categories:
  - Code Quality: xss-dangerous-html, inline-css, design-token, transition-all, error-boundary-missing, animation-no-reduced-motion, todo-no-ref, i18n-hardcode, commented-out-code, no-code-splitting, and others
  - Visual Design: typography, color, layout, motion, and CSS pattern violations
- Output: fe-validate-{run_id}.yaml with structured findings (severity: critical / high / medium / low) and verdict (approved / approved_with_caveats / rejected)
- Behavior configurable via design_system block in CLAUDE.md
/u-fe-review — ad-hoc frontend audit skill with --fix mode
/u-ui-design — design amplification tool; introduces anti-patterns.md (337 lines) as the single source of truth for visual violations, referenced by /u-fe-validate findings

YAML Schemas (13 new files in `dist/skills/u-shared-templates/`)

Schema	Purpose
`task_contract.schema.yaml`	Formal Task Contract + execution_contract structure
`fe-validate-report.schema.yaml`	Findings + verdict for `/u-fe-validate` output
`handoff-manifest.schema.yaml`	Cross-team / cross-agent handoff versioning
`component-spec-gate-report.schema.yaml`	Props Contract validation gate
`design-system-gate-report.schema.yaml`	Token + rule compliance gate
`ui-agent-output.schema.yaml`	UI Agent output with `ui_nn_covered` + `bdd_scenarios_covered` metrics
`cr.schema.yaml`	Change Request (types: `spec_gap` / `spec_error` / `infeasibility` / `design_conflict`)
`blocked-report.schema.yaml`	Formal blocked state (`reason: missing_input / dependency / infeasibility`)
`architecture-finding.schema.yaml`	DI / DTO / pagination pattern findings
`security-finding.schema.yaml`	Vulnerability classification
`compliance-finding.schema.yaml`	Governance and audit trail findings
`validation-result.schema.yaml`	Layer-wise validation result envelope
`be-to-fe-handoff.schema.yaml`	Backend-to-frontend handoff contract (API contract + status)

All schemas include parallel .yaml example files.

Design System Rules (R1–R25)

25 hard constraints replacing the previous informal guidelines:

Rule	Constraint
R1	Spacing: only 4/8/12/16/24/32/48/64px; forbidden: 5, 7, 9, 11
R2	Form gaps: label→input `gap-1.5`; input→helper `gap-1`; field→field `gap-4`
R3	Card padding: compact `p-2`, small `p-3`, medium `p-4`, large `p-6`, XL `p-8`
R4	Type scale: 12/14/16/20/24/30px only; max 3 sizes per component
R5	Line-height: headings `leading-tight`; body `leading-relaxed`; caption `leading-snug`
R6	Font weight: headings `font-medium/semibold`; body `font-normal`; metrics `font-bold`
R7	Text hierarchy: opacity only (100%/60%/40%); never hue-based
R8	Contrast: 4.5:1 normal text; 3:1 large/interactive (WCAG AA)
R9	60-30-10: accent only on CTAs; forbidden on headings, dividers, and icons
R10	Aspect ratios: 1:1 / 4:3 / 16:9 / golden ratio only
R11	Touch targets: `h-8` (32px) desktop; `h-11` (44px) mobile minimum
R12	Alignment: every element shares an axis with at least one other
R13	Border radius: ONE style globally (Rounded / Neutral / Sharp); mixing is forbidden
R14	Button hierarchy: max 1 primary button per context; danger = irreversible only
R15	5 interactive states required: Default / Hover / Focus / Active / Disabled
R16	Input validation: Error/Success with helper text; never border-only feedback
R17	Table density: `py-2` compact / `py-3` default / `py-4` relaxed; one per table
R18	Card grid: `auto-fill minmax`; gap-4 or gap-6 only; no fixed columns
R19	Loading feedback: <100ms nothing; 100–1000ms spinner; >1000ms skeleton
R20	Error messages: icon + title + description + action; no codes or stack traces
R21	Icons: 14/16/20/24px only; max 24px for functional icons
R22	Avatars: 24/32/40/48/64/80px only; 1:1 ratio enforced
R23	Animations: 100/200/300/500ms only; max 2 properties; `ease-out` enter / `ease-in` exit
R24	Z-index: only 0/10/20/30/40/50; forbidden: 99, 100, 9999
R25	Empty states: icon + title + description + action; must be defined before implementation

Tooling

install.sh — differential sync script (dist/ → {project}/.claude/): copies new files, updates modified, removes obsolete; non-invasive to unmanaged files

Changed

Task Contracts — replacing User Stories

All agent-to-agent communication now uses the Task Contract model. User Stories are no longer valid execution units.

The task_contract block defines task metadata (id, type, scope, estimate, dependencies), and the execution_contract block defines the execution specification (exec_type, input references, constraints, output schema, validation criteria, fallback behavior).

exec_type enum: code_generation / bug_fix / refactoring / visual_adjustment / spec_writing

Agent: `u-fe-ui.md`

Consumes §2 (UI States) + §3 (Transitions) + §7 (Component Dependencies) from feature.spec.md
Must verify that all §2 states are covered by §9 BDD scenarios before emitting output

Emits ui-spec-gate YAML block at top of output:

ready_for_development: true
ui_nn_covered: [UI-01, UI-02, UI-03, UI-04]
bdd_scenarios_covered: [S-01, S-02, S-03]

Developer agent is gated until ready_for_development: true

Agent: `u-fe-developer.md`

Requires execution_contract to proceed; emits blocked-report.yaml if missing
Pre-flight gates before implementation:
- Gate 1: All components in §7 must have a .component.spec.md available
- Gate 2: Design system tokens must be available at configured path
Validates Props Contract implementation against component.spec.md §2
Emits CR (type: spec_gap) when a gap is found in the specification
Records inference_log for all assumptions made during implementation

Agent: `u-fe-orchestrator-core.md`

Context mounting now loads feature.spec.md instead of screen.md
Routing is deterministic via exec_type (no interpretation required)
Extracts design_system config block from CLAUDE.md

Agent: `u-be-developer.md`

Added DI / DTO / pagination pattern validation (+357 lines)

Agent: `u-fe-planner.md`

Epic decomposition now produces Task Contracts (not User Stories)
Generates feature.spec.md stubs with §1 pre-filled

Design System: Tailwind v4 Token Naming

All design system tokens migrated to Tailwind v4 @theme naming convention:

/* Before */
--bg-primary: oklch(...);

/* After */
@theme {
  --color-primary: oklch(...);  /* → bg-primary, text-primary, border-primary */
  --spacing-lg: 16px;           /* → p-lg, m-lg, gap-lg */
  --duration-base: 350ms;       /* → duration-base */
}

Inline styles using var(--token) are now a code quality violation (rule: inline-css). Tailwind utility classes are mandatory.

Motion tokens added: --duration-* and --ease-*, with mandatory @media (prefers-reduced-motion) support.

Design System Templates

tokens.md — +130 lines: OKLCH color space as canonical (with hex comments), motion tokens, semantic usage rules (§8)
components.md — +28 lines
composition.md — +26 lines
implementation.md — +91 lines: Tailwind v4 integration guide
_index.md — +47 lines

Skill: `/u-improve`

Narrative improvement log replaced by structured improve_scope YAML block
Layer 8 tests validate that improve_scope.affected_specs matches the actual diff

Documentation

docs-en/05-flows/existent-repo.md — onboarding guide for existing codebases (+154 lines)
docs-en/04-teams/dev/developer.md — Task Contract terminology update
docs-en/08-artifacts/templates.md — complete artifact catalog (+219 lines)
38 documents updated: "User Story" → "Task Contract"

Removed

TEMPLATE.screen.md — deprecated; replaced by feature.spec.md
All references to "User Story" terminology in agent and skill definitions

Breaking Changes

#	Before (v1.0)	After (v1.1)
1	`screen.md` (descriptive layout)	`feature.spec.md` (§1–§9 prescriptive structure)
2	User Story (narrative)	Task Contract (formal execution model)
3	`style={{ color: 'var(--token)' }}`	`className="text-primary"` (Tailwind utility)
4	Generic token naming	Tailwind v4 `@theme` naming convention
5	Narrative improve log (`improve##.md`)	`improve_scope` YAML block

Agent-to-Agent Flow (v1.1)

Planner
  └─ Produces: TC-XX + feature.spec.md (§1–§9)

UI Agent
  ├─ Reads: §2 UI States, §3 Transitions, §7 Component Dependencies
  ├─ Produces: ui-epic-XX.md
  └─ Emits: ui-spec-gate { ready_for_development: true }

Developer Agent
  ├─ Pre-flight gates: component specs, design system
  ├─ Reads: feature.spec.md §2–§7 + ui-epic-XX.md
  ├─ Implements and tests against §9 BDD scenarios
  ├─ Validates tokens vs design-system/tokens.md
  └─ Emits: inference_log + CR on spec gaps

QA Agent
  ├─ Validates §9 BDD scenarios as executable tests
  ├─ Runs: /u-fe-validate
  └─ Emits: fe-validate-report.yaml

Metrics

Category	v1.0	v1.1	Delta
Skills	18	24	+6
Agents	18	18	refactored
SDD Templates	8	13	+5
YAML Schemas	0	13	+13
Documented rules	~40	150+	+110
Content lines	~80k	~118k	+47%

[1.0.0] — 2026-04-08

Initial release of Siegard-Code — the AI-first agent infrastructure framework.

Included:

Frontend SDD pipeline (Planner → UI → Developer → QA)
Backend SDD pipeline
Base design system templates
Core skills: /u-planning, /u-spec, /u-improve, /u-dev
Agent definitions: u-fe-orchestrator, u-fe-planner, u-fe-ui, u-fe-developer, u-fe-qa-docs
Documentation structure (docs-en/)

Navigation Menu

Siegard Code v1.1.0 - New Frontend SDD Pipeline

Choose a tag to compare

Sorry, something went wrong.

Sorry, something went wrong.

Uh oh!

No results found

Changelog

[1.1.0] — 2026-04-15

Summary

Added

SDD Artifacts

Skills

YAML Schemas (13 new files in `dist/skills/u-shared-templates/`)

Design System Rules (R1–R25)

Tooling

Changed

Task Contracts — replacing User Stories

Agent: `u-fe-ui.md`

Agent: `u-fe-developer.md`

Agent: `u-fe-orchestrator-core.md`

Agent: `u-be-developer.md`

Agent: `u-fe-planner.md`

Design System: Tailwind v4 Token Naming

Design System Templates

Skill: `/u-improve`

Documentation

Removed

Breaking Changes

Agent-to-Agent Flow (v1.1)

Metrics

[1.0.0] — 2026-04-08

Uh oh!

Siegard Code v1.1.0 - New Frontend SDD Pipeline

Changelog

[1.1.0] — 2026-04-15

Summary

Added

SDD Artifacts

Skills

YAML Schemas (13 new files in dist/skills/u-shared-templates/)

Design System Rules (R1–R25)

Tooling

Changed

Task Contracts — replacing User Stories

Agent: u-fe-ui.md

Agent: u-fe-developer.md

Agent: u-fe-orchestrator-core.md

Agent: u-be-developer.md

Agent: u-fe-planner.md

Design System: Tailwind v4 Token Naming

Design System Templates

Skill: /u-improve

Documentation

Removed

Breaking Changes

Agent-to-Agent Flow (v1.1)

Metrics

[1.0.0] — 2026-04-08

Uh oh!

YAML Schemas (13 new files in `dist/skills/u-shared-templates/`)

Agent: `u-fe-ui.md`

Agent: `u-fe-developer.md`

Agent: `u-fe-orchestrator-core.md`

Agent: `u-be-developer.md`

Agent: `u-fe-planner.md`

Skill: `/u-improve`