@ryuenn3123/agentic-senior-core 6.16.0 → 6.16.2
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/.agents/plugins/agentic-senior-core/.codex-plugin/plugin.json +1 -1
- package/.agents/plugins/agentic-senior-core/plugin.json +1 -1
- package/.agents/plugins/agentic-senior-core/skills/asc/SKILL.md +10 -2
- package/.agents/plugins/agentic-senior-core/skills/asc-reference/SKILL.md +26 -13
- package/.agents/plugins/agentic-senior-core/skills/asc-test/SKILL.md +33 -15
- package/.agents/plugins/agentic-senior-core/skills/asc-ui/SKILL.md +55 -32
- package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/color-surfaces.md +3 -0
- package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/typography.md +5 -0
- package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/modes/persuade.md +27 -0
- package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/redesign-audit.md +36 -13
- package/bin/agentic-senior-core.js +7 -0
- package/gemini-extension.json +1 -1
- package/lib/cli/commands/preview.mjs +206 -0
- package/package.json +1 -1
- package/plugin.yaml +1 -1
|
@@ -79,6 +79,14 @@ asc uninstall # Clean up adapter files and hooks
|
|
|
79
79
|
|
|
80
80
|
## 6. On-Demand Reference Library
|
|
81
81
|
|
|
82
|
-
|
|
82
|
+
> [!IMPORTANT]
|
|
83
|
+
> **Reference Path Resolution:**
|
|
84
|
+
> Reference files do NOT reside in the user workspace root. They are located adjacent to this `SKILL.md` file:
|
|
85
|
+
> `<skill_directory>/references/<file>.md`
|
|
86
|
+
> Prepend this skill's directory path when calling `read_file`.
|
|
87
|
+
|
|
88
|
+
When authoring, refactoring, or tailoring skills, you MUST call `read_file` on `references/writing-skills.md` before generating skill files:
|
|
89
|
+
|
|
90
|
+
| Topic / Requirement | Mandatory Reference Path |
|
|
83
91
|
|---|---|
|
|
84
|
-
| Authoring skills, trigger descriptions & 150-line routers |
|
|
92
|
+
| Authoring skills, trigger descriptions & 150-line routers | `references/writing-skills.md` |
|
|
@@ -28,16 +28,28 @@ Every backend and infrastructure change must satisfy these baseline invariants:
|
|
|
28
28
|
|
|
29
29
|
---
|
|
30
30
|
|
|
31
|
-
## 2.
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
31
|
+
## 2. Architecture Pre-Flight Gate & Reference Library (BLOCKING)
|
|
32
|
+
|
|
33
|
+
> [!IMPORTANT]
|
|
34
|
+
> **Reference Path Resolution:**
|
|
35
|
+
> Reference files do NOT reside in the user workspace root. They are located adjacent to this `SKILL.md` file:
|
|
36
|
+
> `<skill_directory>/references/<file>.md`
|
|
37
|
+
> Prepend this skill's directory path when calling `read_file`.
|
|
38
|
+
|
|
39
|
+
Before modifying database schemas, writing API contracts, drafting Dockerfiles, or writing retry logic:
|
|
40
|
+
1. **Mandatory Ingestion (BLOCKING GATE):** Call `read_file` on the matching domain reference BEFORE drafting plans or changing code:
|
|
41
|
+
- REST semantics, cursor pagination, RFC 9457, GraphQL ➔ `references/api.md`
|
|
42
|
+
- B-Tree indexing, N+1 queries, row locking, expand-and-contract migrations ➔ `references/database.md`
|
|
43
|
+
- Multi-stage Docker, non-root users, 12-factor env, health probes ➔ `references/infrastructure.md`
|
|
44
|
+
- Timeouts, jittered backoff, circuit breakers, hard vs. soft dependencies ➔ `references/resilience.md`
|
|
45
|
+
*Do NOT generate migrations, endpoint signatures, or network clients until this reference is loaded.*
|
|
46
|
+
|
|
47
|
+
| Domain | Scope & Trigger | Mandatory Reference Path |
|
|
36
48
|
|---|---|---|
|
|
37
|
-
| **API Design** | REST semantics, cursor pagination, RFC 9457, GraphQL DataLoader
|
|
38
|
-
| **Database** | B-Tree indexing, N+1 prevention, row locking (`FOR UPDATE`), expand-and-contract |
|
|
39
|
-
| **Infrastructure** | Multi-stage Docker, non-root users, 12-factor env validation, liveness/readiness |
|
|
40
|
-
| **Resilience** |
|
|
49
|
+
| **API Design** | REST semantics, cursor pagination, RFC 9457 problem details, GraphQL DataLoader | `references/api.md` |
|
|
50
|
+
| **Database** | B-Tree indexing, N+1 prevention, row locking (`FOR UPDATE`), expand-and-contract migrations | `references/database.md` |
|
|
51
|
+
| **Infrastructure** | Multi-stage Docker, non-root users, 12-factor env validation, liveness/readiness probes | `references/infrastructure.md` |
|
|
52
|
+
| **Resilience** | Outbound timeouts, full jitter backoff, circuit breakers, hard vs soft dependencies | `references/resilience.md` |
|
|
41
53
|
|
|
42
54
|
---
|
|
43
55
|
|
|
@@ -55,7 +67,8 @@ Before writing integration code, classify external services:
|
|
|
55
67
|
## 4. Verification & Handoff Sweep
|
|
56
68
|
|
|
57
69
|
Before completing backend or infrastructure work:
|
|
58
|
-
1.
|
|
59
|
-
2. Verify
|
|
60
|
-
3.
|
|
61
|
-
4.
|
|
70
|
+
1. Confirm constraints from the loaded `references/*.md` file were applied in contracts, schemas, and configurations.
|
|
71
|
+
2. Verify query execution plan (`EXPLAIN ANALYZE`) for newly introduced SQL queries.
|
|
72
|
+
3. Verify all outbound network calls have timeout parameters.
|
|
73
|
+
4. Validate startup configuration fails fast on missing environment variables.
|
|
74
|
+
5. Confirm migrations run cleanly in both `up` and `down` directions.
|
|
@@ -21,9 +21,25 @@ Every feature, bugfix, or refactor must follow the Red-Green-Refactor sequence:
|
|
|
21
21
|
|
|
22
22
|
---
|
|
23
23
|
|
|
24
|
-
## 2. The Verification Gate
|
|
25
|
-
|
|
26
|
-
|
|
24
|
+
## 2. The Verification Gate & Pre-Flight Ingestion (BLOCKING)
|
|
25
|
+
|
|
26
|
+
> [!IMPORTANT]
|
|
27
|
+
> **Reference Path Resolution:**
|
|
28
|
+
> Reference files do NOT reside in the user workspace root. They are located adjacent to this `SKILL.md` file:
|
|
29
|
+
> `<skill_directory>/references/<file>.md`
|
|
30
|
+
> Prepend this skill's directory path when calling `read_file`.
|
|
31
|
+
|
|
32
|
+
Before writing tests, running suites, or claiming verification:
|
|
33
|
+
1. **Mandatory Ingestion (BLOCKING GATE):** Call `read_file` on the tier reference matching your testing requirement BEFORE taking action:
|
|
34
|
+
- Writing unit tests / TDD cycle ➔ `references/tdd-cycle.md`
|
|
35
|
+
- Behavior testing, boundary isolation, mocks/fakes ➔ `references/test-design.md`
|
|
36
|
+
- Playwright browser tests, locators, page objects ➔ `references/e2e-playwright.md`
|
|
37
|
+
- Acceptance criteria, UAT checklists, edge case quads ➔ `references/uat.md`
|
|
38
|
+
- Bug reproduction, root-cause verification, regression proof ➔ `references/regression-proof.md`
|
|
39
|
+
- Flaky tests, timing race conditions, 50-run stress loop ➔ `references/flaky-tests.md`
|
|
40
|
+
*Do NOT write test assertions or declare claims until this reference is loaded.*
|
|
41
|
+
|
|
42
|
+
2. **Never make a claim regarding test status without fresh execution evidence:**
|
|
27
43
|
|
|
28
44
|
```
|
|
29
45
|
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
|
|
@@ -81,24 +97,26 @@ Select the lowest testing tier that validates the requirement:
|
|
|
81
97
|
|
|
82
98
|
## 5. On-Demand Reference Library
|
|
83
99
|
|
|
84
|
-
|
|
100
|
+
> [!IMPORTANT]
|
|
101
|
+
> **Resolution Note:** All paths below are relative to this `SKILL.md` file's parent folder (`.../skills/asc-test/`). Prepend this skill's directory path when calling `read_file`.
|
|
85
102
|
|
|
86
|
-
|
|
|
103
|
+
| Testing Domain / Trigger | Mandatory Reference Path |
|
|
87
104
|
|---|---|
|
|
88
|
-
| Red-Green-Refactor mechanics & whole-suite checks |
|
|
89
|
-
| Behavior testing, boundary isolation & mocking |
|
|
90
|
-
| Playwright E2E, reconnaissance & locator hierarchy |
|
|
91
|
-
| Given/When/Then acceptance criteria & edge case quad |
|
|
92
|
-
| 3-step bugfix verification & regression proof |
|
|
93
|
-
| Flakiness root causes & 50-run stress loop |
|
|
105
|
+
| Red-Green-Refactor mechanics & whole-suite checks | `references/tdd-cycle.md` |
|
|
106
|
+
| Behavior testing, boundary isolation & mocking | `references/test-design.md` |
|
|
107
|
+
| Playwright E2E, reconnaissance & locator hierarchy | `references/e2e-playwright.md` |
|
|
108
|
+
| Given/When/Then acceptance criteria & edge case quad | `references/uat.md` |
|
|
109
|
+
| 3-step bugfix verification & regression proof | `references/regression-proof.md` |
|
|
110
|
+
| Flakiness root causes & 50-run stress loop | `references/flaky-tests.md` |
|
|
94
111
|
|
|
95
112
|
---
|
|
96
113
|
|
|
97
114
|
## 6. Verification & Handoff Sweep
|
|
98
115
|
|
|
99
116
|
Before declaring any coding or testing task complete:
|
|
100
|
-
1. **
|
|
101
|
-
2. **
|
|
102
|
-
3. **
|
|
103
|
-
4. **
|
|
117
|
+
1. **Reference Compliance:** Confirm constraints from the loaded `references/*.md` file were applied.
|
|
118
|
+
2. **Regression Proof:** For bugfixes, confirm the test failed without the fix and passes with it.
|
|
119
|
+
3. **Whole-Suite Run:** Execute the full test suite (`ascx npm test` or project test runner); confirm exit code 0.
|
|
120
|
+
4. **No Assertions Weakened:** Verify no existing test assertions were deleted or commented out to simulate success.
|
|
121
|
+
5. **Hermetic State:** Ensure tests clean up temporary files, database records, and environment variables.
|
|
104
122
|
|
|
@@ -33,59 +33,82 @@ Every UI edit must satisfy these 15 rules without exception:
|
|
|
33
33
|
|
|
34
34
|
---
|
|
35
35
|
|
|
36
|
-
## 2. Pre-Flight & Material Inventory
|
|
37
|
-
|
|
38
|
-
Before declaring markup,
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
36
|
+
## 2. Pre-Flight & Material Inventory (BLOCKING GATE)
|
|
37
|
+
|
|
38
|
+
Before declaring markup, drafting redesign plans, or inspecting user code:
|
|
39
|
+
|
|
40
|
+
1. **Locate Skill Directory & References (MANDATORY):**
|
|
41
|
+
Reference files do NOT reside in the user workspace root. They are located adjacent to this `SKILL.md` file:
|
|
42
|
+
`<skill_directory>/references/<category>/<file>.md`
|
|
43
|
+
Identify the path of this `SKILL.md` file (provided by host/tooling) and resolve all reference paths relative to it.
|
|
44
|
+
|
|
45
|
+
2. **Step 1 — Surface Mode Ingestion (MANDATORY GATE):**
|
|
46
|
+
Classify the surface and execute `read_file` on the corresponding mode reference BEFORE inspecting files or writing code:
|
|
47
|
+
- Dashboards, settings, data tables, developer tools ➔ `references/modes/operate.md`
|
|
48
|
+
- Landing pages, pricing tiers, conversion flows ➔ `references/modes/persuade.md`
|
|
49
|
+
- Documentation, changelogs, knowledge bases ➔ `references/modes/read.md`
|
|
50
|
+
- Showcases, portfolios, interactive galleries ➔ `references/modes/experience.md`
|
|
51
|
+
*Do NOT proceed until you have read the mode reference into context.*
|
|
52
|
+
|
|
53
|
+
3. **Step 2 — Secondary Craft Ingestion:**
|
|
54
|
+
Execute `read_file` on at least one relevant craft reference for your task from Section 5 (e.g. `references/craft/typography.md`, `references/craft/color-surfaces.md`, or `references/divergence.md`).
|
|
55
|
+
|
|
56
|
+
4. **Step 3 — Workspace Material Inventory:**
|
|
57
|
+
Only AFTER loading the mode reference, inspect the workspace:
|
|
58
|
+
- **Design Tokens:** Read project CSS variables, Tailwind configuration, or existing components in `components/` or `ui/`. If `DESIGN.md` exists, read it (read-only). Never create or edit persistent checkpoint files.
|
|
59
|
+
- **Take Material Inventory:**
|
|
60
|
+
- **Real:** Concrete numbers, existing endpoints, actual data attributes.
|
|
61
|
+
- **Pictures:** Actual screenshots and product visual assets.
|
|
62
|
+
- **Absent:** Missing quotes, missing logos, or unverified metrics—these are omitted entirely.
|
|
44
63
|
|
|
45
64
|
---
|
|
46
65
|
|
|
47
66
|
## 3. Surface Modes & Ambition Scaling
|
|
48
67
|
|
|
49
|
-
|
|
68
|
+
Visual posture is governed by the surface type, not product branding. Every surface maps to an enforced mode reference file:
|
|
50
69
|
|
|
51
|
-
- **Operate (`references/modes/operate.md`):**
|
|
52
|
-
- **Persuade (`references/modes/persuade.md`):**
|
|
53
|
-
- **Read (`references/modes/read.md`):**
|
|
54
|
-
- **Experience (`references/modes/experience.md`):**
|
|
70
|
+
- **Operate (`references/modes/operate.md`):** Dense scannability, master-detail rails, `tabular-nums`, inline progressive disclosure.
|
|
71
|
+
- **Persuade (`references/modes/persuade.md`):** 80-word viewport budget, asymmetric posture, single signature element, zero equal-weight 3-card grids.
|
|
72
|
+
- **Read (`references/modes/read.md`):** 65–75ch measure (`max-w-prose`), dual-rail navigation, syntax-highlighted code blocks.
|
|
73
|
+
- **Experience (`references/modes/experience.md`):** Receding interface chrome, full-bleed visual canvas, tactile exploration.
|
|
55
74
|
|
|
56
75
|
---
|
|
57
76
|
|
|
58
77
|
## 4. Scope Classification: Refine vs. Redesign
|
|
59
78
|
|
|
60
|
-
|
|
61
|
-
- **
|
|
79
|
+
Never split the difference into cosmetic polish on a discarded look:
|
|
80
|
+
- **Polish / Refinement:** Preserves layout structure, DOM hierarchy, and design tokens. Resolves contrast, missing state quad, microcopy, and lint issues.
|
|
81
|
+
- **Restyle:** Preserves layout geometry. Replaces color tokens, typographic scales, corner radiuses, and elevation shadows.
|
|
82
|
+
- **Full Redesign:** Replaces entire spatial geometry and posture. Mandatory decoupled protocol: extract data/contracts first, discard old DOM, author standalone preview (`asc preview <path>`), build fresh geometry, re-bind dynamic data.
|
|
62
83
|
|
|
63
84
|
---
|
|
64
85
|
|
|
65
86
|
## 5. On-Demand Reference Library
|
|
66
87
|
|
|
67
|
-
|
|
88
|
+
> [!IMPORTANT]
|
|
89
|
+
> **Resolution Note:** All paths below are relative to this `SKILL.md` file's parent folder (`.../skills/asc-ui/`). When calling `read_file`, prepend this skill's directory path.
|
|
68
90
|
|
|
69
|
-
|
|
|
91
|
+
| Target Domain / Task Requirement | Mandatory Reference Path |
|
|
70
92
|
|---|---|
|
|
71
|
-
| Waivable defaults & waiver syntax |
|
|
72
|
-
| Typography, line-height & tabular numbers |
|
|
73
|
-
| Color tokens, 60-30-10 & elevation |
|
|
74
|
-
| Micro-interactions & GPU motion |
|
|
75
|
-
| Native surfaces (selection, caret, scrollbars) |
|
|
76
|
-
| 50% reduction, active verbs & i18n |
|
|
77
|
-
| Responsive reflow, dvh & touch targets |
|
|
78
|
-
| WCAG 2.2 AA contrast & keyboard operability |
|
|
79
|
-
| The Data State Quad & mutation feedback |
|
|
80
|
-
| Anti-convergence, 3 Waves of Tells & Mirror Test |
|
|
81
|
-
| Structured UI audit matrix |
|
|
93
|
+
| Waivable defaults & waiver syntax | `references/reflexes.md` |
|
|
94
|
+
| Typography, line-height & tabular numbers | `references/craft/typography.md` |
|
|
95
|
+
| Color tokens, 60-30-10 & elevation | `references/craft/color-surfaces.md` |
|
|
96
|
+
| Micro-interactions & GPU motion | `references/craft/motion.md` |
|
|
97
|
+
| Native surfaces (selection, caret, scrollbars) | `references/craft/browser-surfaces.md` |
|
|
98
|
+
| 50% reduction, active verbs & i18n | `references/copy-i18n.md` |
|
|
99
|
+
| Responsive reflow, dvh & touch targets | `references/mobile-responsive.md` |
|
|
100
|
+
| WCAG 2.2 AA contrast & keyboard operability | `references/accessibility.md` |
|
|
101
|
+
| The Data State Quad & mutation feedback | `references/states-feedback.md` |
|
|
102
|
+
| Anti-convergence, 3 Waves of Tells & Mirror Test | `references/divergence.md` |
|
|
103
|
+
| Structured UI audit matrix | `references/redesign-audit.md` |
|
|
82
104
|
|
|
83
105
|
---
|
|
84
106
|
|
|
85
107
|
## 6. Verification & Handoff Sweep
|
|
86
108
|
|
|
87
109
|
Before completing any UI task, run this mechanical check:
|
|
88
|
-
1. **
|
|
89
|
-
2. **
|
|
90
|
-
3. **
|
|
91
|
-
4. **
|
|
110
|
+
1. **Reference Compliance:** Confirm constraints from the loaded `references/modes/<mode>.md` and craft references were strictly applied.
|
|
111
|
+
2. **State Quad:** Loading skeleton, empty state, error with retry, and populated data are all handled.
|
|
112
|
+
3. **Pending Feedback:** Buttons disable and display feedback during ongoing mutations.
|
|
113
|
+
4. **Contrast & Focus:** Verify keyboard tab flow and high-contrast `:focus-visible` styling.
|
|
114
|
+
5. **Lint Check:** Verify changes against `hooks/lib/known-ui-slop-patterns.json`.
|
package/.agents/plugins/agentic-senior-core/skills/asc-ui/references/craft/color-surfaces.md
CHANGED
|
@@ -25,6 +25,9 @@ Grounded in: Apple HIG, Google Material Design 3, and Refactoring UI Color Strat
|
|
|
25
25
|
- The dedicated brand accent hue.
|
|
26
26
|
- **Accent Exclusivity:** Accent color is reserved strictly for interactive affordances: Primary CTA button, active navigation indicator, unread dot, selected checkbox.
|
|
27
27
|
- **Forbidden:** Never use the accent color as background wallpaper, card borders, or decorative section dividers.
|
|
28
|
+
- **Full-Field Grounding (Anti-Sterile Surface):**
|
|
29
|
+
- To prevent the "sterile white void" trap, at least one major functional region (the Hero Stage, the Signature Canvas, or the Master Header) must own a deep, purposeful surface field (e.g. deep midnight grounding, rich brand tint, or dark canvas container).
|
|
30
|
+
- This establishes an optical center of gravity, preventing the page from looking like an unstyled wireframe.
|
|
28
31
|
|
|
29
32
|
---
|
|
30
33
|
|
|
@@ -13,6 +13,11 @@ Grounded in: Refactoring UI, Bringhurst's The Elements of Typographic Style, and
|
|
|
13
13
|
- **Weight Contrast Before Size Inflation:**
|
|
14
14
|
- Build strong typographic hierarchy by varying font weights (`font-bold` vs `font-normal`) and contrast tokens (`text-foreground` vs `text-muted-foreground`) before jumping to oversized font sizes.
|
|
15
15
|
- A clean 24px `font-bold` title paired with a 14px `text-muted-foreground` subtitle establishes clearer hierarchy than inflating the title to 48px with identical gray values.
|
|
16
|
+
- **The Generative Scale Contrast Floor ($Display \ge 3.5\times Body$):**
|
|
17
|
+
- On landing, marketing, and hero surfaces (`Persuade`), the primary headline must establish an optical scale step over body text:
|
|
18
|
+
- Target: $Display \ge 3.5\times Body$ (e.g. `text-5xl` to `text-7xl` [48px–72px] display vs `text-base` [16px] or `text-sm` [14px] body).
|
|
19
|
+
- Heading leading must be tight: `leading-[1.05]` to `leading-tight`.
|
|
20
|
+
- An under-scaled heading ($< 2.5\times$ body, such as 24px H1) collapses optical gravity and makes marketing pages look like internal memo forms.
|
|
16
21
|
|
|
17
22
|
---
|
|
18
23
|
|
|
@@ -43,6 +43,33 @@ When building or redesigning a Persuade surface, never let the LLM default to th
|
|
|
43
43
|
- If technical documentation, whitepaper, or architectural manifesto $\to$ **Posture 2 (The Monolith Ledger)**.
|
|
44
44
|
- If performance benchmarks, protocol comparisons, or telemetry proof $\to$ **Posture 4 (Kinetic Proof Stream)**.
|
|
45
45
|
|
|
46
|
+
### Structural Blueprints (Enforced DOM Geometries)
|
|
47
|
+
|
|
48
|
+
#### Posture 1: Asymmetric Stage (65/35 Split)
|
|
49
|
+
- **Container:** `grid grid-cols-1 lg:grid-cols-12 gap-12 items-center`
|
|
50
|
+
- **Left Lead (7 cols):** `lg:col-span-7 space-y-6 text-left`
|
|
51
|
+
- Display headline: `text-5xl lg:text-7xl font-bold tracking-tight leading-[1.05]`
|
|
52
|
+
- Subtitle: `text-lg text-muted-foreground max-w-xl`
|
|
53
|
+
- Actions: `flex flex-wrap items-center gap-4 pt-2`
|
|
54
|
+
- **Right Artifact (5 cols):** `lg:col-span-5`
|
|
55
|
+
- Authentic artifact, interactive widget, or live ROI card: `rounded-2xl border border-border/80 bg-card p-6 shadow-sm`
|
|
56
|
+
- Zero equal-weight card grids below.
|
|
57
|
+
|
|
58
|
+
#### Posture 2: The Monolith Ledger
|
|
59
|
+
- **Container:** `max-w-4xl mx-auto px-6 py-16 divide-y divide-border/60`
|
|
60
|
+
- **Tabular Rows:** Each entity or program is a horizontal row: `py-8 grid grid-cols-1 md:grid-cols-12 gap-6 items-baseline`
|
|
61
|
+
- Category / Date: `md:col-span-3 text-xs font-semibold tracking-wider uppercase text-muted-foreground`
|
|
62
|
+
- Heading & Data: `md:col-span-5 text-xl font-bold text-foreground`
|
|
63
|
+
- Detail & Action: `md:col-span-4 text-sm text-muted-foreground`
|
|
64
|
+
|
|
65
|
+
#### Posture 3: Product-Led Canvas
|
|
66
|
+
- **Container:** `flex flex-col items-center text-center max-w-6xl mx-auto px-6 pt-16 pb-20`
|
|
67
|
+
- **Compact Hero Frame:** `max-w-2xl space-y-4 mb-10`
|
|
68
|
+
- Headline: `text-4xl sm:text-6xl font-extrabold tracking-tight`
|
|
69
|
+
- 1-sentence value claim + 1 primary action.
|
|
70
|
+
- **Hero Canvas (70% Viewport Lead):** `w-full rounded-2xl border border-border/80 bg-slate-950 p-2 shadow-2xl`
|
|
71
|
+
- Real interface fragment or live demo canvas dominating the first viewport.
|
|
72
|
+
|
|
46
73
|
---
|
|
47
74
|
|
|
48
75
|
## 3. Anti-Cardocalypse & Visual Pacing
|
|
@@ -4,21 +4,44 @@ Modifying an existing interface requires clear intent. Audits must provide actio
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
## 1.
|
|
7
|
+
## 1. Scope Classification: The 3 Redesign Depths
|
|
8
8
|
|
|
9
|
-
Before touching code, explicitly classify the
|
|
9
|
+
Never split the difference into cosmetic polish on a discarded look. Before touching code, explicitly classify the depth of work:
|
|
10
10
|
|
|
11
|
-
|
|
|
11
|
+
| Depth | Scope & Intent | What Stays Intact | What Changes |
|
|
12
12
|
|---|---|---|---|
|
|
13
|
-
|
|
|
14
|
-
|
|
|
13
|
+
| **`polish`** | Resolve bugs, contrast, microcopy, states. | Layout structure, DOM hierarchy, and design system tokens. | Padding rhythm, WCAG AA contrast, missing state quad (empty/error/loading), focus rings, microcopy brevity, lint fixes. |
|
|
14
|
+
| **`restyle`** | Upgrade design system without breaking layout. | Layout grid, component hierarchy, and DOM structure. | Color palette (60-30-10), typographic scale, corner radiuses, elevation shadows, button and input styles. |
|
|
15
|
+
| **`full`** | Total visual and structural overhaul. | Factual content, data bindings (`$variables`, loops), routes, form handlers. | **Spatial geometry, grid ratios, surface posture, and typography.** Treated as fresh build from subject truth. |
|
|
15
16
|
|
|
16
|
-
|
|
17
|
-
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 2. The Decoupled Redesign Protocol (For Full Redesigns)
|
|
20
|
+
|
|
21
|
+
When executing a **Full Redesign** on an existing template or page (`.blade.php`, `.tsx`, `.vue`, `.html`), editing in-place is forbidden because the AI's attention mechanism will anchor to the old DOM structure. Execute this 4-step decoupled sequence:
|
|
22
|
+
|
|
23
|
+
1. **Step 1: Extract Data Contracts & Factual Inventory**
|
|
24
|
+
- Parse the incumbent file and extract all dynamic variables, loops, route helpers, form submission endpoints, and real text/assets into a clean data list.
|
|
25
|
+
- Separate product truth (names, prices, verified claims) from discarded markup.
|
|
26
|
+
2. **Step 2: Isolate / Discard Old Markup**
|
|
27
|
+
- Treat the old layout as an anti-reference. Do not perform incremental class swapping on it.
|
|
28
|
+
3. **Step 3: Author Standalone HTML Prototype & Preview**
|
|
29
|
+
- Create an ephemeral standalone prototype in the brain directory: `<appDataDir>/brain/<id>/preview.html`.
|
|
30
|
+
- Select 1 of the 4 Structural Postures (`references/modes/persuade.md` or `operate.md`).
|
|
31
|
+
- Use Tailwind via CDN and realistic sample data.
|
|
32
|
+
- Run zero-dependency visual capture:
|
|
33
|
+
```bash
|
|
34
|
+
asc preview <path_to_preview.html>
|
|
35
|
+
```
|
|
36
|
+
Inspect the captured image at `%TEMP%/asc-preview-active.png` (or pass `--open` to view in OS browser). Verify typographic scale ($Display \ge 3.5\times Body$) and full-field grounding.
|
|
37
|
+
4. **Step 4: Re-inject Data Contracts into Production**
|
|
38
|
+
- Transfer the proven clean geometry into the project file (`welcome.blade.php`, `Page.tsx`).
|
|
39
|
+
- Re-bind the dynamic data loops, Blade/React variables, and event handlers.
|
|
40
|
+
- Confirm project test suite and linters pass cleanly.
|
|
18
41
|
|
|
19
42
|
---
|
|
20
43
|
|
|
21
|
-
##
|
|
44
|
+
## 3. Structured Audit Matrix
|
|
22
45
|
|
|
23
46
|
When auditing an existing interface or PR, generate a structured findings table categorized by severity:
|
|
24
47
|
|
|
@@ -41,29 +64,29 @@ When auditing an existing interface or PR, generate a structured findings table
|
|
|
41
64
|
|
|
42
65
|
---
|
|
43
66
|
|
|
44
|
-
##
|
|
67
|
+
## 4. Systematic Audit Checklist
|
|
45
68
|
|
|
46
69
|
Audit screens systematically against four engineering vectors:
|
|
47
70
|
|
|
48
|
-
###
|
|
71
|
+
### 4.1 Ergonomics & Responsiveness
|
|
49
72
|
- [ ] Render at `375px` width (mobile viewport) and `1280px` (desktop viewport).
|
|
50
73
|
- [ ] Verify zero horizontal scrollbars on mobile (`overflow-x: clip`).
|
|
51
74
|
- [ ] Confirm all touch targets meet minimum $44 \times 44\text{px}$ bounding box.
|
|
52
75
|
- [ ] Verify mobile layout uses `dvh` instead of `vh` to prevent browser chrome clipping.
|
|
53
76
|
|
|
54
|
-
###
|
|
77
|
+
### 4.2 Accessibility & Contrast (WCAG 2.2 AA)
|
|
55
78
|
- [ ] Check normal text against backgrounds ($\ge 4.5:1$).
|
|
56
79
|
- [ ] Check input borders, active toggles, and large headings ($\ge 3:1$).
|
|
57
80
|
- [ ] Cycle through entire screen using `Tab` and `Shift+Tab` with mouse disconnected.
|
|
58
81
|
- [ ] Press `Escape` while dialog/modal is open; verify closure and focus restoration.
|
|
59
82
|
|
|
60
|
-
###
|
|
83
|
+
### 4.3 State Quad Coverage
|
|
61
84
|
- [ ] Inspect loading state: does it use proportional skeletons matching final dimensions?
|
|
62
85
|
- [ ] Inspect empty state: is it actionable with a 1-sentence explanation?
|
|
63
86
|
- [ ] Inspect error state: does it diagnose the issue and provide an inline retry button?
|
|
64
87
|
- [ ] Inspect mutation triggers: do buttons lock and display spinners during network latency?
|
|
65
88
|
|
|
66
|
-
###
|
|
89
|
+
### 4.4 Microcopy & Token Hygiene
|
|
67
90
|
- [ ] Run 50% word reduction sweep across headings and explanatory paragraphs.
|
|
68
91
|
- [ ] Confirm all buttons follow `Verb + Noun` grammar.
|
|
69
92
|
- [ ] Verify zero banned buzzwords (*seamless*, *empower*, *robust*).
|
|
@@ -36,6 +36,7 @@ function printUsage() {
|
|
|
36
36
|
console.log(' uninstall Remove ASC adapter files and git hooks from this project');
|
|
37
37
|
console.log(' clean Remove v4 per-project artifacts');
|
|
38
38
|
console.log(' status Show detected IDEs and install hints');
|
|
39
|
+
console.log(' preview Render zero-dependency multi-browser snapshot or preview');
|
|
39
40
|
console.log(' --version Show version');
|
|
40
41
|
console.log(' --help Show this help');
|
|
41
42
|
}
|
|
@@ -90,6 +91,12 @@ async function main() {
|
|
|
90
91
|
return;
|
|
91
92
|
}
|
|
92
93
|
|
|
94
|
+
if (commandArgument === 'preview') {
|
|
95
|
+
const { runPreviewCommand } = await import('../lib/cli/commands/preview.mjs');
|
|
96
|
+
await runPreviewCommand(commandArguments);
|
|
97
|
+
return;
|
|
98
|
+
}
|
|
99
|
+
|
|
93
100
|
console.error(`Unknown command: ${commandArgument}`);
|
|
94
101
|
printUsage();
|
|
95
102
|
exit(1);
|
package/gemini-extension.json
CHANGED
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Zero-dependency Multi-Browser Preview & Headless Snapshot Engine.
|
|
3
|
+
* Detects installed browsers (Brave, Edge, Chrome, Firefox, Vivaldi, Arc)
|
|
4
|
+
* and captures a headless snapshot or opens in the OS default browser.
|
|
5
|
+
*/
|
|
6
|
+
import fs from 'node:fs';
|
|
7
|
+
import path from 'node:path';
|
|
8
|
+
import os from 'node:os';
|
|
9
|
+
import { execSync } from 'node:child_process';
|
|
10
|
+
|
|
11
|
+
export function getBrowserCandidates() {
|
|
12
|
+
const platform = process.platform;
|
|
13
|
+
const candidates = [];
|
|
14
|
+
|
|
15
|
+
if (platform === 'win32') {
|
|
16
|
+
const localAppData = process.env.LOCALAPPDATA || '';
|
|
17
|
+
const programFiles = process.env['ProgramFiles'] || 'C:\\Program Files';
|
|
18
|
+
const programFilesX86 = process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)';
|
|
19
|
+
|
|
20
|
+
candidates.push(
|
|
21
|
+
{
|
|
22
|
+
name: 'Brave Browser',
|
|
23
|
+
family: 'chromium',
|
|
24
|
+
paths: [
|
|
25
|
+
path.join(programFiles, 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'),
|
|
26
|
+
path.join(programFilesX86, 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'),
|
|
27
|
+
path.join(localAppData, 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'),
|
|
28
|
+
]
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
name: 'Microsoft Edge',
|
|
32
|
+
family: 'chromium',
|
|
33
|
+
paths: [
|
|
34
|
+
path.join(programFilesX86, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
|
|
35
|
+
path.join(programFiles, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
|
|
36
|
+
path.join(localAppData, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
|
|
37
|
+
]
|
|
38
|
+
},
|
|
39
|
+
{
|
|
40
|
+
name: 'Google Chrome',
|
|
41
|
+
family: 'chromium',
|
|
42
|
+
paths: [
|
|
43
|
+
path.join(programFiles, 'Google', 'Chrome', 'Application', 'chrome.exe'),
|
|
44
|
+
path.join(programFilesX86, 'Google', 'Chrome', 'Application', 'chrome.exe'),
|
|
45
|
+
path.join(localAppData, 'Google', 'Chrome', 'Application', 'chrome.exe'),
|
|
46
|
+
]
|
|
47
|
+
},
|
|
48
|
+
{
|
|
49
|
+
name: 'Mozilla Firefox',
|
|
50
|
+
family: 'firefox',
|
|
51
|
+
paths: [
|
|
52
|
+
path.join(programFiles, 'Mozilla Firefox', 'firefox.exe'),
|
|
53
|
+
path.join(programFilesX86, 'Mozilla Firefox', 'firefox.exe'),
|
|
54
|
+
]
|
|
55
|
+
},
|
|
56
|
+
{
|
|
57
|
+
name: 'Vivaldi',
|
|
58
|
+
family: 'chromium',
|
|
59
|
+
paths: [
|
|
60
|
+
path.join(localAppData, 'Vivaldi', 'Application', 'vivaldi.exe'),
|
|
61
|
+
path.join(programFiles, 'Vivaldi', 'Application', 'vivaldi.exe'),
|
|
62
|
+
]
|
|
63
|
+
},
|
|
64
|
+
{
|
|
65
|
+
name: 'Arc',
|
|
66
|
+
family: 'chromium',
|
|
67
|
+
paths: [
|
|
68
|
+
path.join(localAppData, 'Arc', 'Arc.exe'),
|
|
69
|
+
]
|
|
70
|
+
}
|
|
71
|
+
);
|
|
72
|
+
} else if (platform === 'darwin') {
|
|
73
|
+
candidates.push(
|
|
74
|
+
{
|
|
75
|
+
name: 'Google Chrome',
|
|
76
|
+
family: 'chromium',
|
|
77
|
+
paths: ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome']
|
|
78
|
+
},
|
|
79
|
+
{
|
|
80
|
+
name: 'Brave Browser',
|
|
81
|
+
family: 'chromium',
|
|
82
|
+
paths: ['/Applications/Brave Browser.app/Contents/MacOS/Brave Browser']
|
|
83
|
+
},
|
|
84
|
+
{
|
|
85
|
+
name: 'Microsoft Edge',
|
|
86
|
+
family: 'chromium',
|
|
87
|
+
paths: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge']
|
|
88
|
+
},
|
|
89
|
+
{
|
|
90
|
+
name: 'Mozilla Firefox',
|
|
91
|
+
family: 'firefox',
|
|
92
|
+
paths: ['/Applications/Firefox.app/Contents/MacOS/firefox']
|
|
93
|
+
},
|
|
94
|
+
{
|
|
95
|
+
name: 'Arc',
|
|
96
|
+
family: 'chromium',
|
|
97
|
+
paths: ['/Applications/Arc.app/Contents/MacOS/Arc']
|
|
98
|
+
}
|
|
99
|
+
);
|
|
100
|
+
} else {
|
|
101
|
+
// Linux
|
|
102
|
+
candidates.push(
|
|
103
|
+
{ name: 'google-chrome', family: 'chromium', commands: ['google-chrome', 'google-chrome-stable'] },
|
|
104
|
+
{ name: 'chromium', family: 'chromium', commands: ['chromium', 'chromium-browser'] },
|
|
105
|
+
{ name: 'brave', family: 'chromium', commands: ['brave-browser', 'brave'] },
|
|
106
|
+
{ name: 'microsoft-edge', family: 'chromium', commands: ['microsoft-edge', 'microsoft-edge-stable', 'msedge'] },
|
|
107
|
+
{ name: 'firefox', family: 'firefox', commands: ['firefox'] }
|
|
108
|
+
);
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
return candidates;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
export function findBrowserExecutable() {
|
|
115
|
+
const candidates = getBrowserCandidates();
|
|
116
|
+
|
|
117
|
+
for (const candidate of candidates) {
|
|
118
|
+
if (candidate.paths) {
|
|
119
|
+
for (const p of candidate.paths) {
|
|
120
|
+
if (fs.existsSync(p)) {
|
|
121
|
+
return { name: candidate.name, family: candidate.family, path: p };
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
} else if (candidate.commands) {
|
|
125
|
+
for (const cmd of candidate.commands) {
|
|
126
|
+
try {
|
|
127
|
+
const resolved = execSync(`which ${cmd} 2>/dev/null`, { encoding: 'utf8' }).trim();
|
|
128
|
+
if (resolved) {
|
|
129
|
+
return { name: candidate.name, family: candidate.family, path: resolved };
|
|
130
|
+
}
|
|
131
|
+
} catch {
|
|
132
|
+
// ignore
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
return null;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
export async function runPreviewCommand(args = []) {
|
|
142
|
+
const targetFile = args.find(a => !a.startsWith('-'));
|
|
143
|
+
const shouldOpen = args.includes('--open');
|
|
144
|
+
const width = 1280;
|
|
145
|
+
const height = 800;
|
|
146
|
+
|
|
147
|
+
if (!targetFile) {
|
|
148
|
+
console.error('Usage: asc preview <html-file> [--open]');
|
|
149
|
+
process.exit(1);
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
const resolvedHtmlPath = path.resolve(process.cwd(), targetFile);
|
|
153
|
+
if (!fs.existsSync(resolvedHtmlPath)) {
|
|
154
|
+
console.error(`File not found: ${resolvedHtmlPath}`);
|
|
155
|
+
process.exit(1);
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
// Single fixed reusable slot in OS temp directory
|
|
159
|
+
const tempDir = os.tmpdir();
|
|
160
|
+
const outputPng = path.join(tempDir, 'asc-preview-active.png');
|
|
161
|
+
|
|
162
|
+
// Open in default OS browser if requested
|
|
163
|
+
if (shouldOpen) {
|
|
164
|
+
const opener = process.platform === 'win32' ? 'start' : process.platform === 'darwin' ? 'open' : 'xdg-open';
|
|
165
|
+
try {
|
|
166
|
+
execSync(`${opener} "" "${resolvedHtmlPath}"`, { stdio: 'ignore' });
|
|
167
|
+
console.log(`[asc preview] Opened in default browser: ${resolvedHtmlPath}`);
|
|
168
|
+
return;
|
|
169
|
+
} catch (err) {
|
|
170
|
+
console.error(`Failed to open default browser: ${err.message}`);
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
// Headless snapshot mode
|
|
175
|
+
const browser = findBrowserExecutable();
|
|
176
|
+
if (!browser) {
|
|
177
|
+
console.warn('[asc preview] No supported headless browser detected (Brave, Edge, Chrome, Firefox). Falling back to OS opener.');
|
|
178
|
+
const opener = process.platform === 'win32' ? 'start' : process.platform === 'darwin' ? 'open' : 'xdg-open';
|
|
179
|
+
execSync(`${opener} "" "${resolvedHtmlPath}"`, { stdio: 'ignore' });
|
|
180
|
+
return;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
try {
|
|
184
|
+
let command;
|
|
185
|
+
if (browser.family === 'chromium') {
|
|
186
|
+
command = `"${browser.path}" --headless --disable-gpu --screenshot="${outputPng}" --window-size=${width},${height} "${resolvedHtmlPath}"`;
|
|
187
|
+
} else if (browser.family === 'firefox') {
|
|
188
|
+
command = `"${browser.path}" -headless -screenshot "${outputPng}" -window-size ${width},${height} "${resolvedHtmlPath}"`;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
execSync(command, { stdio: 'pipe' });
|
|
192
|
+
|
|
193
|
+
if (fs.existsSync(outputPng)) {
|
|
194
|
+
const stat = fs.statSync(outputPng);
|
|
195
|
+
console.log(`[asc preview] Captured via ${browser.name} (${width}x${height}, ${stat.size} bytes)`);
|
|
196
|
+
console.log(`Output: ${outputPng}`);
|
|
197
|
+
} else {
|
|
198
|
+
throw new Error('Screenshot file was not generated');
|
|
199
|
+
}
|
|
200
|
+
} catch (err) {
|
|
201
|
+
console.warn(`[asc preview] Headless snapshot failed: ${err.message}. Falling back to OS opener.`);
|
|
202
|
+
const opener = process.platform === 'win32' ? 'start' : process.platform === 'darwin' ? 'open' : 'xdg-open';
|
|
203
|
+
execSync(`${opener} "" "${resolvedHtmlPath}"`, { stdio: 'ignore' });
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
|
package/package.json
CHANGED
package/plugin.yaml
CHANGED