@ryuenn3123/agentic-senior-core 4.3.2 → 4.3.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agent-context/prompts/bootstrap-design.md +56 -222
- package/.agent-context/rules/api-docs.md +17 -126
- package/.agent-context/rules/api-versioning.md +9 -86
- package/.agent-context/rules/architecture.md +18 -136
- package/.agent-context/rules/background-jobs.md +9 -85
- package/.agent-context/rules/config-and-flags.md +8 -71
- package/.agent-context/rules/database-design.md +9 -65
- package/.agent-context/rules/docker-runtime.md +9 -62
- package/.agent-context/rules/efficiency-vs-hype.md +7 -37
- package/.agent-context/rules/error-handling.md +8 -33
- package/.agent-context/rules/event-driven.md +8 -34
- package/.agent-context/rules/frontend-architecture.md +22 -140
- package/.agent-context/rules/git-workflow.md +8 -77
- package/.agent-context/rules/microservices.md +8 -36
- package/.agent-context/rules/migrations.md +8 -76
- package/.agent-context/rules/observability.md +7 -60
- package/.agent-context/rules/performance.md +8 -28
- package/.agent-context/rules/realtime.md +7 -22
- package/.agent-context/rules/resilience.md +9 -69
- package/.agent-context/rules/security.md +9 -64
- package/.agent-context/rules/testing.md +8 -34
- package/AGENTS.md +11 -18
- package/README.md +1 -1
- package/lib/cli/adaptive-context/catalog.mjs +1 -6
- package/lib/cli/commands/audit-design-anti-repeat.mjs +26 -185
- package/lib/cli/commands/init/project-context.mjs +0 -41
- package/lib/cli/commands/init.mjs +12 -41
- package/lib/cli/commands/upgrade.mjs +12 -35
- package/lib/cli/compiler.mjs +5 -81
- package/lib/cli/preflight.mjs +0 -21
- package/lib/cli/project-scaffolder/constants.mjs +1 -1
- package/lib/cli/project-scaffolder/design-contract.mjs +3 -45
- package/lib/cli/project-scaffolder/prompt-builders.mjs +18 -161
- package/lib/cli/project-scaffolder/storage.mjs +0 -9
- package/lib/cli/project-scaffolder.mjs +0 -1
- package/package.json +1 -1
- package/scripts/frontend-usability-audit.mjs +4 -45
- package/scripts/release-gate/constants.mjs +1 -0
- package/scripts/release-gate/static-checks.mjs +0 -36
- package/scripts/validate/config.mjs +20 -144
- package/scripts/validate/coverage-checks.mjs +2 -12
- package/scripts/validate/file-structure.mjs +165 -0
- package/scripts/validate/markdown-content.mjs +109 -0
- package/scripts/validate/project-metadata.mjs +166 -0
- package/scripts/validate.mjs +42 -435
- package/.agent-context/prompts/research-design.md +0 -160
- package/lib/cli/commands/upgrade/design-intent-seed.mjs +0 -46
- package/lib/cli/project-scaffolder/design-contract/research-dossier-migration.mjs +0 -190
|
@@ -23,7 +23,6 @@ import {
|
|
|
23
23
|
import { buildStructureFirstSeedSignals, shouldBootstrapDesignDocument } from './design-contract/seed-signals.mjs';
|
|
24
24
|
import { FORBIDDEN_PATTERN_SIGNALS } from './design-contract/signal-vocab.mjs';
|
|
25
25
|
import { buildConceptualAnchorSection } from './design-contract/sections/conceptual-anchor.mjs';
|
|
26
|
-
import { buildResearchDossierMetadata } from './design-contract/research-dossier-migration.mjs';
|
|
27
26
|
import {
|
|
28
27
|
buildAccessibilityPolicySection,
|
|
29
28
|
buildAiSafeUiAuditSection,
|
|
@@ -135,7 +134,7 @@ function buildDesignIntentContractObject({
|
|
|
135
134
|
},
|
|
136
135
|
designFlexibilityPolicy: {
|
|
137
136
|
mode: 'locked-outcomes-flexible-expression',
|
|
138
|
-
contractRole: 'Use docs/
|
|
137
|
+
contractRole: 'Use docs/DESIGN.md as review invariants and handoff structure, not as a frozen visual recipe unless the user explicitly locks a decision.',
|
|
139
138
|
lockedOutcomeTypes: [
|
|
140
139
|
'confirmed-user-goals',
|
|
141
140
|
'repo-evidence-and-runtime-constraints',
|
|
@@ -161,7 +160,6 @@ function buildDesignIntentContractObject({
|
|
|
161
160
|
},
|
|
162
161
|
conceptualAnchor: buildConceptualAnchorSection(),
|
|
163
162
|
researchDossier: {
|
|
164
|
-
metadata: buildResearchDossierMetadata(),
|
|
165
163
|
sourceFreshness: {
|
|
166
164
|
status: 'agent-must-complete-before-ui-implementation',
|
|
167
165
|
freshnessAnchorDate: 'session-current-date',
|
|
@@ -241,7 +239,7 @@ function buildDesignIntentContractObject({
|
|
|
241
239
|
seedValuesRequireCalibration: true,
|
|
242
240
|
},
|
|
243
241
|
tokenSystem: {
|
|
244
|
-
sourceOfTruth: 'docs/
|
|
242
|
+
sourceOfTruth: 'docs/DESIGN.md',
|
|
245
243
|
taxonomyOrder: ['primitive', 'semantic', 'component'],
|
|
246
244
|
primitiveColorSpace: 'OKLCH',
|
|
247
245
|
requireSemanticAliases: true,
|
|
@@ -343,7 +341,7 @@ function buildDesignIntentContractObject({
|
|
|
343
341
|
],
|
|
344
342
|
requiredDesignSections: DESIGN_REQUIRED_SECTIONS,
|
|
345
343
|
implementation: {
|
|
346
|
-
requiredDeliverables: ['docs/DESIGN.md'
|
|
344
|
+
requiredDeliverables: ['docs/DESIGN.md'],
|
|
347
345
|
requireDesignRationale: true,
|
|
348
346
|
requireDistinctVisualDirection: true,
|
|
349
347
|
requireMachineReadableContract: true,
|
|
@@ -367,46 +365,6 @@ function buildDesignIntentContractObject({
|
|
|
367
365
|
};
|
|
368
366
|
}
|
|
369
367
|
|
|
370
|
-
export function buildDesignIntentSeedFromSignals({
|
|
371
|
-
projectName,
|
|
372
|
-
projectDescription,
|
|
373
|
-
primaryDomain,
|
|
374
|
-
features = [],
|
|
375
|
-
initContext,
|
|
376
|
-
status = 'seed-needs-design-synthesis',
|
|
377
|
-
supplementalFields = {},
|
|
378
|
-
}) {
|
|
379
|
-
const designIntentContract = buildDesignIntentContractObject({
|
|
380
|
-
projectName,
|
|
381
|
-
projectDescription,
|
|
382
|
-
primaryDomain,
|
|
383
|
-
features,
|
|
384
|
-
initContext,
|
|
385
|
-
status,
|
|
386
|
-
supplementalFields,
|
|
387
|
-
});
|
|
388
|
-
const validationErrors = validateDesignIntentContract(designIntentContract);
|
|
389
|
-
|
|
390
|
-
if (validationErrors.length > 0) {
|
|
391
|
-
throw new Error(`Invalid design intent contract seed: ${validationErrors.join(' ')}`);
|
|
392
|
-
}
|
|
393
|
-
|
|
394
|
-
return `${JSON.stringify(designIntentContract, null, 2)}\n`;
|
|
395
|
-
}
|
|
396
|
-
|
|
397
|
-
export function buildDesignIntentSeed({
|
|
398
|
-
discoveryAnswers,
|
|
399
|
-
initContext,
|
|
400
|
-
}) {
|
|
401
|
-
return buildDesignIntentSeedFromSignals({
|
|
402
|
-
projectName: discoveryAnswers.projectName,
|
|
403
|
-
projectDescription: discoveryAnswers.projectDescription,
|
|
404
|
-
primaryDomain: discoveryAnswers.primaryDomain,
|
|
405
|
-
features: discoveryAnswers.features,
|
|
406
|
-
initContext,
|
|
407
|
-
status: 'seed-needs-design-synthesis',
|
|
408
|
-
});
|
|
409
|
-
}
|
|
410
368
|
|
|
411
369
|
/**
|
|
412
370
|
* Public schema index. Lists the field and signal names that this aggregator
|
|
@@ -2,7 +2,6 @@ import { toTitleCase } from '../utils.mjs';
|
|
|
2
2
|
import {
|
|
3
3
|
PROJECT_DOC_SYNTHESIS_PROMPT_VERSION,
|
|
4
4
|
} from './constants.mjs';
|
|
5
|
-
import { buildDesignIntentSeed } from './design-contract.mjs';
|
|
6
5
|
|
|
7
6
|
function buildDockerStrategyExecutionBlock(dockerStrategy) {
|
|
8
7
|
const selectedDockerStrategy = String(dockerStrategy || '').trim();
|
|
@@ -124,10 +123,6 @@ export function buildDesignBootstrapPrompt({
|
|
|
124
123
|
initContext,
|
|
125
124
|
docsLanguage,
|
|
126
125
|
}) {
|
|
127
|
-
const designIntentSeed = buildDesignIntentSeed({
|
|
128
|
-
discoveryAnswers,
|
|
129
|
-
initContext,
|
|
130
|
-
});
|
|
131
126
|
|
|
132
127
|
return [
|
|
133
128
|
'# Bootstrap Prompt: Dynamic Design Contract Synthesis',
|
|
@@ -136,143 +131,28 @@ export function buildDesignBootstrapPrompt({
|
|
|
136
131
|
'',
|
|
137
132
|
'You are the Lead UI/UX Art Director for this project.',
|
|
138
133
|
'Create a dynamic design contract, not a fixed stylistic template.',
|
|
139
|
-
'Use imperative, compact, mechanical rules.',
|
|
140
134
|
'',
|
|
141
135
|
'## Mission',
|
|
142
136
|
`Author docs/DESIGN.md in ${docsLanguage.toUpperCase()} language with strong art direction and engineering-ready guidance.`,
|
|
143
|
-
'Keep docs/design-intent.json synchronized as the machine-readable source of design intent.',
|
|
144
137
|
'',
|
|
145
138
|
'## Deliverables',
|
|
146
139
|
'1. docs/DESIGN.md',
|
|
147
|
-
'2. docs/design-intent.json',
|
|
148
140
|
'',
|
|
149
|
-
'##
|
|
150
|
-
'
|
|
151
|
-
'
|
|
152
|
-
'
|
|
153
|
-
'
|
|
154
|
-
'5. Token Architecture and Alias Strategy',
|
|
155
|
-
'6. Responsive Strategy and Cross-Viewport Adaptation Matrix',
|
|
156
|
-
'7. Motion and Interaction Rules',
|
|
157
|
-
'8. Component Language and Morphology',
|
|
158
|
-
'9. Context Hygiene and Source Boundaries',
|
|
159
|
-
'10. Accessibility Non-Negotiables',
|
|
160
|
-
'11. Anti-Patterns to Avoid',
|
|
161
|
-
'12. Implementation Notes for Future UI Tasks',
|
|
141
|
+
'## Design Direction Process',
|
|
142
|
+
'Follow `.agent-context/prompts/bootstrap-design.md` for the three-step design direction:',
|
|
143
|
+
'1. Name your defaults (three temptations and why each flattens this product)',
|
|
144
|
+
'2. Choose a concrete anchor (googleable, specific, not a generic quality word)',
|
|
145
|
+
'3. Record creative commitments (typography, palette, motion, composition)',
|
|
162
146
|
'',
|
|
163
|
-
'##
|
|
164
|
-
'1.
|
|
165
|
-
'2.
|
|
166
|
-
'3.
|
|
167
|
-
'4.
|
|
168
|
-
'5.
|
|
169
|
-
'6.
|
|
170
|
-
'7.
|
|
171
|
-
'8.
|
|
172
|
-
'9. derivedTokenLogic',
|
|
173
|
-
'10. motionPaletteDecision',
|
|
174
|
-
'11. aiSafeUiAudit',
|
|
175
|
-
'12. productionContentPolicy',
|
|
176
|
-
'13. libraryResearchStatus',
|
|
177
|
-
'14. libraryDecisions',
|
|
178
|
-
'15. mathSystems',
|
|
179
|
-
'16. tokenSystem',
|
|
180
|
-
'17. colorTruth',
|
|
181
|
-
'18. crossViewportAdaptation',
|
|
182
|
-
'19. motionSystem',
|
|
183
|
-
'20. componentMorphology',
|
|
184
|
-
'21. accessibilityPolicy',
|
|
185
|
-
'22. designExecutionPolicy',
|
|
186
|
-
'23. designExecutionHandoff',
|
|
187
|
-
'24. reviewRubric',
|
|
188
|
-
'25. contextHygiene',
|
|
189
|
-
'26. forbiddenPatterns',
|
|
190
|
-
'27. requiredDesignSections',
|
|
191
|
-
'28. implementation',
|
|
192
|
-
'29. researchDossier',
|
|
193
|
-
'30. repoEvidence when onboarding or detector evidence exists',
|
|
194
|
-
'',
|
|
195
|
-
'## Mechanical Gates',
|
|
196
|
-
'0. Read `.agent-context/prompts/research-design.md` first. Sections 3 (Category Code Identification), 4 (Morphological Exploration), and 5 (Anchor Candidates) are gates: each must produce an auditable artifact before UI implementation.',
|
|
197
|
-
'0a. Complete the Live Source Freshness Gate from research-design.md before claiming a pattern, library, browser feature, accessibility requirement, or interaction style is current. Use the session current date as the rolling freshness reference; modern means relative to that date, not a fixed calendar range.',
|
|
198
|
-
'0b. Keep research vocabulary internal: evidence, dossier, anchor, category-code, morphology, rename-test, and source-freshness labels guide decisions but must not leak into UI copy, public-facing docs, or final user-facing rationale unless the user asks for the research trace.',
|
|
199
|
-
'1. Do not copy external style guides.',
|
|
200
|
-
'2. Do not anchor the final design language to famous products, benchmark visuals, or external reference surfaces.',
|
|
201
|
-
'3. Do not choose final style, library, palette, typography, motion, or layout from this offline scaffold.',
|
|
202
|
-
'4. Use repo evidence, active brief, current docs, and current official docs for technology choices.',
|
|
203
|
-
'5. Keep UI-only requests context-isolated; load frontend rules first.',
|
|
204
|
-
'6. Preserve Design continuity is opt-in. Use current repo evidence unless the user approves continuity.',
|
|
205
|
-
'7. Treat prior website memory, unrelated project aesthetics, remembered screenshots, and old design docs as tainted unless approved.',
|
|
206
|
-
'8. Use primitive, semantic, and component tokens. Component tokens must consume semantic aliases.',
|
|
207
|
-
'9. Encode colorTruth in perceptual terms. Hex values are implementation derivatives.',
|
|
208
|
-
'10. Define viewport mutation rules for mobile, tablet, and desktop. Shrinking desktop is failure.',
|
|
209
|
-
'11. Keep structured execution representation-first: surface plan, component graph, content-priority map, viewport mutation plan, and interaction-state matrix.',
|
|
210
|
-
'12. Make design-intent.json carry designExecutionPolicy and designExecutionHandoff, not prose-only policy.',
|
|
211
|
-
'12a. Make design-intent.json carry designFlexibilityPolicy so locked outcomes, candidate moves, and flexible expression axes stay separate.',
|
|
212
|
-
'13. Keep semantic review focused on contract fidelity, distinctiveness, hierarchy, state behavior, and viewport mutation.',
|
|
213
|
-
'14. Treat WCAG 2.2 AA as the hard floor. Use APCA only as advisory tuning.',
|
|
214
|
-
'15. Cover focus visibility, focus appearance, target size, accessible authentication, keyboard access, and dynamic status/state access.',
|
|
215
|
-
'16. Do not depend on screenshot capture, browser automation, or image diffs as the default quality path.',
|
|
216
|
-
'17. Make one memorable visual bet before code.',
|
|
217
|
-
'18. Do not ship AI-safe UI, decorative grid, line, scanline, or calibration-mark wallpaper, generic SaaS gradients, or default component-kit styling without product rationale.',
|
|
218
|
-
'19. Use visually exploratory, product-derived palettes while preserving WCAG contrast and status clarity.',
|
|
219
|
-
'20. Complete the AI color audit before code.',
|
|
220
|
-
'21. Treat motion, 3D, canvas, WebGL, scroll choreography, and modern animation libraries as first-class options.',
|
|
221
|
-
'22. If motion or spatial UI is omitted, document the product-fit reason and replacement interaction quality.',
|
|
222
|
-
'23. If the user supplies research files, library lists, screenshots, articles, or benchmark notes, read them as candidate evidence and verify technology claims.',
|
|
223
|
-
'23a. User-provided concepts are first-class constraints: support, refine, or challenge them with evidence; do not override them with trend defaults unless a product, accessibility, technical, or evidence conflict is recorded.',
|
|
224
|
-
'24. If no user-supplied research or reference exists, activate the Dynamic Avant-Garde Anchor Engine before coding; old design docs do not count as research.',
|
|
225
|
-
'25. In Dynamic Avant-Garde mode, consider three high-variance anchors, discard the two safest or most predictable options, and output only the chosen anchor.',
|
|
226
|
-
'26. Reject final anchors named dashboard, portal, cards, admin panel, SaaS shell, web app shell, or minimalist interface.',
|
|
227
|
-
'27. Reject anchors described only as modern, clean, premium, expressive, minimal, or bold.',
|
|
228
|
-
'27a. Do not default anchors to room, darkroom, counting room, control room, war room, studio, lab, cockpit, or command center unless the product genuinely depends on that physical place model.',
|
|
229
|
-
'27b. Prefer artifacts, custody flows, instruments, data behaviors, material systems, editorial systems, service rituals, or interaction mechanisms over "where the interface lives".',
|
|
230
|
-
'28. Set conceptualAnchor.anchorReference and make derivedTokenLogic.anchorReference match exactly.',
|
|
231
|
-
'29. Fill derivedTokenLogic before code. If a token cannot trace to anchorReference, revise it.',
|
|
232
|
-
'29a. Lock semantic roles before exact values. Do not freeze fonts, color primitives, radius, shadows, or component-kit theme treatment unless repo evidence, accessibility validation, implementation constraints, or explicit user approval requires it.',
|
|
233
|
-
'30. Research current official docs before importing any new UI-related library.',
|
|
234
|
-
'31. Do not default to shadcn/ui, Tailwind-only, native-only, or any component kit by habit, and do not avoid them out of guardrail fear; choose the UI foundation from product fit, accessibility, interaction quality, runtime constraints, and official docs.',
|
|
235
|
-
'32. If research is unavailable, set libraryResearchStatus to pending-verification and use native CSS, browser APIs, or existing dependencies only when they can preserve the intended ambition.',
|
|
236
|
-
'33. Do not reject modern lightweight libraries solely because they add a dependency; package count or vague performance fear is not a blocker by itself.',
|
|
237
|
-
'33a. Tailwind-first is valid only when the stack, token model, and team workflow support it; pure Tailwind, vanilla CSS, shadcn/ui, or any component kit is not neutral by default and not forbidden by default.',
|
|
238
|
-
'33b. For fresh framework projects, prefer official setup commands when official docs show they create the supported project shape; manual file assembly requires a repo, prototype, learning, or architecture reason.',
|
|
239
|
-
'34. Define reviewRubric and require genericity findings to name the actual drift signal.',
|
|
240
|
-
'35. Separate taste from failure. Bold accessible work is valid.',
|
|
241
|
-
'36. For zero-based redesign, create visualResetStrategy and reset composition, hierarchy, palette/typography, motion or interaction, and responsive information architecture.',
|
|
242
|
-
'37. Treat productionContentPolicy as blocking: remove visible testing, demo, sample, placeholder, lorem, TODO, coming soon, and scaffold copy unless it is a real product state.',
|
|
243
|
-
'38. Do not make core user workflows terminal-only unless the product is explicitly a CLI, developer tool, or operational runbook.',
|
|
244
|
-
'39. Separate required experience outcomes from candidate implementation moves. Candidate signature moves are proposals until product evidence, accessibility, or user approval makes them required.',
|
|
245
|
-
'40. Translate conceptual anchors non-literally first. Do not turn anchor artifacts into required chrome, decorative props, wallpaper, or theme objects unless they serve a named product function.',
|
|
246
|
-
'41. Use external websites and benchmark examples as candidate evidence for constraints, mechanics, and quality bars only; do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture.',
|
|
247
|
-
'',
|
|
248
|
-
'## Research-Design Brief Gates (research-design.md)',
|
|
249
|
-
'41a. Live Source Freshness Gate: record researchDossier.sourceFreshness and evidenceTable[] with claim, sourceUrl, sourceType, publishedOrUpdatedAt, fetchedAt, confidence, and decisionImpact. Use current official docs or primary release notes for implementation claims. Trend, category-code, and visual-language claims prefer sources published or materially updated within the last 24 months from the current date. Older sources must be labeled old-timeless and may support durable principles only.',
|
|
250
|
-
'42. Section 3 — Category Code Identification: list at least three category codes per product surface in `conceptualAnchor.categoryCodes.candidateEntries`. Each entry must record `description`, `specificityEvidence`, `categoryDefaultReason`, and `rejectionNote`. The specificity floor is: a reader unfamiliar with the project must be able to visualize a specific aesthetic direction from the text alone, without seeing the UI and without knowing the product name. Reject placeholder phrases like "clean typography", "modern color palette", or "smooth animations". Anti-leakage rule: listing a cliche identifies a trap, not a target; the example cliches in the brief are not aesthetic candidates for any project. If the project pattern-matches a common AI-safe default (dev-tool dark slate, AI-startup purple-pink gradient, health-app mint, SaaS admin three-card KPI, marketing-site three-tile hero), name that cliche in `candidateEntries` with an explicit rejection note.',
|
|
251
|
-
'43. Section 4 — Morphological Exploration: build a 5x5 or 6x5 matrix in `conceptualAnchor.morphologicalExploration`. Choose 5 or 6 dimensions and 5 values per dimension. Do not seed the matrix with the Section 3 category codes as values. Highlight the selected combination, and ALSO highlight at least one uncomfortable combination that feels instinctively wrong but can be argued with product logic. The uncomfortable combination must record `combinationLabel`, `discomfortReason`, and `productLogicJustification`. If you cannot produce an uncomfortable-but-arguable combination, the dimensions are too narrow; widen at least one and regenerate.',
|
|
252
|
-
'44. Section 5 — Anchor Candidates: produce exactly five entries in `conceptualAnchor.anchorCandidates.candidates`. Each candidate must record `anchorReference`, `conceptualFamily`, `jobFit`, `hierarchyImplication`, `densityImplication`, `typeImplication`, `stateLanguage`, `motionImplication`, `whatItRulesOut`, `renameTest`, and `categoryCodeOverlap`.',
|
|
253
|
-
'45. Strengthened rename test: rename the product to three genuinely different categories that are remote from each other and from the actual product. Pick fresh test categories per anchor; do not reuse the same triple across every anchor. Record the three test categories explicitly in the dossier so a human reviewer can audit them. Score the result: 0/3 coherent equals STRONG PASS, 1/3 equals PASS, 2/3 equals REVISE, 3/3 equals DISCARD. Never select an anchor with verdict DISCARD; revise REVISE candidates until they fail in at least 2 of 3 categories.',
|
|
254
|
-
'46. Make `conceptualAnchor.anchorReference` and `derivedTokenLogic.anchorReference` match the selected anchor exactly. The selected anchor must have verdict STRONG PASS or PASS.',
|
|
255
|
-
'',
|
|
256
|
-
'## Creative Ambition Floor',
|
|
257
|
-
'Before implementation, the design contract must name one authored visual bet, one product-derived palette move, one signature motion/spatial/interaction behavior, and one morphology or composition choice that would not appear in a generic AI template.',
|
|
258
|
-
'The ambition floor is not a fixed aesthetic. Quiet, dense, utilitarian, or text-heavy interfaces are allowed when the product requires them, but they still need a project-specific visual decision and a real reason for omitting richer motion, 3D, canvas, WebGL, scroll choreography, or animation libraries.',
|
|
259
|
-
'Measurement, calibration, crop, route, timeline, and inspection marks may be used only as task-bound overlays or control affordances. They must not become page wallpaper, hero texture, or first-output background filler.',
|
|
260
|
-
'Use reduced-motion fallbacks instead of suppressing motion.',
|
|
261
|
-
'',
|
|
262
|
-
'## Token Derivation Audit',
|
|
263
|
-
'Before implementation, docs/design-intent.json must include derivedTokenLogic.anchorReference plus colorDerivationSource, spacingDerivationSource, typographyDerivationSource, motionDerivationSource, colorSpace, spatialBaseUnit, typeScaleMethod, motionBudget, and validationRule.',
|
|
264
|
-
'Every semantic token role must be explainable from anchorReference. If the rationale is only looks good, common practice, modern default, or framework default, derive the token again before UI code.',
|
|
265
|
-
'Keep exact primitive values flexible until repo evidence, accessibility validation, implementation constraints, or explicit user approval locks them.',
|
|
266
|
-
'',
|
|
267
|
-
'## Implementation Craft Layer',
|
|
268
|
-
'Record explicit CSS craft decisions before UI code: color space and commitment level, fluid typography method, spacing base unit, motion budget, and the default CSS reflex this project rejects.',
|
|
269
|
-
'Prefer OKLCH, tinted neutrals, clamp() type scales, transform/opacity motion, and responsive recomposition when supported by the stack; preserve existing design-system tokens and document fallbacks instead of forcing rewrites.',
|
|
270
|
-
'',
|
|
271
|
-
'## Library Research Protocol',
|
|
272
|
-
'If web search is available, verify every new UI, animation, scroll, 3D, canvas, chart, icon, styling, or primitive library against current official docs and record source URL, fetched date, stable compatible version, purpose, risk, and fallback.',
|
|
273
|
-
'If web search is unavailable or fails, set libraryResearchStatus to pending-verification, record LIBRARY_TO_VERIFY notes, and use native CSS, browser APIs, or already-present project dependencies only when they can preserve the intended ambition until verification is possible.',
|
|
274
|
-
'Select UI foundations dynamically. Use ready-made primitives or component kits for mechanics when they fit, but replace library-default visual language with project-specific composition, tokens, motion, state treatment, and morphology.',
|
|
275
|
-
'For fresh projects, compare the user-constrained or strongest-fit framework against at least one plausible alternative when no framework is explicitly selected. Do not let Next.js or any familiar web stack win by pattern frequency.',
|
|
147
|
+
'## Hard Rules',
|
|
148
|
+
'1. Do not copy external style guides or anchor to famous product surfaces.',
|
|
149
|
+
'2. Do not choose final style, library, palette, typography, or motion from this offline scaffold.',
|
|
150
|
+
'3. Use repo evidence, active brief, current docs, and current official docs for technology choices.',
|
|
151
|
+
'4. WCAG 2.2 AA is the hard floor. APCA is advisory perceptual tuning only.',
|
|
152
|
+
'5. Research current official docs before importing any new UI-related library.',
|
|
153
|
+
'6. Do not default to any component kit by habit, and do not avoid them when they fit.',
|
|
154
|
+
'7. Keep research vocabulary internal; evidence, anchor, and category-code labels must not appear in public-facing docs.',
|
|
155
|
+
'8. Treat production content as blocking: remove demo, placeholder, lorem, TODO, and scaffold copy.',
|
|
276
156
|
'',
|
|
277
157
|
'## Project Inputs',
|
|
278
158
|
`- Project name: ${discoveryAnswers.projectName}`,
|
|
@@ -282,34 +162,11 @@ export function buildDesignBootstrapPrompt({
|
|
|
282
162
|
`- Runtime constraint: ${initContext.stackFileName === 'agent-decision-runtime.md' ? 'agent recommendation required before coding' : toTitleCase(initContext.stackFileName)}`,
|
|
283
163
|
`- Architecture constraint: ${initContext.blueprintFileName === 'agent-decision-architecture.md' ? 'agent recommendation required before coding' : toTitleCase(initContext.blueprintFileName)}`,
|
|
284
164
|
'',
|
|
285
|
-
'## Seed Machine Contract',
|
|
286
|
-
'Refine this scaffold seed instead of discarding it. Keep the structural fields that are already valid, but replace all placeholder expressive direction with agent-chosen decisions grounded in repo evidence, the active brief, and live official docs when technology choices matter.',
|
|
287
|
-
'```json',
|
|
288
|
-
designIntentSeed.trim(),
|
|
289
|
-
'```',
|
|
290
|
-
'',
|
|
291
165
|
'## Required Execution',
|
|
292
|
-
'1. Create or update docs/DESIGN.md with complete content.',
|
|
293
|
-
'2.
|
|
294
|
-
'3.
|
|
295
|
-
'4.
|
|
296
|
-
'5. Encode structured design execution as policy: representation strategy, surface plan, component graph, content-priority map, viewport mutation plan, interaction-state matrix, semantic review focus, and structured handoff requirements.',
|
|
297
|
-
'6. Encode an explicit structured handoff inside docs/design-intent.json: surface plan, component graph, content-priority map, viewport mutation plan, interaction-state matrix, task-flow narrative, and signature move rationale.',
|
|
298
|
-
'7. Encode a stable review rubric: required dimensions, genericity signals, valid bold signals, and reporting rules that separate taste from real failure.',
|
|
299
|
-
'7a. Encode designFlexibilityPolicy and designExecutionHandoff.expressionFlexibility so future agents know what is locked and what can change.',
|
|
300
|
-
'8. Make the handoff executable without screenshot dependency. The contract must still guide high-precision UI generation from repo evidence and changed code alone.',
|
|
301
|
-
'9. Preserve repoEvidence.designEvidenceSummary when onboarding or detector evidence exists instead of discarding it.',
|
|
302
|
-
'10. If repoEvidence.designEvidenceSummary.structuredInspection exists, use it as stronger evidence for class surfaces, inline style bypasses, and expression-backed UI structure before defaulting to generic assumptions.',
|
|
303
|
-
'11. Ensure both files stay project-specific, dynamic, and practical for implementation and review. The seed may guide structure, but it must not decide style offline.',
|
|
304
|
-
'12. Keep visualResetStrategy in the machine-readable handoff so reset-language tasks cannot quietly become restyles of the previous UI.',
|
|
305
|
-
'13. Preserve externalResearchIntake so user-provided research becomes reviewed evidence without turning into an offline style or dependency preset.',
|
|
306
|
-
'14. Preserve conceptualAnchor so prompt-only UI work has one cohesive non-template concept instead of a mixed collection of bold but unrelated visual decisions.',
|
|
307
|
-
'15. Record conceptualAnchor.agentResearchMode, specificReferencePoint, signatureMotion, typographicDecision, visualRiskBudget, motionRiskBudget, and cohesionChecks so the final UI cannot quietly fall back to a timid dashboard/admin mental model.',
|
|
308
|
-
'15a. Record conceptualAnchor.categoryCodes.candidateEntries (Section 3 of research-design.md), conceptualAnchor.morphologicalExploration with selectedCombination and uncomfortableCombination (Section 4), and conceptualAnchor.anchorCandidates.candidates with full renameTest results (Section 5) before UI implementation.',
|
|
309
|
-
'16. Preserve derivedTokenLogic, libraryResearchStatus, and libraryDecisions so token choices and dependency uncertainty stay visible before implementation.',
|
|
310
|
-
'16a. Preserve designFlexibilityPolicy so the machine contract guides consistency without freezing literal anchor artifacts, exact token primitives, or component-kit visual language.',
|
|
311
|
-
'17. Preserve productionContentPolicy so UI output is ship-ready and not a testing-looking scaffold.',
|
|
312
|
-
'18. After the contract exists, use it as a first-class source for future UI tasks.',
|
|
166
|
+
'1. Create or update docs/DESIGN.md with complete content covering: design intent, audience signals, visual direction, color/typography/spacing decisions, responsive strategy, motion rules, component language, accessibility non-negotiables, and anti-patterns.',
|
|
167
|
+
'2. Make the contract executable without screenshot dependency.',
|
|
168
|
+
'3. Preserve repoEvidence.designEvidenceSummary when onboarding or detector evidence exists.',
|
|
169
|
+
'4. After the contract exists, use it as a first-class source for future UI tasks.',
|
|
313
170
|
'',
|
|
314
171
|
].join('\n');
|
|
315
172
|
}
|
|
@@ -14,7 +14,6 @@ import {
|
|
|
14
14
|
resolveProjectDocTargets,
|
|
15
15
|
} from './discovery.mjs';
|
|
16
16
|
import {
|
|
17
|
-
buildDesignIntentSeed,
|
|
18
17
|
shouldBootstrapDesignDocument,
|
|
19
18
|
} from './design-contract.mjs';
|
|
20
19
|
import {
|
|
@@ -76,14 +75,6 @@ export async function generateProjectDocumentation(
|
|
|
76
75
|
});
|
|
77
76
|
await fs.writeFile(path.join(promptsDirectoryPath, designPromptFileName), designPromptContent, 'utf8');
|
|
78
77
|
generatedPromptFileNames.push(designPromptFileName);
|
|
79
|
-
|
|
80
|
-
const designIntentSeedFileName = 'design-intent.json';
|
|
81
|
-
const designIntentSeedContent = buildDesignIntentSeed({
|
|
82
|
-
discoveryAnswers,
|
|
83
|
-
initContext: synthesisContext,
|
|
84
|
-
});
|
|
85
|
-
await fs.writeFile(path.join(docsDirectoryPath, designIntentSeedFileName), designIntentSeedContent, 'utf8');
|
|
86
|
-
materializedFileNames.push(designIntentSeedFileName);
|
|
87
78
|
}
|
|
88
79
|
|
|
89
80
|
return {
|
package/package.json
CHANGED
|
@@ -50,30 +50,6 @@ const REQUIRED_ARCHITECTURE_CHECKLIST_SNIPPETS = [
|
|
|
50
50
|
];
|
|
51
51
|
|
|
52
52
|
const REQUIRED_FRONTEND_RULE_SNIPPETS = [
|
|
53
|
-
'Frontend Design and Interaction Boundaries',
|
|
54
|
-
'Load this rule for UI-facing work. Keep the loaded surface small.',
|
|
55
|
-
'## FE-001: Activation',
|
|
56
|
-
'## FE-002: Authority',
|
|
57
|
-
'Treat `.agent-context/` as design governance authority.',
|
|
58
|
-
'Treat `README.md` as public and developer overview, setup, usage, and user-facing context only',
|
|
59
|
-
'Do not choose final style, framework, palette, typography, layout paradigm, or animation library offline.',
|
|
60
|
-
'Keep design continuity opt-in.',
|
|
61
|
-
'Repo evidence outranks memory residue.',
|
|
62
|
-
'Use the current date as the freshness anchor for design research.',
|
|
63
|
-
'Treat user-provided concepts as first-class constraints.',
|
|
64
|
-
'## FE-003: Required Design Contract',
|
|
65
|
-
'## FE-004: Anti-Generic UI Gate',
|
|
66
|
-
'Do not ship interchangeable dashboard chrome',
|
|
67
|
-
'Do not let repeated surfaces share one visual treatment by habit',
|
|
68
|
-
'Use the rename test:',
|
|
69
|
-
'decorative geometry are invalid as wallpaper',
|
|
70
|
-
'## FE-005: Dynamic Anchor Gate',
|
|
71
|
-
'## FE-006: Motion, Palette, and 3D',
|
|
72
|
-
'Treat motion, 3D, WebGL, canvas, scroll choreography, and animation libraries as first-class options.',
|
|
73
|
-
'Prefer visually exploratory, product-derived palettes while preserving WCAG contrast and status clarity.',
|
|
74
|
-
'## FE-008: Responsive Mutation',
|
|
75
|
-
'Responsive quality is not scale-only.',
|
|
76
|
-
'container queries',
|
|
77
53
|
'## FE-009: Accessibility',
|
|
78
54
|
'WCAG 2.2 AA is the hard floor.',
|
|
79
55
|
'APCA is advisory perceptual tuning only.',
|
|
@@ -84,26 +60,10 @@ const REQUIRED_FRONTEND_RULE_SNIPPETS = [
|
|
|
84
60
|
];
|
|
85
61
|
|
|
86
62
|
const REQUIRED_BOOTSTRAP_DESIGN_SNIPPETS = [
|
|
87
|
-
'
|
|
88
|
-
'
|
|
89
|
-
'
|
|
90
|
-
'
|
|
91
|
-
'repoEvidence.designEvidenceSummary',
|
|
92
|
-
'research current official docs',
|
|
93
|
-
'Responsive design means recomposition, not resizing.',
|
|
94
|
-
'Implementation Craft Layer',
|
|
95
|
-
'agent-chosen visual direction',
|
|
96
|
-
'viewport mutation rules',
|
|
97
|
-
'WCAG 2.2 AA is the hard floor',
|
|
98
|
-
'APCA may be used only as advisory perceptual tuning',
|
|
99
|
-
'unresearched dependency choices',
|
|
100
|
-
'Dynamic UI Foundation Selection',
|
|
101
|
-
'Adaptive Research Freshness',
|
|
102
|
-
'fixed calendar range',
|
|
103
|
-
'research vocabulary internal',
|
|
104
|
-
'A new dependency, package count, or vague performance concern is not a blocker by itself.',
|
|
105
|
-
'default component-kit styling without product rationale',
|
|
106
|
-
'genericity findings that cannot name the exact drift signal',
|
|
63
|
+
'WCAG 2.2 AA is the hard compliance floor',
|
|
64
|
+
'Name Your Defaults',
|
|
65
|
+
'Choose an Anchor',
|
|
66
|
+
'Creative Commitments'
|
|
107
67
|
];
|
|
108
68
|
|
|
109
69
|
const REQUIRED_UI_DESIGN_JUDGE_SNIPPETS = [
|
|
@@ -135,7 +95,6 @@ const REQUIRED_INSTRUCTIONS_SNIPPETS = [
|
|
|
135
95
|
'External references, prior-chat memory, unrelated-project visuals, and remembered screenshots are tainted',
|
|
136
96
|
'WCAG 2.2 AA as the hard compliance floor',
|
|
137
97
|
'APCA as advisory perceptual tuning only',
|
|
138
|
-
'Do not require screenshot capture as a baseline dependency',
|
|
139
98
|
];
|
|
140
99
|
|
|
141
100
|
const REQUIRED_DESIGN_EVIDENCE_SNIPPETS = [
|
|
@@ -44,6 +44,7 @@ export const REQUIRED_BACKEND_REVIEW_CHECKLIST_SNIPPETS = [
|
|
|
44
44
|
'Backend/API governance was applied through global domain rules',
|
|
45
45
|
];
|
|
46
46
|
|
|
47
|
+
export const REQUIRED_RELEASE_VERSION = '4.3.4';
|
|
47
48
|
export const REQUIRED_REFACTOR_PROMPT_SNIPPETS = [
|
|
48
49
|
'Enforce backend universal principles: no clever hacks, no premature abstraction, readability over brevity.',
|
|
49
50
|
'Prioritize maintainability over compressed one-liners.',
|
|
@@ -15,10 +15,6 @@ import {
|
|
|
15
15
|
VERSION_PATTERN,
|
|
16
16
|
} from './constants.mjs';
|
|
17
17
|
import { pushResult, readText } from './runtime.mjs';
|
|
18
|
-
import {
|
|
19
|
-
buildDesignIntentSeedFromSignals,
|
|
20
|
-
validateDesignContractCompleteness,
|
|
21
|
-
} from '../../lib/cli/project-scaffolder.mjs';
|
|
22
18
|
|
|
23
19
|
export function runStaticReleaseChecks(results, diagnostics) {
|
|
24
20
|
const packageJsonPath = 'package.json';
|
|
@@ -70,38 +66,6 @@ export function runStaticReleaseChecks(results, diagnostics) {
|
|
|
70
66
|
pushResult(results, true, 'history-v18', 'Project history includes V1.8 release track');
|
|
71
67
|
}
|
|
72
68
|
|
|
73
|
-
try {
|
|
74
|
-
const designIntentSeed = JSON.parse(buildDesignIntentSeedFromSignals({
|
|
75
|
-
projectName: 'Release Gate UI Contract',
|
|
76
|
-
projectDescription: 'Validates deterministic UI design contract completeness before release',
|
|
77
|
-
primaryDomain: 'Web application',
|
|
78
|
-
initContext: {
|
|
79
|
-
stackFileName: 'agent-decision-runtime.md',
|
|
80
|
-
blueprintFileName: 'agent-decision-architecture.md',
|
|
81
|
-
},
|
|
82
|
-
// Seed status so `tokenContinuityClassification: pending-research`
|
|
83
|
-
// is a valid placeholder. This probe asserts seed-shape completeness,
|
|
84
|
-
// not active-contract behavior; an agent or user fills the contract
|
|
85
|
-
// with anchor-derived / continuity-retained / newly-introduced once
|
|
86
|
-
// the dossier is filled.
|
|
87
|
-
status: 'seed-needs-design-synthesis',
|
|
88
|
-
}));
|
|
89
|
-
const designContractIssues = validateDesignContractCompleteness(designIntentSeed);
|
|
90
|
-
|
|
91
|
-
if (designContractIssues.length === 0) {
|
|
92
|
-
pushResult(results, true, 'ui-design-contract-completeness', 'Design intent seed includes deterministic token derivation and library verification gates');
|
|
93
|
-
} else {
|
|
94
|
-
pushResult(
|
|
95
|
-
results,
|
|
96
|
-
false,
|
|
97
|
-
'ui-design-contract-completeness',
|
|
98
|
-
`Design intent seed completeness issues: ${designContractIssues.join('; ')}`
|
|
99
|
-
);
|
|
100
|
-
}
|
|
101
|
-
} catch (designContractError) {
|
|
102
|
-
const designContractMessage = designContractError instanceof Error ? designContractError.message : 'Unknown design contract error';
|
|
103
|
-
pushResult(results, false, 'ui-design-contract-completeness', `Cannot validate design intent seed: ${designContractMessage}`);
|
|
104
|
-
}
|
|
105
69
|
|
|
106
70
|
const requiredOperationsFiles = [
|
|
107
71
|
'.agent-context/review-checklists/architecture-review.md',
|