flyee 0.1.0

package/core/workflows/init-project.md

@@ -0,0 +1,386 @@
+---
+description: Initialize local project state and configuration (idempotent)
+---
+
+1. Check if `.agent/state/project.json` exists.
+
+2. If it exists:
+   - Do NOT recreate files or directories.
+   - Inform that the project has already been initialized.
+   - Explain that the project can be continued using `/next-step`.
+   - Stop execution.
+
+3. If it does NOT exist:
+   - Create directory `.agent/state/`.
+   - Create directory `.agent/rules/`.
+   - Create directory `.agent/workflows/`.
+
+4. Create `.agent/state/project.json` with the following default structure:
+   {
+     "project": {
+       "name": "",
+       "domain": "",
+       "type": ""
+     },
+     "intent": {
+       "primary": "",
+       "secondary": [],
+       "success_criteria": []
+     },
+     "stage": "discovery",
+     "constraints": {
+       "technical": [],
+       "business": [],
+       "legal": [],
+       "time": [],
+       "budget": []
+     },
+     "decisions": {
+       "architecture": {},
+       "stack": {},
+       "patterns": [],
+       "assumptions": []
+     },
+     "design_system": {
+       "status": "not_initialized",
+       "tokens": "missing" | "scaffold_only" | "ready" | "outdated",
+       "token_origin": "none",
+       "components": "missing",
+       "styleguide": "missing",
+       "validated": false,
+       "last_validation": null
+     },
+     "ux_mobile": "not_evaluated",
+     "artifacts": {
+       "documents": [],
+       "code": [],
+       "prompts": []
+     },
+     "open_items": {
+       "tasks": [],
+       "questions": [],
+       "risks": []
+     },
+     "control": {
+       "locked_fields": [],
+       "confidence_level": "low"
+     }
+   }
+
+5. Create `.agent/rules/project.rules.md` with:
+# Project Governance Rules
+
+## Mandatory Rules
+
+- The project state file `.agent/state/project.json` is the single source of truth
+- No rule, workflow, or output may violate declared constraints
+- Decisions recorded in the `decisions` block are LOCKED by default
+- Locked decisions may only be changed by explicit user instruction
+
+### Component Authority Rules (Hard Law)
+
+- UI components MUST be created exclusively through the `/ds-components` workflow
+- Direct creation or modification of UI components outside `/ds-components` is forbidden
+- Any component detected without `/ds-components` authorization is considered INVALID
+- Invalid components MUST be refactored or removed immediately
+
+
+## Design System Rules (Critical)
+
+- No UI code may be generated before `/ds-init` is completed
+- No visual component may be created without Design Tokens
+- No feature is considered complete if `/ds-validate` returns FAIL
+- Design System decisions are locked after successful validation
+- No UI component, page or layout may be generated unless `design_system.validated === true`
+
+### Governance Violations
+
+Any of the following constitutes a GOVERNANCE VIOLATION:
+
+- Generating UI before `/ds-validate`
+- Creating components outside `/ds-components`
+- Defining visual styles locally (colors, spacing, typography)
+- Bypassing locked Design System decisions
+
+Governance violations MUST:
+- Block all downstream workflows
+- Be reported explicitly
+- Be resolved before any continuation
+
+
+### Component Authority Rules (Hard Law)
+
+- UI components MUST be created exclusively through the `/ds-components` workflow
+- Direct creation or modification of UI components outside `/ds-components` is forbidden
+- Any component detected without `/ds-components` authorization is considered INVALID
+- Invalid components MUST be refactored or removed immediately
+
+## Design System Refactor Rules (Recovery Mode)
+
+- /ds-refactor is the ONLY authorized workflow to fix Design System violations
+  caused by hardcoded styles or token bypass
+
+- /ds-refactor MAY be executed ONLY IF:
+  - design_system.initialized === true
+  - design_system.tokens === "ready"
+  - design_system.validated === false
+  - Violations are classified as refactorable
+
+- /ds-refactor MUST NOT:
+  - Change visual appearance
+  - Alter spacing, layout, hierarchy or semantics
+  - Introduce new tokens
+  - Modify design decisions already LOCKED
+
+- /ds-refactor MUST:
+  - Replace hardcoded values with existing tokens
+  - Preserve rendered UI output
+  - Generate an audit report of all changes
+  - Require explicit user authorization before applying changes
+
+- After a successful /ds-refactor:
+  - /ds-validate MUST be re-run
+  - design_system.validated MAY be set to true
+  - UI generation MAY be unblocked
+
+## Workflow Authority
+
+- `/next-step` is the only workflow allowed to determine progression
+- Direct execution of DS workflows without readiness checks is forbidden
+
+
+6. Create `.agent/workflows/next-step.md` with a workflow that:
+
+---
+Description: Determine the next logical and allowed action based on the current project state.
+---
+
+## Execution Steps
+
+### 1. Load Project State
+Read `.agent/state/project.json`
+
+---
+
+### 2. Evaluate Stage
+
+#### Stage: discovery
+- Recommend:
+  - Defining project intent
+  - Clarifying constraints
+  - Selecting product type
+- Output command suggestion only (no execution)
+
+---
+
+## Workflow Authority Alignment
+
+- `/next-step` is the sole authority to authorize `/ds-components`
+- Manual invocation of `/ds-components` without `/next-step` authorization is forbidden
+- Manual invocation of `/page-build` without `/next-step` authorization is forbidden
+
+---
+
+#### Stage: development
+
+##### 2.1 Design System Initialization Guard
+- If `/app/globals.css` does NOT exist:
+  → NEXT ACTION: `/ds-init`
+
+---
+
+##### 2.2 Token Readiness Guard
+- If `design_system.tokens === "scaffold_only"`:
+  → BLOCK UI  
+  → NEXT ACTION: Add visual references + `/ds-tokens`
+
+- If `design_system.tokens === "missing"`:
+  → BLOCK UI  
+  → NEXT ACTION: Add visual references + `/ds-tokens`
+
+---
+
+##### 2.2.1 Reference Detection Guard
+- If new files are detected in `design-system/references`:
+  → Set `design_system.tokens = "outdated"`  
+  → BLOCK UI generation  
+  → NEXT ACTION: `/ds-tokens`
+
+---
+
+##### 2.3 Component Readiness Guard (Hard Gate)
+
+- If UI components are requested  
+  AND `design_system.validated === false`:
+  → BLOCK execution  
+  → NEXT ACTION: `/ds-validate`
+
+- If UI components are requested  
+  AND `design_system.validated === true`:
+  → NEXT ACTION: `/ds-components`
+
+---
+
+##### 2.4 Validation Gate (Hard Stop)
+
+- If `design_system.tokens === "scaffold_only"`:
+  → BLOCK UI  
+  → NEXT ACTION: Add visual references + `/ds-tokens`
+
+- If `design_system.tokens === "ready"`  
+  AND `design_system.token_origin === "visual_reference"`  
+  AND `design_system.validated === false`:
+  → NEXT ACTION: `/ds-validate`
+
+---
+
+##### 2.4.1 Design System Recovery Path (Refactor Mode)
+
+If ALL conditions below are true:
+
+- `design_system.initialized === true`
+- `design_system.tokens === "ready"`
+- `design_system.validated === false`
+- A ds-validation report exists
+- All violations are limited to:
+  - hardcoded colors
+  - inline styles
+  - token bypass
+- NO violations related to:
+  - accessibility
+  - layout structure
+  - semantics
+  - component architecture
+
+Then:
+
+- UI generation remains BLOCKED
+- Recovery is ALLOWED
+
+→ Authorized Workflow: `/ds-refactor`  
+→ Next Logical Action: Refactor existing components to token-only compliance  
+→ Command to Execute: `/ds-refactor`
+
+---
+
+##### 2.4.2 Component Authority Enforcement
+
+- UI components MUST be created only via `/ds-components`
+- Direct component creation outside this workflow is forbidden
+
+If component files are detected without `/ds-components` execution:
+→ BLOCK execution  
+→ Report governance violation  
+→ Require correction via `/ds-refactor` (if refactorable)  
+→ Otherwise require removal and recreation via `/ds-components`
+
+---
+
+##### 2.5 Documentation Guard
+- If components exist and styleguide is missing:
+  → Recommend `/ds-styleguide`
+
+---
+
+##### 2.5.1 Copy Readiness Guard (Hard Gate)
+
+If page, section, or feature UI is requested:
+
+- If required copy/content is missing:
+  → BLOCK execution  
+  → NEXT ACTION: `/copy-collect`
+
+- If copy exists but `copy.status !== "approved"`:
+  → BLOCK execution  
+  → NEXT ACTION: `/copy-collect`
+
+- If `copy.status === "approved"`:
+  → ALLOW continuation
+
+> Notes:
+> - Copy includes: headings, labels, CTAs, empty states, helper text, messages
+> - `/page-build` is forbidden to invent copy
+> - Copy approval is a product decision, not a UI decision
+
+---
+
+##### 2.6 Page / Feature UI Guard
+
+- If page or feature UI is requested  
+  AND `design_system.validated === true`  
+  AND `copy.status === "approved"`:
+  → NEXT ACTION: `/page-build`
+
+- If page or feature UI is requested  
+  AND `design_system.validated === false`:
+  → BLOCK execution  
+  → NEXT ACTION: `/ds-validate`
+
+---
+
+##### 2.7 Page Build Authority
+
+- Page or section UI MUST be created only via `/page-build`
+
+- If requested change is scoped to an existing page:
+  → Require `mode=extend`
+
+- If requested change introduces a new route:
+  → Require `mode=create`
+
+---
+
+##### 2.8 Mobile UX Validation Gate (NEW — HARD)
+If page build has been completed:
+
+- If `ux_mobile !== "validated"`:
+  → NEXT ACTION: `/ux-mobile-validate`
+
+❌ Page is NOT considered production-ready without this
+
+---
+
+##### 2.9 Mobile UX Optimization (OPTIONAL, GOVERNED)
+
+If ALL are true:
+
+- `ux_mobile === "validated"`
+- No blocking issues
+- Explicit optimization intent detected
+  → AUTHORIZED (Optional): `/ux-mobile-optimize`
+
+⚠️ Never mandatory
+⚠️ Never blocking
+
+---
+
+### 3. Decision Protection
+
+- Never re-evaluate locked decisions
+- Never suggest alternatives that violate constraints
+- Never suggest UI or component generation outside `/ds-components`
+- Never allow page or feature UI to define new visual patterns
+- Never allow `/ds-refactor` to alter visual decisions
+- Never allow `/page-build` to invent or modify approved copy
+
+---
+
+### 4. Output Format (Mandatory)
+
+Current Stage:  
+Design System Status:  
+UX Mobile Status:
+Blocking Issues:  
+Next Logical Action:  
+Authorized Workflow:  
+Command to Execute:  
+Design System Validation:
+
+
+
+3. Initialization Confirmation
+After successful execution:
+   - Confirm project initialized
+   - Explain governance model
+   - Explain that /next-step is now the single source of progression
+   - Recommend next discovery actions