@ryuenn3123/agentic-senior-core 3.0.6 → 3.0.8

package/.agent-context/prompts/bootstrap-design.md

@@ -1,22 +1,48 @@
 
-# Bootstrap DESIGN.md (UI/UX Art Direction)
+# Bootstrap Dynamic Design Contract
 
-When a user requests frontend design or redesign, the agent should automatically synthesize a complete DESIGN.md covering:
-- Visual identity (color palette, typography, spacing, iconography)
-- Layout and navigation principles
-- Component library and atomic design system
-- Accessibility and responsive guidelines
-- User journey and interaction flows
-- Design tokens and handoff notes for developers
+When a user requests frontend design or redesign, the agent should automatically synthesize a dynamic design contract made of:
+- `docs/DESIGN.md` for human-readable design direction and implementation rationale
+- `docs/design-intent.json` for machine-readable intent, anti-generic constraints, and validation hints
+
+This contract is a structure and reasoning system, not a fixed visual template. It must adapt to product context, user needs, platform constraints, and current design signals.
 
 The agent must:
 1. Read [AGENTS.md](../../AGENTS.md) for project context and team roles.
 2. Scan all files in [.agent-context/rules/](../rules/) for UI/UX and accessibility standards.
 3. Reference [docs/deep-dive.md](../../docs/deep-dive.md) and [docs/faq.md](../../docs/faq.md) for architecture and product background.
-4. If [docs/DESIGN.md](../../docs/DESIGN.md) exists, check for drift and propose improvements instead of rewriting from scratch.
-5. All references to docs or rules must be clickable markdown links.
+4. If [docs/DESIGN.md](../../docs/DESIGN.md) or `docs/design-intent.json` already exists, check for drift and improve them instead of rewriting blindly.
+5. Treat any example structure or stylistic inspiration as non-normative. Use it only to judge depth and clarity, never to copy a visual language directly.
+6. All references to docs or rules must be clickable markdown links.
+
+Required `docs/DESIGN.md` sections:
+1. Design Intent and Product Personality
+2. Audience and Use-Context Signals
+3. Visual Direction and Distinctive Moves
+4. Color System and Semantic Roles
+5. Typography System and Hierarchy
+6. Spacing, Layout Rhythm, and Density Strategy
+7. Interaction, Motion, and Feedback Rules
+8. Component Language and Shared Patterns
+9. Accessibility Non-Negotiables
+10. Responsive Strategy
+11. Anti-Patterns to Avoid
+12. Implementation Notes for Future UI Tasks
+
+Required `docs/design-intent.json` fields:
+- `mode`
+- `status`
+- `project`
+- `brandAdjectives`
+- `antiAdjectives`
+- `visualDirection`
+- `experiencePrinciples`
+- `forbiddenPatterns`
+- `requiredDesignSections`
+- `implementation`
 
 Output:
-- Write a full DESIGN.md in markdown, with clear sections and clickable links to referenced docs/rules.
-- Use practical, modern, and accessible design language.
+- Create or update both `docs/DESIGN.md` and `docs/design-intent.json`.
+- Keep both files synchronized: the markdown explains the why, the JSON captures the contract in machine-readable form.
+- Use practical, modern, accessible language grounded in the project, not generic SaaS defaults.
 - Wait for user approval before generating Figma or code assets.

package/.agent-context/prompts/init-project.md

@@ -35,7 +35,7 @@ If the user specifies a framework/blueprint, the agent should:
 See [docs/roadmap.md](../../docs/roadmap.md) and [docs/deep-dive.md](../../docs/deep-dive.md) for the latest stack and blueprint list.
 
 ## UI/UX Bootstrap
-When a user requests frontend or UI/UX design, the agent should automatically execute the [bootstrap-design.md](./bootstrap-design.md) prompt to synthesize DESIGN.md.
+When a user requests frontend or UI/UX design, the agent should automatically execute the [bootstrap-design.md](./bootstrap-design.md) prompt to synthesize a dynamic design contract (`docs/DESIGN.md` + `docs/design-intent.json`).
 
 ---
 
