guardian-framework 0.1.24 → 0.1.26

package/templates/pi/extensions/domain-explorer.ts

@@ -190,6 +190,132 @@ function buildExplorationPrompt(context: string): string {
 	].join("\n");
 }
 
+function readLanguage(cwd: string): string {
+	try {
+		const manifestPath = path.join(cwd, "guardian-manifest.json");
+		if (fs.existsSync(manifestPath)) {
+			const raw = fs.readFileSync(manifestPath, "utf-8");
+			const manifest = JSON.parse(raw) as { language?: string };
+			if (manifest.language) return manifest.language;
+		}
+	} catch {}
+	return "typescript";
+}
+
+function buildFrontendExplorationPrompt(context: string): string {
+	return [
+		"You are a frontend architecture expert. Analyze the following web application",
+		"description and extract a structured model focused on user experience,",
+		"UI concepts, and design principles. Respond with valid JSON only.",
+		"",
+		"## Business Context",
+		"",
+		context,
+		"",
+		"## Output Format (JSON)",
+		"",
+		"\`\`\`json",
+		"{",
+		'  "businessContext": "Brief one-line summary",',
+		'  "actors": [',
+		"    {",
+		'      "name": "UserRole",',
+		'      "description": "Who this user is",',
+		'      "interactions": "What they do in the application"',
+		"    }",
+		"  ],",
+		'  "functionalRequirements": [',
+		"    {",
+		'      "id": "FR-001",',
+		'      "requirement": "The user shall be able to...",',
+		'      "priority": "critical|high|medium|low",',
+		'      "boundedContext": "FeatureName"',
+		"    }",
+		"  ],",
+		'  "nonFunctionalRequirements": [',
+		"    {",
+		'      "id": "NFR-001",',
+		'      "requirement": "The application shall...",',
+		'      "category": "performance|accessibility|usability|security|maintainability",',
+		'      "target": "Specific measurable target"',
+		"    }",
+		"  ],",
+		'  "assumptions": [',
+		"    {",
+		'      "assumption": "We assume that...",',
+		'      "impactIfWrong": "What breaks if this is false",',
+		'      "mitigation": "How we handle it being wrong"',
+		"    }",
+		"  ],",
+		'  "boundedContexts": [',
+		"    {",
+		'      "name": "FeatureName",',
+		'      "description": "Brief description of this app feature/section",',
+		'      "entities": ["UIConcept1", "UIConcept2"]',
+		"    }",
+		"  ],",
+		'  "entities": [',
+		"    {",
+		'      "name": "UIConceptName",',
+		'      "context": "FeatureName",',
+		'      "type": "ui-concept | user-intent | design-token | app-shell | value-object",',
+		'      "description": "What this UI concept represents"',
+		"    }",
+		"  ],",
+		'  "userIntents": [',
+		"    {",
+		'      "name": "UserIntentName",',
+		'      "context": "FeatureName",',
+		'      "description": "What the user is trying to do",',
+		'      "triggeredBy": "What UI action triggers this intent"',
+		"    }",
+		"  ],",
+		'  "designPrinciples": [',
+		"    {",
+		'      "principle": "The application is...",',
+		'      "description": "What this principle means in practice",',
+		'      "rationale": "Why this principle exists"',
+		"    }",
+		"  ],",
+		'  "navigationPhilosophy": {',
+		'    "contextPreservation": "How the user never loses context",',
+		'    "deepLinking": "How every page is deep-linkable",',
+		'    "multiTab": "How multiple tabs are supported"',
+		"  },",
+		'  "appShell": {',
+		'    "navigation": "Navigation structure",',
+		'    "header": "Header content",',
+		'    "sidebar": "Sidebar content",',
+		'    "commandPalette": "Command palette actions",',
+		'    "globalSearch": "Global search behavior"',
+		"  },",
+		'  "degradationStrategy": [',
+		"    {",
+		'      "feature": "FeatureName",',
+		'      "whenUnavailable": "What happens when this feature API is down",',
+		'      "degradesTo": "What still works"',
+		"    }",
+		"  ],",
+		'  "ubiquitousLanguage": [',
+		"    {",
+		'      "term": "CanonicalTerm",',
+		'      "definition": "Clear definition",',
+		'      "boundedContext": "FeatureName",',
+		'      "aliases": ["AlternativeName1"],',
+		'      "examples": "Usage example"',
+		"    }",
+		"  ],",
+		'  "openQuestions": "Any open questions about the application",',
+		'  "designSystem": {',
+		'    "componentLibrary": "Which component library or approach",',
+		'    "theming": "How theming works",',
+		'    "accessibility": "Accessibility requirements"',
+		"  }",
+		"}",
+		"\`\`\`",
+	].join("\n");
+}
+
 // ── Domain Explore Tool (deprecated) ──
 
 export default function (pi: ExtensionAPI) {
@@ -473,7 +599,9 @@ export default function (pi: ExtensionAPI) {
 					return "(domain command handled)";
 				}
 				const sanitized = sanitizeContext(context);
-				const prompt = buildExplorationPrompt(sanitized);
+				const lang = readLanguage(ctx.cwd);
+				const isFrontend = lang === "nextjs" || lang === "angular";
+				const prompt = isFrontend ? buildFrontendExplorationPrompt(sanitized) : buildExplorationPrompt(sanitized);
 				const sessionId = crypto.randomUUID();
 				const explorationDir = path.join(ctx.cwd, ".pi", "domain", "exploration");
 				fs.mkdirSync(explorationDir, { recursive: true });
@@ -502,99 +630,237 @@ export default function (pi: ExtensionAPI) {
 
 				// Write stub exploration.md with business context filled in
 				const explorationMdPath = path.join(ctx.cwd, ".pi", "domain", "exploration.md");
-				const stubContent = [
-					"---",
-					"session_id: " + sessionId,
-					"created: " + new Date().toISOString().split("T")[0],
-					'business_context: "' + sanitized.replace(/"/g, '\\"') + '"',
-					"status: draft",
-					"---",
-					"",
-					"# Domain Exploration: " + sessionId,
-					"",
-					"> **Status:** draft — agent needs to fill in the analysis below.",
-					"",
-					"---",
-					"",
-					"## Business Context",
-					"",
-					sanitized,
-					"",
-					"---",
-					"",
-					"## Actors & Roles",
-					"",
-					"| Actor | Description | Interactions |",
-					"|-------|-------------|-------------|",
-					"| | | |",
-					"",
-					"---",
-					"",
-					"## Functional Requirements",
-					"",
-					"| ID | Requirement | Priority | Bounded Context |",
-					"|----|-------------|----------|----------------|",
-					"| | | | |",
-					"",
-					"---",
-					"",
-					"## Non-Functional Requirements",
-					"",
-					"| ID | Requirement | Category | Target |",
-					"|----|-------------|----------|--------|",
-					"| | | | |",
-					"",
-					"---",
-					"",
-					"## Assumptions",
-					"",
-					"| Assumption | Impact if Wrong | Mitigation |",
-					"|------------|----------------|-----------|",
-					"| | | |",
-					"",
-					"---",
-					"",
-					"## Bounded Contexts",
-					"",
-					"| Context | Description | Entities |",
-					"|---------|-------------|----------|",
-					"| | | |",
-					"",
-					"---",
-					"",
-					"## Entities",
-					"",
-					"| Entity | Context | Type | Description |",
-					"|--------|---------|------|-------------|",
-					"| | | | |",
-					"",
-					"---",
-					"",
-					"## Domain Events",
-					"",
-					"| Event | Context | Description | Triggered By |",
-					"|-------|---------|-------------|-------------|",
-					"| | | | |",
-					"",
-					"---",
-					"",
-					"## Ubiquitous Language",
-					"",
-					"| Term | Definition | Bounded Context | Aliases/Synonyms |",
-					"|------|-----------|----------------|-----------------|",
-					"| | | | |",
-					"",
-					"---",
-					"",
-					"## Open Questions",
-					"",
-					"",
-					"---",
-					"",
-					"## Aggregate Roots",
-					"",
-					"",
-				].join("\n");
+				const stubContent = isFrontend
+					? [
+						"---",
+						"session_id: " + sessionId,
+						"created: " + new Date().toISOString().split("T")[0],
+						'business_context: "' + sanitized.replace(/"/g, '\\"') + '"',
+						"status: draft",
+						"---",
+						"",
+						"# Domain Exploration: " + sessionId,
+						"",
+						"> **Status:** draft — agent needs to fill in the analysis below.",
+						"",
+						"---",
+						"",
+						"## Business Context",
+						"",
+						sanitized,
+						"",
+						"---",
+						"",
+						"## Actors & Roles",
+						"",
+						"| Actor | Description | Interactions |",
+						"|-------|-------------|-------------|",
+						"| | | |",
+						"",
+						"---",
+						"",
+						"## Functional Requirements",
+						"",
+						"| ID | Requirement | Priority | Feature |",
+						"|----|-------------|----------|--------|",
+						"| | | | |",
+						"",
+						"---",
+						"",
+						"## Non-Functional Requirements",
+						"",
+						"| ID | Requirement | Category | Target |",
+						"|----|-------------|----------|--------|",
+						"| | | | |",
+						"",
+						"---",
+						"",
+						"## Assumptions",
+						"",
+						"| Assumption | Impact if Wrong | Mitigation |",
+						"|------------|----------------|-----------|",
+						"| | | |",
+						"",
+						"---",
+						"",
+						"## Features (Bounded Contexts)",
+						"",
+						"| Feature | Description | UI Concepts |",
+						"|---------|-------------|------------|",
+						"| | | |",
+						"",
+						"---",
+						"",
+						"## UI Concepts",
+						"",
+						"| Concept | Feature | Type | Description |",
+						"|---------|---------|------|-------------|",
+						"| | | | |",
+						"",
+						"---",
+						"",
+						"## User Intents",
+						"",
+						"| Intent | Feature | Description | Triggered By |",
+						"|--------|---------|-------------|-------------|",
+						"| | | | |",
+						"",
+						"---",
+						"",
+						"## Design Principles",
+						"",
+						"| Principle | Description | Rationale |",
+						"|-----------|-------------|----------|",
+						"| | | |",
+						"",
+						"---",
+						"",
+						"## Navigation Philosophy",
+						"",
+						"| Aspect | Description |",
+						"|--------|-------------|",
+						"| Context Preservation | |",
+						"| Deep Linking | |",
+						"| Multi-Tab Support | |",
+						"",
+						"---",
+						"",
+						"## App Shell",
+						"",
+						"| Component | Description |",
+						"|-----------|-------------|",
+						"| Navigation | |",
+						"| Header | |",
+						"| Sidebar | |",
+						"| Command Palette | |",
+						"| Global Search | |",
+						"| Status Bar | |",
+						"",
+						"---",
+						"",
+						"## Degradation Strategy",
+						"",
+						"| Feature | When Unavailable | Degrades To |",
+						"|---------|-----------------|-------------|",
+						"| | | |",
+						"",
+						"---",
+						"",
+						"## Ubiquitous Language",
+						"",
+						"| Term | Definition | Feature | Aliases/Synonyms |",
+						"|------|-----------|---------|-----------------|",
+						"| | | | |",
+						"",
+						"---",
+						"",
+						"## Design System",
+						"",
+						"| Aspect | Decision |",
+						"|--------|----------|",
+						"| Component Library | |",
+						"| Theming | |",
+						"| Accessibility | |",
+						"",
+						"---",
+						"",
+						"## Open Questions",
+						"",
+						"",
+					  ].join("\n")
+					: [
+						"---",
+						"session_id: " + sessionId,
+						"created: " + new Date().toISOString().split("T")[0],
+						'business_context: "' + sanitized.replace(/"/g, '\\"') + '"',
+						"status: draft",
+						"---",
+						"",
+						"# Domain Exploration: " + sessionId,
+						"",
+						"> **Status:** draft — agent needs to fill in the analysis below.",
+						"",
+						"---",
+						"",
+						"## Business Context",
+						"",
+						sanitized,
+						"",
+						"---",
+						"",
+						"## Actors & Roles",
+						"",
+						"| Actor | Description | Interactions |",
+						"|-------|-------------|-------------|",
+						"| | | |",
+						"",
+						"---",
+						"",
+						"## Functional Requirements",
+						"",
+						"| ID | Requirement | Priority | Bounded Context |",
+						"|----|-------------|----------|----------------|",
+						"| | | | |",
+						"",
+						"---",
+						"",
+						"## Non-Functional Requirements",
+						"",
+						"| ID | Requirement | Category | Target |",
+						"|----|-------------|----------|--------|",
+						"| | | | |",
+						"",
+						"---",
+						"",
+						"## Assumptions",
+						"",
+						"| Assumption | Impact if Wrong | Mitigation |",
+						"|------------|----------------|-----------|",
+						"| | | |",
+						"",
+						"---",
+						"",
+						"## Bounded Contexts",
+						"",
+						"| Context | Description | Entities |",
+						"|---------|-------------|----------|",
+						"| | | |",
+						"",
+						"---",
+						"",
+						"## Entities",
+						"",
+						"| Entity | Context | Type | Description |",
+						"|--------|---------|------|-------------|",
+						"| | | | |",
+						"",
+						"---",
+						"",
+						"## Domain Events",
+						"",
+						"| Event | Context | Description | Triggered By |",
+						"|-------|---------|-------------|-------------|",
+						"| | | | |",
+						"",
+						"---",
+						"",
+						"## Ubiquitous Language",
+						"",
+						"| Term | Definition | Bounded Context | Aliases/Synonyms |",
+						"|------|-----------|----------------|-----------------|",
+						"| | | | |",
+						"",
+						"---",
+						"",
+						"## Open Questions",
+						"",
+						"",
+						"---",
+						"",
+						"## Aggregate Roots",
+						"",
+						"",
+					  ].join("\n");
 				fs.writeFileSync(explorationMdPath + ".tmp", stubContent, "utf-8");
 				fs.renameSync(explorationMdPath + ".tmp", explorationMdPath);
 
@@ -626,12 +892,18 @@ export default function (pi: ExtensionAPI) {
 				// Using sendMessage with triggerTurn=true causes the agent to process
 				// this as a new conversation turn, not as a command response.
 				const analysisPrompt = [
-					"I need you to analyze the following business domain using Domain-Driven Design.",
+					"I need you to analyze the following business domain.",
 					"I have created stub files in .pi/domain/exploration.md and .pi/domain/ubiquitous-language.md.",
 					"",
+					"IMPORTANT: Read .pi/domain/exploration.md FIRST. It contains empty tables.",
+					"FILL IN the existing tables exactly as structured. Do NOT change the section names or table columns.",
+					"Do NOT add new sections that aren't in the stub. Do NOT use 'Domain Events' or 'Aggregate Roots' — those are backend concepts.",
+					"",
 					"Your task:",
 					"1. READ .pi/domain/exploration.md — it has the business context and empty tables",
-					"2. ANALYZE the domain: actors, FR/NFR, assumptions, bounded contexts, entities, events , glossary",
+					(isFrontend
+						? "2. ANALYZE the domain: actors, FR/NFR, assumptions, features (bounded contexts), UI concepts, user intents, glossary"
+						: "2. ANALYZE the domain: actors, FR/NFR, assumptions, bounded contexts, entities, events, glossary"),
 					"3. FILL IN all empty tables in .pi/domain/exploration.md with your analysis",
 					"4. UPDATE .pi/domain/ubiquitous-language.md with the glossary terms",
 					"",
@@ -639,18 +911,40 @@ export default function (pi: ExtensionAPI) {
 					sanitized,
 					"",
 					"Use this JSON schema as a reference for structuring your analysis:",
-					'```json',
-					"{",
-					'  "actors": [{ "name": "", "description": "", "interactions": "" }],',
-					'  "functionalRequirements": [{ "id": "FR-001", "requirement": "", "priority": "critical|high|medium|low", "boundedContext": "" }],',
-					'  "nonFunctionalRequirements": [{ "id": "NFR-001", "requirement": "", "category": "performance|security|scalability|availability|maintainability", "target": "" }],',
-					'  "assumptions": [{ "assumption": "", "impactIfWrong": "", "mitigation": "" }],',
-					'  "boundedContexts": [{ "name": "", "description": "", "entities": [""] }],',
-					'  "entities": [{ "name": "", "context": "", "type": "entity|value-object|aggregate-root", "description": "" }],',
-					'  "domainEvents": [{ "name": "", "context": "", "description": "", "triggeredBy": "" }],',
-					'  "ubiquitousLanguage": [{ "term": "", "definition": "", "boundedContext": "", "aliases": [""], "examples": "" }]',
-					"}",
-					'```',
+					isFrontend
+						? [
+								'\`\`\`json',
+								"{",
+								'  "actors": [{ "name": "", "description": "", "interactions": "" }],',
+								'  "functionalRequirements": [{ "id": "FR-001", "requirement": "", "priority": "critical|high|medium|low", "boundedContext": "" }],',
+								'  "nonFunctionalRequirements": [{ "id": "NFR-001", "requirement": "", "category": "performance|accessibility|usability|security|maintainability", "target": "" }],',
+								'  "assumptions": [{ "assumption": "", "impactIfWrong": "", "mitigation": "" }],',
+								'  "boundedContexts": [{ "name": "", "description": "", "entities": [""] }],',
+								'  "entities": [{ "name": "", "context": "", "type": "ui-concept|user-intent|design-token|app-shell|value-object", "description": "" }],',
+								'  "userIntents": [{ "name": "", "context": "", "description": "", "triggeredBy": "" }],',
+								'  "designPrinciples": [{ "principle": "", "description": "", "rationale": "" }],',
+								'  "navigationPhilosophy": { "contextPreservation": "", "deepLinking": "", "multiTab": "" },',
+								'  "appShell": { "navigation": "", "header": "", "sidebar": "", "commandPalette": "", "globalSearch": "" },',
+								'  "degradationStrategy": [{ "feature": "", "whenUnavailable": "", "degradesTo": "" }],',
+								'  "ubiquitousLanguage": [{ "term": "", "definition": "", "boundedContext": "", "aliases": [""], "examples": "" }],',
+								'  "designSystem": { "componentLibrary": "", "theming": "", "accessibility": "" }',
+								"}",
+								'\`\`\`',
+						  ].join("\n")
+						: [
+								'\`\`\`json',
+								"{",
+								'  "actors": [{ "name": "", "description": "", "interactions": "" }],',
+								'  "functionalRequirements": [{ "id": "FR-001", "requirement": "", "priority": "critical|high|medium|low", "boundedContext": "" }],',
+								'  "nonFunctionalRequirements": [{ "id": "NFR-001", "requirement": "", "category": "performance|security|scalability|availability|maintainability", "target": "" }],',
+								'  "assumptions": [{ "assumption": "", "impactIfWrong": "", "mitigation": "" }],',
+								'  "boundedContexts": [{ "name": "", "description": "", "entities": [""] }],',
+								'  "entities": [{ "name": "", "context": "", "type": "entity|value-object|aggregate-root", "description": "" }],',
+								'  "domainEvents": [{ "name": "", "context": "", "description": "", "triggeredBy": "" }],',
+								'  "ubiquitousLanguage": [{ "term": "", "definition": "", "boundedContext": "", "aliases": [""], "examples": "" }]',
+								"}",
+								'\`\`\`',
+						  ].join("\n"),
 				].join("\n");
 
 				try {

package/templates/pi/preflight_report.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-07-03T07:45:52Z",
+  "timestamp": "2026-07-03T11:03:52Z",
   "mode": "all",
   "stages_run": [],
   "summary": {

package/templates/pi/skills/agents/design-system-codegen.md

@@ -0,0 +1,41 @@
+---
+name: design-system-codegen
+description: Minimal skill for design system architecture with DDD + adapter pattern. References full patterns on demand — never loads inline. Use when building design system components, tokens, or CSS integration.
+model: inherit
+tools: [Read, Grep]
+---
+
+# Design System Code Generation — DDD + Adapter Pattern
+
+> Full reference: `.pi/skills/design-system-enterprise-codegen.md`
+
+## Quick Reference
+
+| When you need... | Read this section |
+|-----------------|-------------------|
+| Structure overview | Section 1 — DDD module layout, framework agnostic |
+| Design tokens | Section 2 — ColorToken, SpacingToken, TypeScale as domain values |
+| Variant engine | Section 3 — defineVariants(), type-safe component props |
+| CSS adapter (Tailwind) | Section 4 — Tailwind class generation from tokens |
+| CSS adapter (CSS Modules) | Section 4 — CSS variable generation |
+| CSS adapter (MUI/Material) | Section 4 — MUI theme mapping |
+| Component pattern | Section 5 — Button component using application layer |
+| Theming (dark mode) | Section 6 — ThemeService, data-theme attribute |
+| Testing | Section 7 — token tests, variant engine tests |
+| Choosing your stack | Section 8 — Tailwind vs CSS Modules vs MUI by use case |
+
+## DDD Layer Contract for Design Systems
+
+| Layer | Purpose | Example | CSS framework aware? |
+|-------|---------|---------|---------------------|
+| `domain/tokens/` | Typed design tokens | `ColorToken.PRIMARY` | No |
+| `application/` | Variant resolution, theming | `defineVariants()` | No |
+| `infrastructure/` | CSS adapter | `tailwind-adapter.ts` | **Yes** — this is the only layer |
+| `interfaces/` | Rendered components | `button.tsx` | No (uses application layer) |
+
+## Rules
+- NEVER read full reference — read specific sections
+- Design tokens are pure TypeScript — zero CSS, zero framework imports
+- Components import from `application/`, never from `infrastructure/` directly
+- The adapter is the **only file** that changes when you switch CSS frameworks
+- Pick one adapter per project — never mix Tailwind and MUI in the same component