flyee 0.1.0

package/core/workflows/ds-references.md

@@ -0,0 +1,197 @@
+---
+description:  Register, validate, and govern ALL visual references used to derive Design System tokens.  This workflow is the ONLY authorized entry point for visual reference material.
+---
+
+## Hard Preconditions (Abort if any fail)
+
+1. `.agent/state/project.json` exists
+2. `project.stage === "development"`
+3. `design_system.status === "initialized"`
+
+If any condition fails, abort with:
+
+```text
+/ds-references aborted: Design System not initialized or project not ready.
+````
+
+---
+
+## Accepted Reference Types
+
+Users MUST provide at least ONE of the following:
+
+### Visual Files
+
+* `.png`
+* `.jpg`
+* `.jpeg`
+* `.webp`
+
+### Documents
+
+* `.pdf`
+
+### Design Sources (links)
+
+* Figma
+* FigJam
+* Dribbble
+* Behance
+* Internal design docs
+
+🚫 Forbidden:
+
+* Verbal descriptions only
+* “Do something modern”
+* Pure inspiration without intent
+
+---
+
+## Execution Steps
+
+### 1️⃣ Reference Intake (Mandatory)
+
+Request explicitly from the user:
+
+* Upload files OR
+* Provide links
+
+If no references are provided:
+
+```text
+/ds-references blocked: Visual references are required.
+```
+
+---
+
+### 2️⃣ Reference Validation
+
+For each reference:
+
+* Check file integrity
+* Identify reference type (UI, branding, inspiration)
+* Ensure visual relevance to product domain
+
+🚫 Abort if:
+
+* Files are corrupted
+* Content is not visual
+* References are unrelated to UI / branding
+
+---
+
+### 3️⃣ Canonical Storage (Mandatory)
+
+Store all references in:
+
+```
+src/design-system/references/
+├── primary/
+├── secondary/
+└── inspiration/
+```
+
+Rules:
+
+* No references outside this directory
+* Filenames must be immutable
+* References are append-only
+
+---
+
+### 4️⃣ Project State Update (Critical)
+
+Update `.agent/state/project.json`:
+
+```json
+"design_system": {
+  "references": "present",
+  "reference_count": 5,
+  "last_reference_update": "ISO_TIMESTAMP",
+  "tokens": "outdated",
+  "token_origin": "visual_reference",
+  "validated": false
+}
+```
+
+📌 Important:
+
+* Any new reference INVALIDATES existing tokens
+* Validation is automatically revoked
+
+---
+
+### 5️⃣ Artifact Registration
+
+Append:
+
+```json
+"artifacts": {
+  "documents": ["Visual references registered"],
+  "prompts": ["/ds-references"]
+}
+```
+
+---
+
+## Postconditions (Guaranteed)
+
+After successful execution:
+
+* References are safely stored
+* Token system is marked OUTDATED
+* UI generation is BLOCKED
+* Next mandatory action is `/ds-tokens`
+
+---
+
+## Standard Output
+
+```text
+Visual References: REGISTERED
+Total References: 5
+Token Status: OUTDATED
+Validation: REVOKED
+Next Required Action: /ds-tokens
+```
+
+---
+
+## Golden Rules (Hard Law)
+
+* No references → No tokens
+* New references → Tokens invalidated
+* Tokens without references → Illegal
+* References are immutable evidence
+
+---
+
+## `/next-step` Integration (Mandatory)
+
+`/next-step` MUST interpret:
+
+```text
+design_system.references === "present"
+AND design_system.tokens === "outdated"
+```
+
+As:
+
+```text
+BLOCK UI
+NEXT ACTION: /ds-tokens
+```
+
+And:
+
+```text
+design_system.references !== "present"
+```
+
+As:
+
+```text
+BLOCK ALL
+NEXT ACTION: /ds-references
+```
+

package/core/workflows/ds-styleguide.md

@@ -0,0 +1,237 @@
+---
+description: Generate or update the in-app Design System styleguide.
+---
+
+Generate and maintain a **single, authoritative Style Guide** for the Design System, intended for:
+
+* Developers
+* Designers
+* Product teams
+* External consumers (when applicable)
+
+This workflow **documents only validated artifacts**.
+It **MUST NEVER invent, infer, or modify** Design System decisions.
+
+---
+
+## Hard Preconditions (Abort if any fail)
+
+The workflow **MUST NOT RUN** unless:
+
+1. `.agent/state/project.json` exists
+2. `design_system.validated === true`
+3. `design_system.status === "validated"`
+4. Token artifacts exist:
+
+   ```
+   src/design-system/tokens/
+   ```
+5. Validation reports exist:
+
+   ```
+   src/design-system/validation/ds-validation-report.*
+   ```
+
+If any condition fails, abort with:
+
+```text
+/ds-styleguide aborted: Design System not validated.
+```
+
+---
+
+## Output Location (Mandatory)
+
+```
+src/design-system/styleguide/
+├── index.md
+├── foundations/
+│   ├── colors.md
+│   ├── typography.md
+│   ├── spacing.md
+│   ├── radius.md
+│   └── shadows.md
+├── themes/
+│   ├── light.md
+│   └── dark.md
+├── components/
+│   └── README.md
+├── governance.md
+└── changelog.md
+```
+
+---
+
+## Execution Phases
+
+---
+
+### 1️⃣ Load Validated Sources (Read-Only)
+
+Consume data from:
+
+* `src/design-system/tokens/*`
+* `globals.css` / `tokens.css`
+* Component specifications (if any)
+* `ds-validation-report.json`
+* `.agent/state/project.json`
+
+🚫 Any attempt to modify artifacts = **ABORT**
+
+---
+
+### 2️⃣ Foundations Documentation
+
+#### Colors (`foundations/colors.md`)
+
+Document:
+
+* Brand colors
+* Neutral palette
+* Semantic colors
+* Surface & background usage
+* Accessibility notes
+
+Include:
+
+* Token name
+* Description
+* Usage guidance
+* Do / Don’t rules
+
+🚫 Never document raw hex values as primary reference
+Tokens are the authority.
+
+---
+
+#### Typography (`foundations/typography.md`)
+
+Document:
+
+* Font families
+* Heading scale
+* Body text scale
+* Line heights
+* Usage hierarchy
+
+---
+
+#### Spacing, Radius, Shadows
+
+For each:
+
+* Token list
+* Scale rationale
+* Intended usage
+* Anti-patterns
+
+---
+
+### 3️⃣ Theme Documentation
+
+#### Light & Dark Themes
+
+For each theme:
+
+* Token mappings
+* Surface hierarchy
+* Interaction behavior
+* Accessibility guarantees
+
+---
+
+### 4️⃣ Component Documentation (Conditional)
+
+If `design_system.components === "ready"`:
+
+For **each component**, document:
+
+* Purpose
+* Variants
+* States
+* Token dependencies
+* Accessibility notes
+
+🚫 No CSS, JSX, or implementation code
+This is **conceptual + spec-level documentation**
+
+---
+
+### 5️⃣ Governance Documentation (`governance.md`)
+
+Document **non-negotiable rules**:
+
+* Tokens are mandatory
+* No local visual definitions
+* Validation is required before UI generation
+* Locked decisions policy
+* Change protocol
+
+This section is **contractual**, not advisory.
+
+---
+
+### 6️⃣ Changelog Generation (`changelog.md`)
+
+Append:
+
+* Date
+* Validation version
+* Summary of validated artifacts
+* Reference to last validation report
+
+🚫 No speculative future entries
+
+---
+
+### 7️⃣ Project State Update (Minimal)
+
+Update **only**:
+
+```json
+"design_system": {
+  "styleguide": "ready"
+}
+```
+
+🚫 No other state mutation allowed
+
+---
+
+## Standard Output Message (Mandatory)
+
+```text
+Design System Styleguide: GENERATED
+Status: Read-only
+Validated Source: YES
+Consumption Ready: YES
+```
+
+---
+
+## Hard Rules (Immutable)
+
+* Styleguide documents reality — never creates it
+* Tokens > Components > Documentation
+* No validation → No styleguide
+* No styleguide → External usage forbidden
+
+---
+
+## `/next-step` Integration
+
+`/next-step` MAY:
+
+* Recommend `/ds-styleguide` **only after validation**
+* Never block execution if styleguide is missing
+* Never treat styleguide as a prerequisite for UI generation
+
+---
+
+## Anti-Patterns (Explicitly Forbidden)
+
+* Redefining tokens in docs
+* Showing raw values as authoritative
+* Documenting unvalidated components
+* Mixing implementation code with documentation
+

package/core/workflows/ds-token-diff.md

@@ -0,0 +1,103 @@
+---
+description: Analyze differences between token versions and detect semantic and visual impact.
+---
+
+## Preconditions
+
+1. Previous token snapshot exists
+2. New token generation has occurred
+
+---
+
+## Execution Steps
+
+### 1️⃣ Load Token Snapshots
+
+Compare:
+- Previous version
+- Current version
+
+---
+
+### 2️⃣ Diff Classification
+
+Classify each change as:
+
+- 🟢 Additive (new token)
+- 🟡 Mutative (value changed)
+- 🔴 Breaking (semantic meaning changed or removed)
+
+---
+
+### 3️⃣ Impact Analysis
+
+For each changed token:
+
+- Identify consumers (components, themes)
+- Identify visual domains affected:
+  - Buttons
+  - Text
+  - Surfaces
+  - Layout
+
+---
+
+### 4️⃣ Severity Scoring
+
+Assign impact level:
+
+- LOW → Safe
+- MEDIUM → Review required
+- HIGH → Validation reset required
+
+---
+
+### 5️⃣ Report Generation
+
+Generate:
+
+```
+
+src/design-system/validation/
+├── token-diff-report.json
+└── token-diff-report.md
+
+````
+
+---
+
+## Output Example
+
+```text
+Token Diff Analysis: COMPLETED
+Changed Tokens: 6
+Breaking Changes: 2
+High Impact Tokens: 1
+Validation Status: REVOKED
+Next Action: /ds-validate
+````
+
+````
+
+---
+
+### 4️⃣ **Integração com `/ds-tokens` (Obrigatória)**
+
+Após gerar tokens:
+
+- Executar automaticamente `/ds-token-diff`
+- Se impacto ≠ LOW:
+  - `design_system.validated = false`
+  - UI continua BLOQUEADA
+
+---
+
+### 5️⃣ **Atualização do Project State**
+
+```json
+"design_system": {
+  "token_lineage": "enabled",
+  "last_token_diff": "ISO_TIMESTAMP",
+  "last_token_impact": "high"
+}
+````