@@ -97,6 +97,6 @@ See [docs/roadmap.md](../../docs/roadmap.md) and [docs/deep-dive.md](../../docs/
 
 ---
 
-## Bootstrap UI/UX (DESIGN.md)
+## Bootstrap UI/UX (Dynamic Design Contract)
 
-To start UI/UX design from scratch, use the [bootstrap-design.md](./bootstrap-design.md) prompt to synthesize `docs/DESIGN.md`.
+To start UI/UX design from scratch, use the [bootstrap-design.md](./bootstrap-design.md) prompt to synthesize `docs/DESIGN.md` and `docs/design-intent.json`.

package/.agent-context/prompts/refactor.md

@@ -15,7 +15,7 @@ Before making changes:
 3. Read .agent-context/rules/error-handling.md — fix error handling patterns.
 4. Resolve active language guidance from dynamic stack signals (TypeScript in this repository).
 5. Enforce backend universal principles: no clever hacks, no premature abstraction, readability over brevity.
-6. Enforce Universal SOP hard gate: stop implementation if `docs/architecture-decision-record.md` is missing, and for UI scope stop if `docs/DESIGN.md` is missing.
+6. Enforce Universal SOP hard gate: stop implementation if `docs/architecture-decision-record.md` is missing, and for UI scope stop if `docs/DESIGN.md` or `docs/design-intent.json` is missing.
 
 For every change you make, provide a Reasoning Chain:
 - What was wrong (rule reference)

package/.agent-context/prompts/review-code.md

@@ -20,7 +20,7 @@ Use these checklists:
 7. Enforce cross-session consistency guardian: session handoff must include active architecture contract summary, drift detection must warn before direction changes, and direction changes require explicit user confirmation.
 8. Enforce explain-on-demand state visibility: default responses must avoid unnecessary state-file internals, state internals are exposed only on explicit request, and diagnostic mode must explain relevant state decisions when needed.
 9. Enforce single-source and lazy-loading policy: canonical rule source must be explicitly enforced, language-specific guidance must load lazily based on detected scope, and conflicting duplicate rule instructions must not appear during normal flow.
-10. Enforce Universal SOP hard gate: block coding flow when required project docs are missing (`docs/architecture-decision-record.md`, and for UI scope `docs/DESIGN.md`).
+10. Enforce Universal SOP hard gate: block coding flow when required project docs are missing (`docs/architecture-decision-record.md`, and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).
 
 For EVERY violation found:
 - State the exact file and line

package/.agent-context/review-checklists/pr-checklist.md

@@ -135,4 +135,4 @@ VERDICT: PASS / FAIL (X/Y items passed)
 - [ ] Backend and frontend mindset checks are both applied when scope spans API and UI boundaries
 - [ ] Security and testing requirements remain mandatory after static template purge
 - [ ] Coding flow is blocked if `docs/architecture-decision-record.md` (or `docs/Architecture-Decision-Record.md`) is missing
-- [ ] UI implementation flow is blocked if `docs/DESIGN.md` is missing
+- [ ] UI implementation flow is blocked if `docs/DESIGN.md` or `docs/design-intent.json` is missing

package/.agent-context/rules/architecture.md

@@ -21,7 +21,7 @@ The `.agent-context/rules/` directory is the default guidance source for impleme
 - Security and testing are non-negotiable baseline requirements.
 - Hard block before coding:
   - `docs/architecture-decision-record.md` (alias: `docs/Architecture-Decision-Record.md`) must exist.
-  - For UI scope, `docs/DESIGN.md` must exist.
+  - For UI scope, `docs/DESIGN.md` and `docs/design-intent.json` must exist.
 - If required project context docs are missing, stop implementation and bootstrap docs before writing application code.
 
 ## Rules as Guardian (Cross-Session Consistency)

package/.agent-context/state/memory-continuity-benchmark.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-04-19T03:52:25.678Z",
+  "generatedAt": "2026-04-20T01:05:14.547Z",
   "reportName": "memory-continuity-benchmark",
   "schemaVersion": "1.0.0",
   "passed": true,

package/.cursorrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v3.0.6
+Generated by Agentic-Senior-Core CLI v3.0.8
 Timestamp: 2026-04-18T00:00:00.000Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json
@@ -46,4 +46,4 @@ Do not claim done before checklist pass.
 
 ## UNIVERSAL SOP HARD GATES
 - Stop coding if docs/architecture-decision-record.md (or docs/Architecture-Decision-Record.md) is missing.
-- For UI scope, stop coding if docs/DESIGN.md is missing.
+- For UI scope, stop coding if docs/DESIGN.md or docs/design-intent.json is missing.

package/.gemini/instructions.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 354edbbfaedec284ddcc6d4a5bb5393a7f5385650d1a6ae84a2d9633b5a6d10d
+Canonical Snapshot SHA256: 08c326d79f2c0f4bd7ef106da3542ab0f78f4d02bc205d63598db34cf3f40731
 
 Canonical policy source: [.instructions.md](../.instructions.md).
 

package/.github/copilot-instructions.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 354edbbfaedec284ddcc6d4a5bb5393a7f5385650d1a6ae84a2d9633b5a6d10d
+Canonical Snapshot SHA256: 08c326d79f2c0f4bd7ef106da3542ab0f78f4d02bc205d63598db34cf3f40731
 
 The canonical policy source for this repository is [.instructions.md](../.instructions.md).
 

package/.windsurfrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v3.0.6
+Generated by Agentic-Senior-Core CLI v3.0.8
 Timestamp: 2026-04-18T00:00:00.000Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json
@@ -46,4 +46,4 @@ Do not claim done before checklist pass.
 
 ## UNIVERSAL SOP HARD GATES
 - Stop coding if docs/architecture-decision-record.md (or docs/Architecture-Decision-Record.md) is missing.
-- For UI scope, stop coding if docs/DESIGN.md is missing.
+- For UI scope, stop coding if docs/DESIGN.md or docs/design-intent.json is missing.

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 354edbbfaedec284ddcc6d4a5bb5393a7f5385650d1a6ae84a2d9633b5a6d10d
+Canonical Snapshot SHA256: 08c326d79f2c0f4bd7ef106da3542ab0f78f4d02bc205d63598db34cf3f40731
 
 This file is an adapter entrypoint for agent discovery.
 The canonical policy source is [.instructions.md](.instructions.md).

package/README.md

@@ -10,12 +10,12 @@
 **Production-grade Rules Engine (Governance Engine) for AI coding agents.**
 Works with Cursor, Windsurf, GitHub Copilot, Claude Code, Gemini, and other LLM-powered IDE workflows.
 
-Latest release: 3.0.6 (2026-04-19).
+Latest release: 3.0.8 (2026-04-20).
 
-Highlights in 3.0.0:
-- Universal IDE adapter surface is completed and synchronized through thin adapters.
-- Scoped auto-docs sync rollout is active with explicit phase-1 boundaries and precision/recall evidence.
-- Init and scaffolding flow is slimmer, template-free on active path, and validated by deterministic release gates.
+Highlights in 3.0.8:
+- Existing UI repositories now get `docs/design-intent.json` seeded during both `init` and `upgrade`.
+- Upgrade preview explicitly shows when a machine-readable design seed will be created on apply.
+- UI scope detection is now shared between `init` and `upgrade` so design-contract enforcement stays consistent.
 
 </div>
 

package/lib/cli/commands/init.mjs

@@ -4,6 +4,7 @@
  */
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
+import fs from 'node:fs/promises';
 import path from 'node:path';
 
 import {
@@ -29,10 +30,16 @@ import {
   formatBlockingSeverities,
   formatDuration,
   copyGovernanceAssetsToTarget,
+  pathExists,
 } from '../utils.mjs';
 
 import { collectProfilePacks, findProfilePackByInput } from '../profile-packs.mjs';
-import { detectProjectContext, buildDetectionSummary, formatDetectionCandidates } from '../detector.mjs';
+import {
+  detectProjectContext,
+  buildDetectionSummary,
+  formatDetectionCandidates,
+  detectUiScopeSignals,
+} from '../detector.mjs';
 import { compileDynamicContext, writeSelectedPolicy, writeOnboardingReport } from '../compiler.mjs';
 import {
   filterBlueprintFileNamesByCandidates,
@@ -55,6 +62,7 @@ import {
   hasExistingProjectDocs,
   loadProjectConfig,
   normalizeDocsLanguage,
+  buildDesignIntentSeedFromSignals,
 } from '../project-scaffolder.mjs';
 import { performRollback } from '../rollback.mjs';
 import {
@@ -162,6 +170,41 @@ async function askBlueprintSelection(promptMessage, selectableBlueprintFileNames
   return selectableBlueprintFileNames[selectedIndex] || selectableBlueprintFileNames[0] || null;
 }
 
+function buildInitExistingProjectDesignIntentSeed({
+  targetDirectoryPath,
+  packageManifest,
+  selectedStackFileName,
+  selectedBlueprintFileName,
+  uiScopeSignals,
+  architectureProjectDescription,
+}) {
+  const projectName = String(packageManifest?.name || path.basename(targetDirectoryPath)).trim() || 'existing-ui-project';
+  const isMobileUiProject = String(selectedStackFileName || '').toLowerCase().includes('react-native')
+    || String(selectedStackFileName || '').toLowerCase().includes('flutter')
+    || uiScopeSignals.signalReasons.some((signalReason) => signalReason.includes('android') || signalReason.includes('ios'));
+  const resolvedDomain = isMobileUiProject ? 'Mobile app' : 'Web application';
+  const projectDescription = String(packageManifest?.description || architectureProjectDescription || '').trim()
+    || `Existing ${resolvedDomain.toLowerCase()} detected during init. Create a project-specific dynamic design contract before shipping new UI work.`;
+
+  return buildDesignIntentSeedFromSignals({
+    projectName,
+    projectDescription,
+    primaryDomain: resolvedDomain,
+    features: [],
+    initContext: {
+      stackFileName: selectedStackFileName,
+      blueprintFileName: selectedBlueprintFileName,
+    },
+    status: 'seed-generated-during-init',
+    supplementalFields: {
+      initSignals: {
+        detectedFrom: uiScopeSignals.signalReasons,
+        generatedBy: 'init-existing-project-seed',
+      },
+    },
+  });
+}
+
 export async function runInitCommand(targetDirectoryArgument, initOptions = {}) {
   const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument || '.');
   const isTokenOptimizationEnabled = typeof initOptions.tokenOptimize === 'boolean'
@@ -399,6 +442,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     )?.label || 'Both (frontend + backend)';
 
     let architectureRecommendation = null;
+    let architectureProjectDescription = '';
     let architectPreferenceState = await readArchitectPreferenceState();
     let architectPreferenceUpdated = false;
 
@@ -457,6 +501,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     selectedProjectScopeLabel = architectureSelection.selectedProjectScopeLabel;
     selectedManualStackFileName = architectureSelection.selectedManualStackFileName;
     selectedManualBlueprintFileName = architectureSelection.selectedManualBlueprintFileName;
+    architectureProjectDescription = architectureSelection.architectureProjectDescription;
     architectureRecommendation = architectureSelection.architectureRecommendation;
     architectPreferenceState = architectureSelection.architectPreferenceState;
     architectPreferenceUpdated = architectureSelection.architectPreferenceUpdated;
@@ -578,6 +623,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
 
     // --- Project Documentation Scaffolding ---
     let scaffoldingResult = null;
+    const supplementalMaterializedDocFileNames = [];
     const isFreshProjectTarget = wasDirectoryEffectivelyEmpty && !hadExistingProjectDocsBeforeInit;
     const shouldOfferScaffolding = initOptions.scaffoldDocs === true
       || Boolean(initOptions.projectConfig)
@@ -607,6 +653,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
         } else {
           discoveryAnswers = await runProjectDiscovery(userInterface, {
             defaultProjectName: path.basename(resolvedTargetDirectoryPath),
+            defaultProjectDescription: architectureProjectDescription,
           });
         }
 
@@ -645,6 +692,9 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
           for (const generatedPromptFileName of scaffoldingResult.generatedPromptFileNames || []) {
             console.log(`  - .agent-context/prompts/${generatedPromptFileName}`);
           }
+          for (const materializedFileName of scaffoldingResult.materializedFileNames || []) {
+            console.log(`  - docs/${materializedFileName}`);
+          }
           console.log('Project docs will be authored dynamically by your IDE assistant from these prompts.');
         } else {
           console.log(`\nProject documentation generated in docs/:`);
@@ -655,6 +705,36 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       }
     }
 
+    const existingProjectUiScopeSignals = projectDetection.hasExistingProjectFiles
+      ? await detectUiScopeSignals({
+        targetDirectoryPath: resolvedTargetDirectoryPath,
+        selectedStackFileName: selectedResolvedStackFileName,
+        selectedBlueprintFileName: selectedResolvedBlueprintFileName,
+      })
+      : null;
+    const designIntentTargetPath = path.join(resolvedTargetDirectoryPath, 'docs', 'design-intent.json');
+    const shouldSeedExistingUiDesignIntent = projectDetection.hasExistingProjectFiles
+      && existingProjectUiScopeSignals?.isUiScopeLikely === true
+      && !(await pathExists(designIntentTargetPath));
+
+    if (shouldSeedExistingUiDesignIntent) {
+      const docsDirectoryPath = path.join(resolvedTargetDirectoryPath, 'docs');
+      const designIntentSeedContent = buildInitExistingProjectDesignIntentSeed({
+        targetDirectoryPath: resolvedTargetDirectoryPath,
+        packageManifest: existingProjectUiScopeSignals.packageManifest,
+        selectedStackFileName: selectedResolvedStackFileName,
+        selectedBlueprintFileName: selectedResolvedBlueprintFileName,
+        uiScopeSignals: existingProjectUiScopeSignals,
+        architectureProjectDescription,
+      });
+
+      await ensureDirectory(docsDirectoryPath);
+      await fs.writeFile(designIntentTargetPath, designIntentSeedContent, 'utf8');
+      supplementalMaterializedDocFileNames.push('design-intent.json');
+
+      console.log('\nExisting UI/frontend scope detected. Seeded docs/design-intent.json so the machine-readable design contract exists before UI implementation work continues.');
+    }
+
     await compileDynamicContext({
       targetDirectoryPath: resolvedTargetDirectoryPath,
       selectedProfileName,
@@ -674,6 +754,10 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       selectedProfileName,
       selectedProfilePack,
       selectedPreset: initOptions.preset || null,
+      projectScope: {
+        key: selectedProjectScopeKey,
+        label: selectedProjectScopeLabel,
+      },
       selectedStackFileName: selectedResolvedStackFileName,
       selectedAdditionalStackFileNames,
       selectedBlueprintFileName: selectedResolvedBlueprintFileName,
@@ -746,12 +830,18 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     console.log('- Generated files: .agent-instructions.md, .cursorrules, .windsurfrules, .clauderc, and .agent-context/state/onboarding-report.json');
     if (scaffoldingResult?.bootstrapMode === 'ai-synthesis') {
       console.log(`- Bootstrap prompts: ${(scaffoldingResult.generatedPromptFileNames || []).length} files generated in .agent-context/prompts/`);
+      if ((scaffoldingResult.materializedFileNames || []).length > 0) {
+        console.log(`- Seed docs: ${(scaffoldingResult.materializedFileNames || []).length} files generated in docs/`);
+      }
       console.log(`- Bootstrap docs language: ${scaffoldingResult.docsLanguage}`);
       console.log(`- Expected project docs after synthesis: ${scaffoldingResult.generatedFileNames.length} files in docs/`);
     } else if (scaffoldingResult) {
       console.log(`- Project docs: ${scaffoldingResult.generatedFileNames.length} files generated in docs/`);
       console.log(`- Project docs language: ${scaffoldingResult.docsLanguage}`);
     }
+    if (supplementalMaterializedDocFileNames.length > 0) {
+      console.log(`- Design seed docs: ${supplementalMaterializedDocFileNames.length} files generated in docs/`);
+    }
     console.log(`- Repository workflows copied: no (workflows remain source-repo assets)`);
     console.log(`- MCP configuration: ${shouldIncludeMcpTemplate ? 'auto-configured for your IDEs (VS Code, Cursor, Zed, Gemini)' : 'disabled (--no-mcp-template)'}`);
     if (isMemoryContinuityEnabled) {
@@ -779,7 +869,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       console.log('\nPrompt starter examples (copy and adapt in your IDE):');
       console.log('- If docs/project-brief.md is missing, execute .agent-context/prompts/bootstrap-project-context.md now and create all required docs files.');
       if ((scaffoldingResult.generatedPromptFileNames || []).includes('bootstrap-design.md')) {
-        console.log('- If docs/DESIGN.md is missing, execute .agent-context/prompts/bootstrap-design.md now before building UI components.');
+        console.log('- If docs/DESIGN.md or docs/design-intent.json is missing, execute .agent-context/prompts/bootstrap-design.md now before building UI components.');
       }
       console.log(`- Build an MVP for ${promptProjectName} using the newly synthesized docs as strict project context.`);
       console.log('- When scope changes, update docs/* in the same change so future prompts stay aligned.');
@@ -791,6 +881,11 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       console.log(`- Build an MVP for ${promptProjectName}. Follow Layer 9 docs and keep the current stack, database, and auth constraints.`);
       console.log('- Add [new feature] and update docs/project-brief.md plus docs/flow-overview.md in the same change.');
       console.log('- If this change needs architecture migration, propose a migration plan first, then implement after approval.');
+    } else if (supplementalMaterializedDocFileNames.includes('design-intent.json')) {
+      console.log('I also seeded docs/design-intent.json for this existing UI repository so future UI work starts from a machine-readable design contract without forcing a canned visual concept.');
+      console.log('\nPrompt starter examples (copy and adapt in your IDE):');
+      console.log('- If docs/DESIGN.md is missing, execute .agent-context/prompts/bootstrap-design.md now and refine docs/design-intent.json into a complete design contract before building UI components.');
+      console.log('- Keep docs/design-intent.json and docs/DESIGN.md synchronized whenever the UI direction changes.');
     }
     console.log('Your AI tools will now receive one compiled rulebook plus the original source rules, and your review threshold is stored in .agent-context/policies/llm-judge-threshold.json.');
     console.log('MCP server registration is manual inside your IDE settings, even when mcp.json exists.');

package/lib/cli/commands/upgrade.mjs

@@ -29,6 +29,7 @@ import {
   detectProjectContext,
   buildDetectionSummary,
   formatDetectionCandidates,
+  detectUiScopeSignals,
 } from '../detector.mjs';
 import {
   buildCompiledRulesContent,
@@ -40,7 +41,10 @@ import {
 import { runPreflightChecks } from '../preflight.mjs';
 import { createBackup } from '../backup.mjs';
 import { performRollback } from '../rollback.mjs';
-import { detectProjectDocTemplateStaleness } from '../project-scaffolder.mjs';
+import {
+  detectProjectDocTemplateStaleness,
+  buildDesignIntentSeedFromSignals,
+} from '../project-scaffolder.mjs';
 
 export function parseUpgradeArguments(commandArguments) {
   const parsedUpgradeOptions = {
@@ -103,6 +107,40 @@ function buildExistingProjectMajorConstraints() {
   ];
 }
 
+function buildUpgradeDesignIntentSeed({
+  targetDirectoryPath,
+  packageManifest,
+  selectedStackFileName,
+  selectedBlueprintFileName,
+  uiScopeSignals,
+}) {
+  const projectName = String(packageManifest?.name || path.basename(targetDirectoryPath)).trim() || 'existing-ui-project';
+  const isMobileUiProject = String(selectedStackFileName || '').toLowerCase().includes('react-native')
+    || String(selectedStackFileName || '').toLowerCase().includes('flutter')
+    || uiScopeSignals.signalReasons.some((signalReason) => signalReason.includes('android') || signalReason.includes('ios'));
+  const resolvedDomain = isMobileUiProject ? 'Mobile app' : 'Web application';
+  const projectDescription = String(packageManifest?.description || '').trim()
+    || `Existing ${resolvedDomain.toLowerCase()} detected during upgrade. Create a project-specific dynamic design contract before shipping new UI work.`;
+
+  return buildDesignIntentSeedFromSignals({
+    projectName,
+    projectDescription,
+    primaryDomain: resolvedDomain,
+    features: [],
+    initContext: {
+      stackFileName: selectedStackFileName,
+      blueprintFileName: selectedBlueprintFileName,
+    },
+    status: 'seed-generated-during-upgrade',
+    supplementalFields: {
+      upgradeSignals: {
+        detectedFrom: uiScopeSignals.signalReasons,
+        generatedBy: 'upgrade-seed',
+      },
+    },
+  });
+}
+
 export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions = {}) {
   const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument || '.');
 
@@ -135,7 +173,6 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     const blueprintFileNames = await collectFileNames(path.join(AGENT_CONTEXT_DIR, 'blueprints'));
     const existingOnboardingReport = await loadOnboardingReportIfExists(resolvedTargetDirectoryPath);
     const projectDetection = await detectProjectContext(resolvedTargetDirectoryPath);
-
     const selectedProfileName = PROFILE_PRESETS[existingOnboardingReport?.selectedProfile]
       ? existingOnboardingReport.selectedProfile
       : 'balanced';
@@ -167,6 +204,34 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     const includeCiGuardrails = typeof existingOnboardingReport?.ciGuardrailsEnabled === 'boolean'
       ? existingOnboardingReport.ciGuardrailsEnabled
       : true;
+    const uiScopeSignals = await detectUiScopeSignals({
+      targetDirectoryPath: resolvedTargetDirectoryPath,
+      selectedStackFileName,
+      selectedBlueprintFileName,
+      projectScopeKey: existingOnboardingReport?.projectScope?.key || null,
+      projectScopeSourceLabel: 'onboarding project scope',
+    });
+    const packageManifest = uiScopeSignals.packageManifest;
+    const designContractPaths = ['docs/DESIGN.md', 'docs/design-intent.json'];
+    const missingDesignContractPaths = [];
+
+    for (const designContractPath of designContractPaths) {
+      const absoluteDesignContractPath = path.join(resolvedTargetDirectoryPath, ...designContractPath.split('/'));
+      if (!(await pathExists(absoluteDesignContractPath))) {
+        missingDesignContractPaths.push(designContractPath);
+      }
+    }
+    const shouldSeedDesignIntentOnApply = uiScopeSignals.isUiScopeLikely
+      && missingDesignContractPaths.includes('docs/design-intent.json');
+    const designIntentSeedContent = shouldSeedDesignIntentOnApply
+      ? buildUpgradeDesignIntentSeed({
+        targetDirectoryPath: resolvedTargetDirectoryPath,
+        packageManifest,
+        selectedStackFileName,
+        selectedBlueprintFileName,
+        uiScopeSignals,
+      })
+      : null;
 
     const detectionMajorConstraints = buildExistingProjectMajorConstraints();
     const detectionTransparency = {
@@ -288,6 +353,21 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
       console.log('Recommendation: regenerate docs with init --scaffold-docs or update the files manually to match the latest template version.');
     }
 
+    if (uiScopeSignals.isUiScopeLikely && missingDesignContractPaths.length > 0) {
+      console.log('\n[WARN] UI/frontend scope was detected, but the dynamic design contract is incomplete:');
+      for (const missingDesignContractPath of missingDesignContractPaths) {
+        console.log(`- Missing ${missingDesignContractPath}`);
+      }
+      if (uiScopeSignals.signalReasons.length > 0) {
+        console.log(`- Detection signals: ${uiScopeSignals.signalReasons.join('; ')}`);
+      }
+      if (shouldSeedDesignIntentOnApply) {
+        console.log('- Planned seed on apply: docs/design-intent.json');
+      }
+      console.log('Recommendation: create or refresh docs/DESIGN.md and docs/design-intent.json before allowing UI implementation work.');
+      console.log('Upgrade synchronizes governance assets and can seed docs/design-intent.json, but it does not author project-specific docs/DESIGN.md automatically.');
+    }
+
     if (upgradeOptions.dryRun) {
       console.log('\nDry run enabled. No files were modified.');
       return;
@@ -310,6 +390,15 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
         pruneManagedSurface: upgradeOptions.pruneManagedSurface === true,
         managedSurfacePlan,
       });
+      const supplementalCreatedFileNames = [];
+
+      if (shouldSeedDesignIntentOnApply && designIntentSeedContent) {
+        const docsDirectoryPath = path.join(resolvedTargetDirectoryPath, 'docs');
+        const designIntentTargetPath = path.join(docsDirectoryPath, 'design-intent.json');
+        await ensureDirectory(docsDirectoryPath);
+        await fs.writeFile(designIntentTargetPath, designIntentSeedContent, 'utf8');
+        supplementalCreatedFileNames.push('docs/design-intent.json');
+      }
 
       await fs.writeFile(currentRulesPath, plannedRulesContent, 'utf8');
       await fs.writeFile(path.join(resolvedTargetDirectoryPath, '.windsurfrules'), plannedRulesContent, 'utf8');
@@ -320,6 +409,7 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
         targetDirectoryPath: resolvedTargetDirectoryPath,
         selectedProfileName,
         selectedProfilePack: existingOnboardingReport?.selectedProfilePack || null,
+        projectScope: existingOnboardingReport?.projectScope || null,
         selectedStackFileName,
         selectedAdditionalStackFileNames,
         selectedBlueprintFileName,
@@ -346,6 +436,12 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
         governanceSyncResult.updatedFiles.forEach((fileName) => console.log(`  [UPDATED] ${fileName}`));
         governanceSyncResult.deletedManagedFiles.forEach((fileName) => console.log(`  [DELETED] ${fileName}`));
       }
+      if (supplementalCreatedFileNames.length > 0) {
+        if (!(governanceSyncResult.updatedFiles.length > 0 || governanceSyncResult.createdFiles.length > 0 || governanceSyncResult.deletedManagedFiles.length > 0)) {
+          console.log('\nDetailed changes:');
+        }
+        supplementalCreatedFileNames.forEach((fileName) => console.log(`  [NEW]     ${fileName} (seed)`));
+      }
 
       console.log('\nRefreshed files: .cursorrules, .windsurfrules, .agent-context/state/onboarding-report.json');
     } catch (error) {

package/lib/cli/compiler.mjs

@@ -37,6 +37,7 @@ export async function writeOnboardingReport({
   selectedProfileName,
   selectedProfilePack,
   selectedPreset,
+  projectScope = null,
   selectedStackFileName,
   selectedAdditionalStackFileNames = [],
   selectedBlueprintFileName,
@@ -70,6 +71,7 @@ export async function writeOnboardingReport({
       }
       : null,
     selectedPreset,
+    projectScope,
     selectedStack: selectedStackFileName,
     selectedAdditionalStacks: selectedAdditionalStackFileNames,
     selectedBlueprint: selectedBlueprintFileName,
@@ -351,6 +353,8 @@ export async function buildCompiledRulesContent({
       'database-schema.md',
       'api-contract.md',
       'flow-overview.md',
+      'DESIGN.md',
+      'design-intent.json',
     ];
 
     for (const candidateFileName of candidateDocFileNames) {
@@ -369,7 +373,7 @@ export async function buildCompiledRulesContent({
         '',
         'Universal SOP hard block policy:',
         '- Stop implementation if docs/architecture-decision-record.md (alias: docs/Architecture-Decision-Record.md) is missing.',
-        '- For UI scope, stop implementation if docs/DESIGN.md is missing.',
+        '- For UI scope, stop implementation if docs/DESIGN.md or docs/design-intent.json is missing.',
         '- Materialize missing docs first, then continue coding.',
         '',
         'These docs were generated during project initialization and reflect the architecture,',
@@ -402,7 +406,7 @@ export async function buildCompiledRulesContent({
         '- Hard block: do not write application code until docs/project-brief.md and docs/architecture-decision-record.md exist.',
         '- If docs/project-brief.md is missing, execute bootstrap-project-context prompt immediately.',
         hasBootstrapDesignPrompt
-          ? '- For UI scope: if docs/DESIGN.md is missing, execute bootstrap-design prompt before implementing UI surfaces.'
+          ? '- For UI scope: if docs/DESIGN.md or docs/design-intent.json is missing, execute bootstrap-design prompt before implementing UI surfaces.'
           : '- For UI scope: add a design bootstrap prompt before implementing UI surfaces.',
         '- Save generated docs under docs/ and keep them updated when feature scope changes.',
         'Latest user prompt defines current feature scope and product direction.',