get-shit-pretty 0.2.0 → 0.3.0

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.
Files changed (21) hide show
  1. package/agents/gsp-critic.md +54 -0
  2. package/agents/gsp-design-engineer.md +2 -0
  3. package/agents/gsp-spec-engineer.md +63 -0
  4. package/agents/gsp-system-architect.md +64 -0
  5. package/agents/gsp-ui-designer.md +69 -0
  6. package/commands/gsp/build.md +29 -3
  7. package/commands/gsp/design.md +41 -10
  8. package/commands/gsp/new-project.md +67 -17
  9. package/commands/gsp/review.md +13 -0
  10. package/commands/gsp/spec.md +25 -4
  11. package/commands/gsp/system.md +59 -3
  12. package/package.json +1 -1
  13. package/prompts/01-design-system-architect.md +35 -3
  14. package/prompts/03-ui-ux-pattern-master.md +11 -1
  15. package/prompts/09-design-to-code-translator.md +9 -0
  16. package/references/chunk-format.md +35 -0
  17. package/templates/codebase-inventory.md +71 -0
  18. package/templates/config.json +3 -0
  19. package/templates/exports-index.md +69 -0
  20. package/templates/phases/system.md +28 -0
  21. package/templates/project.md +6 -0
package/agents/gsp-critic.md CHANGED
@@ -53,3 +53,57 @@ Write critique to `.design/review/CRITIQUE.md`:
53
53
  8. **Alternative Directions** — 2 redesign approaches with descriptions
54
54
  9. **What Works Well** — Specific strengths to preserve
55
55
  </output>
56
+
57
+ <chunked-exports>
58
+ ## Chunked Exports
59
+
60
+ After writing CRITIQUE.md, generate an agent-consumable fix list.
61
+
62
+ ### Output
63
+
64
+ Write `.design/review/exports/review-fixes.md` (~50-100 lines):
65
+
66
+ ```markdown
67
+ # Review Fixes
68
+
69
+ > Phase: Review | Source: [CRITIQUE.md](../CRITIQUE.md) | Generated: {DATE}
70
+
71
+ ---
72
+
73
+ ## Critical Fixes
74
+
75
+ - **[Screen/Component]:** {Issue} → {Concrete fix}
76
+
77
+ ## Important Fixes
78
+
79
+ - **[Screen/Component]:** {Issue} → {Concrete fix}
80
+
81
+ ---
82
+
83
+ ## Related
84
+
85
+ - [CRITIQUE.md](../CRITIQUE.md) — full critique with heuristic scores
86
+ - [accessibility-fixes.md](./accessibility-fixes.md) — WCAG violations
87
+ ```
88
+
89
+ ### Rules
90
+
91
+ - Only include Critical and Important severity — skip Polish items
92
+ - Every fix must name the specific screen or component affected
93
+ - Every fix must include a concrete remediation (not just "improve X")
94
+ - Preserve exact issue descriptions from CRITIQUE.md
95
+ - See `references/chunk-format.md` for standard header, footer, naming, and size rules
96
+
97
+ ### Update INDEX.md
98
+
99
+ Replace `<!-- BEGIN:review -->` … `<!-- END:review -->` in `.design/exports/INDEX.md` with:
100
+
101
+ ```markdown
102
+ <!-- BEGIN:review -->
103
+ | Section | File |
104
+ |---------|------|
105
+ | Review Fixes | [review-fixes.md](../review/exports/review-fixes.md) |
106
+ | Accessibility Fixes | [accessibility-fixes.md](../review/exports/accessibility-fixes.md) |
107
+ <!-- END:review -->
108
+ ```
109
+ </chunked-exports>
package/agents/gsp-design-engineer.md CHANGED
@@ -18,6 +18,8 @@ You adapt your approach based on the `implementation_target`:
18
18
  - **`skip` (no SPECS.md)** — Build directly from SCREENS.md + SYSTEM.md, derive component architecture yourself
19
19
 
20
20
  Write real, copy-paste-ready code. Not pseudocode. Not "implementation left as exercise." Production code.
21
+
22
+ **Chunk-aware mode:** When chunked exports are provided instead of full monoliths (screen chunks, spec chunks, component chunks), work with the focused context. Do not request additional monolith files unless the chunks are insufficient for the task. This keeps your context lean and focused on the specific screen being built.
21
23
  </role>
22
24
 
23
25
  <methodology>
package/agents/gsp-spec-engineer.md CHANGED
@@ -119,3 +119,66 @@ Write specs to `.design/specs/SPECS.md`:
119
119
  5. **Accessibility Specs** — ARIA roles, keyboard navigation, focus management
120
120
  6. **Implementation Notes** — Key decisions, patterns, and constraints
121
121
  </output>
122
+
123
+ <chunked-exports>
124
+ ## Chunked Exports
125
+
126
+ After writing SPECS.md, generate agent-consumable chunks.
127
+
128
+ ### Output structure
129
+
130
+ ```
131
+ .design/specs/exports/
132
+ ├── component-mapping.md
133
+ ├── token-mapping.md
134
+ ├── install-manifest.md (shadcn/rn-reusables only)
135
+ ├── gap-analysis.md (existing target only)
136
+ ├── file-references.md (existing target only)
137
+ └── screens/
138
+ ├── screen-01-spec.md
139
+ ├── screen-02-spec.md
140
+ └── ...
141
+ ```
142
+
143
+ ### Chunk format
144
+
145
+ See `references/chunk-format.md` for standard header, footer, naming, and size rules.
146
+
147
+ ### Rules
148
+
149
+ - **Preserve exact content** from SPECS.md — do not summarize, rewrite, or omit details
150
+ - **Chunk structure varies by `implementation_target`** — use the same conditionals already in your output section
151
+ - **Per-screen spec chunks** link to the corresponding screen design chunk (`../../screens/exports/screen-{NN}-{name}.md`) and component chunks (`../../system/exports/components/{name}.md`)
152
+ - **`install-manifest.md`** only generated for `shadcn` and `rn-reusables` targets
153
+ - **For `existing` target:** generate `gap-analysis.md` and `file-references.md` instead of `install-manifest.md`
154
+ - **Naming:** singular, kebab-case, lowercase
155
+ - **Size target:** 50-200 lines per chunk
156
+ - **Self-contained:** each chunk must be understandable without loading other chunks
157
+
158
+ ### Update INDEX.md
159
+
160
+ After generating chunks, update `.design/exports/INDEX.md`:
161
+
162
+ 1. If INDEX.md doesn't exist, copy it from `templates/exports-index.md`
163
+ 2. Replace everything between `<!-- BEGIN:specs -->` and `<!-- END:specs -->` with populated tables:
164
+
165
+ ```markdown
166
+ <!-- BEGIN:specs -->
167
+ ### Specs
168
+
169
+ | Section | File |
170
+ |---------|------|
171
+ | Component Mapping | [component-mapping.md](../specs/exports/component-mapping.md) |
172
+ | Token Mapping | [token-mapping.md](../specs/exports/token-mapping.md) |
173
+ | Install Manifest | [install-manifest.md](../specs/exports/install-manifest.md) |
174
+
175
+ ### Per-Screen Specs
176
+
177
+ | # | Screen | File |
178
+ |---|--------|------|
179
+ | 01 | Home | [screen-01-spec.md](../specs/exports/screens/screen-01-spec.md) |
180
+ | 02 | Dashboard | [screen-02-spec.md](../specs/exports/screens/screen-02-spec.md) |
181
+ | ... | ... | ... |
182
+ <!-- END:specs -->
183
+ ```
184
+ </chunked-exports>
package/agents/gsp-system-architect.md CHANGED
@@ -54,3 +54,67 @@ Complete W3C Design Tokens format JSON with:
54
54
  - Border radius tokens
55
55
  - Breakpoint tokens
56
56
  </output>
57
+
58
+ <chunked-exports>
59
+ ## Chunked Exports
60
+
61
+ After writing SYSTEM.md and tokens.json, generate agent-consumable chunks.
62
+
63
+ ### Output structure
64
+
65
+ ```
66
+ .design/system/exports/
67
+ ├── foundations/
68
+ │ ├── color-system.md (~100-150 lines)
69
+ │ ├── typography.md
70
+ │ ├── spacing.md
71
+ │ ├── grid.md
72
+ │ ├── elevation.md
73
+ │ └── border-radius.md
74
+ ├── components/
75
+ │ ├── button.md (~50 lines each)
76
+ │ ├── input.md
77
+ │ ├── card.md
78
+ │ └── ... (one per component, singular kebab-case)
79
+ └── principles.md
80
+ ```
81
+
82
+ ### Chunk format
83
+
84
+ See `references/chunk-format.md` for standard header, footer, naming, and size rules.
85
+
86
+ ### Rules
87
+
88
+ - **Preserve exact content** from SYSTEM.md — do not summarize, rewrite, or omit details
89
+ - **Naming:** singular, kebab-case, lowercase. "Buttons" → `button.md`, "Date Picker" → `date-picker.md`
90
+ - **Size target:** 50-200 lines per chunk
91
+ - **Self-contained:** each chunk must be understandable without loading other chunks
92
+ - **Component chunks** must cross-reference the foundations they use (e.g., button.md links to color-system.md, typography.md, spacing.md)
93
+ - **Foundation chunks** link to related foundations (e.g., spacing.md links to grid.md)
94
+
95
+ ### Update INDEX.md
96
+
97
+ After generating chunks, update `.design/exports/INDEX.md`:
98
+
99
+ 1. If INDEX.md doesn't exist, copy it from `templates/exports-index.md`
100
+ 2. Replace everything between `<!-- BEGIN:system -->` and `<!-- END:system -->` with populated tables:
101
+
102
+ ```markdown
103
+ <!-- BEGIN:system -->
104
+ ### Foundations
105
+
106
+ | Foundation | File | Tokens |
107
+ |------------|------|--------|
108
+ | Color System | [color-system.md](../system/exports/foundations/color-system.md) | primary, secondary, semantic, neutral |
109
+ | Typography | [typography.md](../system/exports/foundations/typography.md) | font-family, font-size, line-height |
110
+ | ... | ... | ... |
111
+
112
+ ### Components
113
+
114
+ | Component | File | States | Variants |
115
+ |-----------|------|--------|----------|
116
+ | Button | [button.md](../system/exports/components/button.md) | default, hover, active, disabled, focus, loading | primary, secondary, ghost, destructive |
117
+ | ... | ... | ... | ... |
118
+ <!-- END:system -->
119
+ ```
120
+ </chunked-exports>
package/agents/gsp-ui-designer.md CHANGED
@@ -57,3 +57,72 @@ Write screens to `.design/screens/SCREENS.md`:
57
57
  - **New (local)** — Screen-specific components
58
58
  8. **Designer's Notes** — Key decisions and rationale
59
59
  </output>
60
+
61
+ <chunked-exports>
62
+ ## Chunked Exports
63
+
64
+ After writing SCREENS.md, generate agent-consumable chunks.
65
+
66
+ ### Output structure
67
+
68
+ ```
69
+ .design/screens/exports/
70
+ ├── screen-01-{name}.md (~150-200 lines each)
71
+ ├── screen-02-{name}.md
72
+ ├── ...
73
+ ├── screen-08-{name}.md
74
+ └── shared/
75
+ ├── personas.md
76
+ ├── information-architecture.md
77
+ ├── navigation.md
78
+ ├── micro-interactions.md
79
+ ├── responsive.md
80
+ └── component-plan.md (omit when target is figma)
81
+ ```
82
+
83
+ ### Chunk format
84
+
85
+ See `references/chunk-format.md` for standard header, footer, naming, and size rules.
86
+
87
+ ### Rules
88
+
89
+ - **Preserve exact content** from SCREENS.md — do not summarize, rewrite, or omit details
90
+ - **Screen chunks** include: purpose, flow position, layout, components used, all 4 states (default, empty, loading, error), interactions, accessibility
91
+ - **Screen naming:** `screen-{NN}-{kebab-case-name}.md` (e.g., `screen-01-home.md`, `screen-03-user-profile.md`)
92
+ - **Shared chunks** extract global sections (personas, IA, navigation, responsive, etc.)
93
+ - **Size target:** 150-200 lines per screen chunk, 50-100 lines per shared chunk
94
+ - **Self-contained:** each chunk must be understandable without loading other chunks
95
+ - **Screen chunks** link to component chunks in `../../system/exports/components/{name}.md`
96
+ - **Shared chunks** link to related shared chunks and relevant screen chunks
97
+ - **Omit** `component-plan.md` when `implementation_target` is `figma`
98
+
99
+ ### Update INDEX.md
100
+
101
+ After generating chunks, update `.design/exports/INDEX.md`:
102
+
103
+ 1. If INDEX.md doesn't exist, copy it from `templates/exports-index.md`
104
+ 2. Replace everything between `<!-- BEGIN:screens -->` and `<!-- END:screens -->` with populated tables:
105
+
106
+ ```markdown
107
+ <!-- BEGIN:screens -->
108
+ ### Screens
109
+
110
+ | # | Screen | File | Components Used |
111
+ |---|--------|------|-----------------|
112
+ | 01 | Home | [screen-01-home.md](../screens/exports/screen-01-home.md) | Button, Card, Navigation |
113
+ | 02 | Dashboard | [screen-02-dashboard.md](../screens/exports/screen-02-dashboard.md) | Chart, Table, Card |
114
+ | ... | ... | ... | ... |
115
+
116
+ ### Shared
117
+
118
+ | Section | File |
119
+ |---------|------|
120
+ | Personas | [personas.md](../screens/exports/shared/personas.md) |
121
+ | Information Architecture | [information-architecture.md](../screens/exports/shared/information-architecture.md) |
122
+ | Navigation | [navigation.md](../screens/exports/shared/navigation.md) |
123
+ | Micro-interactions | [micro-interactions.md](../screens/exports/shared/micro-interactions.md) |
124
+ | Responsive | [responsive.md](../screens/exports/shared/responsive.md) |
125
+ | Component Plan | [component-plan.md](../screens/exports/shared/component-plan.md) |
126
+ <!-- END:screens -->
127
+ ```
128
+ </chunked-exports>
package/commands/gsp/build.md CHANGED
@@ -8,7 +8,7 @@ allowed-tools:
8
8
  - Task
9
9
  ---
10
10
  <context>
11
- Phase 7 of the GSP design pipeline. Uses the Design-to-Code Translator prompt to convert implementation specs and design system into production-ready frontend components.
11
+ Phase 7 of the GSP design pipeline. Uses the Design-to-Code Translator prompt to convert implementation specs and design system into production-ready frontend components. Adapts output based on design scope and codebase context.
12
12
  </context>
13
13
 
14
14
  <objective>
@@ -27,14 +27,32 @@ Translate designs into production-ready frontend code.
27
27
  <process>
28
28
  ## Step 1: Load context
29
29
 
30
- Read `.design/config.json` to get `implementation_target`.
31
-
30
+ Read `.design/config.json` to get `implementation_target`, `design_scope`, `codebase_type`.
31
+
32
+ **Check for chunked exports:**
33
+ If `.design/exports/INDEX.md` exists, chunked exports are available.
34
+
35
+ **When building a specific screen** (user specifies which) and chunks are available:
36
+ 1. Read `.design/exports/INDEX.md` — find chunk file paths
37
+ 2. Load screen chunk: `.design/screens/exports/screen-{NN}-{name}.md`
38
+ 3. Load screen spec: `.design/specs/exports/screens/screen-{NN}-spec.md`
39
+ 4. Load referenced component chunks from `.design/system/exports/components/`
40
+ 5. Load `.design/specs/exports/token-mapping.md`
41
+ 6. Load `.design/specs/exports/install-manifest.md` (shadcn/rn-reusables targets)
42
+ 6b. Load `.design/specs/exports/gap-analysis.md` + `.design/specs/exports/file-references.md` (existing target)
43
+ 6c. Load `.design/codebase/INVENTORY.md` (when `codebase_type` is `boilerplate` or `existing` — provides architecture patterns and conventions)
44
+ 7. Load `.design/system/tokens.json`
45
+ 8. Read `.design/BRIEF.md` — tech stack preference
46
+ 9. Load `.design/review/exports/review-fixes.md` (if available) or `.design/review/CRITIQUE.md` — fixes to incorporate
47
+
48
+ **When building all screens** (or no chunks available):
32
49
  Read:
33
50
  - `.design/specs/SPECS.md` — implementation specs (primary input)
34
51
  - `.design/system/SYSTEM.md` — design system
35
52
  - `.design/system/tokens.json` — design tokens
36
53
  - `.design/BRIEF.md` — tech stack preference
37
54
  - `.design/review/CRITIQUE.md` — any fixes to incorporate
55
+ - `.design/codebase/INVENTORY.md` — codebase patterns and conventions (if exists)
38
56
 
39
57
  If SPECS.md doesn't exist, check if `implementation_target` is `skip`:
40
58
  - **If `skip`:** Read `.design/screens/SCREENS.md` + `.design/system/SYSTEM.md` as primary input instead
@@ -50,11 +68,19 @@ Spawn the `gsp-design-engineer` agent with:
50
68
  - The build output template
51
69
  - The target tech stack
52
70
  - The `implementation_target` value
71
+ - The `design_scope` value
72
+ - The codebase inventory (INVENTORY.md content, when exists) — for naming conventions, file placement
53
73
 
54
74
  **When `shadcn`:** Agent should use `npx shadcn@latest add` for components, extend with custom variants as defined in SPECS.md.
55
75
 
56
76
  **When `rn-reusables`:** Agent should use `npx @react-native-reusables/cli add` for components, configure NativeWind theming.
57
77
 
78
+ **When `design_scope` is `tokens`:**
79
+ - Primary input: SYSTEM.md + tokens.json
80
+ - Output: token files only (updated tailwind.config, CSS variables, theme file)
81
+ - Skip component code generation
82
+ - When `codebase_type` is `existing`: output as patches to token files from INVENTORY.md
83
+
58
84
  The agent should deliver:
59
85
  1. Component hierarchy with props, state, data flow
60
86
  2. Production-ready code for each component
package/commands/gsp/design.md CHANGED
@@ -10,14 +10,14 @@ allowed-tools:
10
10
  - Glob
11
11
  ---
12
12
  <context>
13
- Phase 4 of the GSP design pipeline. Uses the UI/UX Pattern Master prompt to design core screens following Apple HIG and the project's design system.
13
+ Phase 4 of the GSP design pipeline. Uses the UI/UX Pattern Master prompt to design core screens following Apple HIG and the project's design system. Adapts screen count and scope based on project configuration.
14
14
  </context>
15
15
 
16
16
  <objective>
17
17
  Design core UI/UX screens and interaction flows.
18
18
 
19
19
  **Input:** `.design/system/SYSTEM.md` + `.design/BRIEF.md`
20
- **Output:** `.design/screens/SCREENS.md`
20
+ **Output:** `.design/screens/SCREENS.md` + `.design/screens/exports/` + `.design/exports/INDEX.md` (updated)
21
21
  **Agent:** `gsp-ui-designer`
22
22
  </objective>
23
23
 
@@ -34,21 +34,32 @@ Read:
34
34
  - `.design/BRIEF.md` — app type, audience, goals
35
35
  - `.design/system/SYSTEM.md` — design system to use
36
36
  - `.design/brand/IDENTITY.md` — brand personality
37
- - `.design/config.json` — get `implementation_target`
37
+ - `.design/config.json` — get `implementation_target`, `design_scope`
38
38
 
39
39
  If SYSTEM.md doesn't exist, tell the user to run `/gsp:system` first.
40
40
 
41
- ## Step 2: Scan codebase for existing components
41
+ ## Step 1.5: Scope check
42
+
43
+ **If `design_scope` is `tokens`:**
44
+ 1. Update `.design/STATE.md` — set Phase 4 (Design) status to `skipped`
45
+ 2. Display: "Design phase skipped — design scope is `tokens` (system/token refresh only). No screens to design."
46
+ 3. Route: "Run `/gsp:review` for design critique and accessibility audit."
47
+ 4. Stop here.
48
+
49
+ **If `design_scope` is `partial`:**
50
+ Read BRIEF.md "Target screens" to get the specific screen list. Pass this to the agent instead of "8 core screens".
51
+
52
+ ## Step 2: Load existing components inventory
42
53
 
43
54
  When `implementation_target` is `shadcn`, `rn-reusables`, `existing`, or `code` (anything except `figma`):
44
55
 
45
- Scan the codebase for existing layouts and components:
56
+ **If `.design/codebase/INVENTORY.md` exists**, read it and use as the Existing Components inventory. Pass to the agent.
57
+
58
+ **If INVENTORY.md doesn't exist** (legacy projects without codebase analysis), fall back to scanning the codebase:
46
59
  - Look for `components/`, `src/components/`, `components/ui/`, `lib/components/`
47
60
  - Look for shadcn `components/ui/` or RN Reusables `components/ui/`
48
- - Look for Expo `app/` layouts, Next.js `app/` layouts, or other layout files
49
- - Look for page/screen files to understand existing structure
50
-
51
- Build an **Existing Components** inventory summarizing what's already built and reusable.
61
+ - Look for layout files, page/screen files
62
+ - Build an Existing Components inventory from what's found
52
63
 
53
64
  Pass this inventory to the agent so screen designs can reference existing components.
54
65
 
@@ -60,13 +71,18 @@ Spawn the `gsp-ui-designer` agent with:
60
71
  - The design output template
61
72
  - The Apple HIG patterns reference
62
73
  - The `implementation_target` value
74
+ - The `design_scope` value
75
+ - The target screens list (when `partial` scope)
63
76
  - The existing components inventory (if gathered in Step 2)
77
+ - The INVENTORY.md content (when exists — for referencing existing components and patterns)
64
78
 
65
79
  The agent should deliver:
66
80
  1. User personas with goals and pain points
67
81
  2. Information architecture
68
82
  3. Navigation pattern and gesture definitions
69
- 4. 8 core screens with wireframes, components, interactions
83
+ 4. Core screens with wireframes, components, interactions:
84
+ - `full` scope: 8 core screens (default)
85
+ - `partial` scope: only the target screens specified in the brief
70
86
  5. All states: empty, error, loading
71
87
  6. Accessibility specs (WCAG, VoiceOver, Dynamic Type)
72
88
  7. Micro-interactions and animations
@@ -78,6 +94,21 @@ The agent should deliver:
78
94
 
79
95
  Write screens to `.design/screens/SCREENS.md`.
80
96
 
97
+ ## Step 4.5: Generate chunked exports
98
+
99
+ After writing SCREENS.md, the agent generates agent-consumable chunks:
100
+
101
+ 1. Create `.design/screens/exports/` with one file per screen:
102
+ - `screen-01-{name}.md`, `screen-02-{name}.md`, etc. (~150-200 lines each)
103
+ 2. Create `.design/screens/exports/shared/` with global sections:
104
+ - `personas.md`, `information-architecture.md`, `navigation.md`, `micro-interactions.md`, `responsive.md`
105
+ - `component-plan.md` (omit when `implementation_target` is `figma`)
106
+ 3. Update `.design/exports/INDEX.md` — replace the `<!-- BEGIN:screens -->` … `<!-- END:screens -->` section with populated screen and shared tables
107
+
108
+ Each chunk follows the standard format: header with phase/source/date, exact content from monolith (no summarization), and `## Related` footer with links to related chunks.
109
+
110
+ Screen chunks' `## Related` section links to component chunks in `../../system/exports/components/{name}.md`.
111
+
81
112
  ## Step 5: Update state
82
113
 
83
114
  Update `.design/STATE.md`:
package/commands/gsp/new-project.md CHANGED
@@ -6,6 +6,8 @@ allowed-tools:
6
6
  - Write
7
7
  - Bash
8
8
  - AskUserQuestion
9
+ - Glob
10
+ - Grep
9
11
  ---
10
12
  <context>
11
13
  You are the GSP (Get Shit Pretty) project initializer. Your job is to gather design requirements through conversational Q&A and produce a complete design brief.
@@ -19,6 +21,7 @@ Initialize a new design project through guided questioning → brief → roadmap
19
21
  - `.design/ROADMAP.md` — phase plan (8 phases)
20
22
  - `.design/STATE.md` — progress tracking
21
23
  - `.design/config.json` — project preferences
24
+ - `.design/codebase/INVENTORY.md` — codebase inventory (when boilerplate or existing)
22
25
 
23
26
  **After this command:** Run `/gsp:research` to begin the design pipeline.
24
27
  </objective>
@@ -29,6 +32,7 @@ Initialize a new design project through guided questioning → brief → roadmap
29
32
  @/Users/jubs/.claude/get-shit-pretty/templates/roadmap.md
30
33
  @/Users/jubs/.claude/get-shit-pretty/templates/state.md
31
34
  @/Users/jubs/.claude/get-shit-pretty/templates/config.json
35
+ @/Users/jubs/.claude/get-shit-pretty/templates/codebase-inventory.md
32
36
  </execution_context>
33
37
 
34
38
  <process>
@@ -40,7 +44,51 @@ Display:
40
44
  Starting new design project...
41
45
  ```
42
46
 
43
- ## Step 2: Gather the brief
47
+ ## Step 2: Create project structure
48
+
49
+ ```bash
50
+ mkdir -p .design/{research,brand,system,screens,specs,review,build,launch,codebase}
51
+ ```
52
+
53
+ ## Step 3: Analyze codebase
54
+
55
+ Run this silently before questioning so results are available for Round 2.
56
+
57
+ **1. Detect code signals** — scan for:
58
+ - `package.json`, `composer.json`, `Cargo.toml`, or other manifests
59
+ - `src/`, `app/`, `components/`, `lib/` directories
60
+ - Config files: `tailwind.config.*`, `next.config.*`, `tsconfig.json`, `app.json`, `vite.config.*`
61
+ - Style files: `globals.css`, `theme.*`, `tokens.*`
62
+ - Token/theme files
63
+
64
+ **2. Classify the codebase:**
65
+ - **`greenfield`** — no meaningful code (empty repo, just README, only config boilerplate with no source files)
66
+ - **`boilerplate`** — scaffolded but no custom components (fresh `create-next-app`, fresh Expo template, etc. — has framework files but no custom components/screens beyond defaults)
67
+ - **`existing`** — has custom components, screens, styling, or tokens
68
+
69
+ **3. If `boilerplate` or `existing`:** fill in the codebase inventory template → write to `.design/codebase/INVENTORY.md`
70
+ - Read actual component files to understand props, variants, patterns
71
+ - Read config files (`tailwind.config.*`, `tsconfig.json`, etc.) to understand conventions
72
+ - Read a few representative source files to detect naming, export, and styling patterns
73
+ - Catalog existing tokens/theming setup
74
+
75
+ **4. Auto-infer `implementation_target`** from what was found:
76
+ - `components.json` + `components/ui/` → suggest `shadcn`
77
+ - RN Reusables setup (reusables config, NativeWind) → suggest `rn-reusables`
78
+ - Custom design system with no UI kit → suggest `existing`
79
+ - Greenfield → default `code`
80
+
81
+ **5. Present findings to user** for confirmation:
82
+ - Show detected stack summary and suggested target
83
+ - Example: "I found a Next.js app with Tailwind and 8 shadcn components installed. Recommended target: `shadcn`. Sound right?"
84
+ - User confirms or overrides — use this confirmed value in Round 2 instead of asking the implementation target question from scratch
85
+ - When `codebase_type` is `existing`, also ask the system strategy question:
86
+ - "Do you want to evolve the existing design system incrementally, or redesign it with a migration path?"
87
+ - Evolve incrementally → `extend`
88
+ - Redesign with migration → `refactor`
89
+ - Store the answer in config as `system_strategy`. For `greenfield` or `boilerplate`, auto-set `system_strategy` to `generate`.
90
+
91
+ ## Step 4: Gather the brief
44
92
 
45
93
  Use the questioning techniques from the reference. Ask in 3 conversational rounds:
46
94
 
@@ -54,13 +102,20 @@ Use the questioning techniques from the reference. Ask in 3 conversational round
54
102
  **Round 2 — Scope & Constraints:**
55
103
  - Platforms (web, iOS, Android)?
56
104
  - Tech stack preferences?
57
- - Implementation target — how will designs become code?
58
- - Using a UI kit? (shadcn/ui → `shadcn`, React Native Reusables → `rn-reusables`)
59
- - Existing design system already in the codebase? (`existing`)
60
- - Need Figma handoff? (`figma`)
61
- - Straight to code with no specific UI kit? (`code`)
62
- - Skip specs entirely, build directly from screen designs? (`skip`)
63
- - Default: `code`
105
+ - Implementation target — **present codebase analysis findings** (from Step 3):
106
+ - Show detected stack and suggested `implementation_target`
107
+ - User confirms or overrides
108
+ - If codebase was classified as `greenfield`, ask directly:
109
+ - Using a UI kit? (shadcn/ui → `shadcn`, React Native Reusables → `rn-reusables`)
110
+ - Existing design system already in the codebase? (`existing`)
111
+ - Need Figma handoff? (`figma`)
112
+ - Straight to code with no specific UI kit? (`code`)
113
+ - Skip specs entirely, build directly from screen designs? (`skip`)
114
+ - Default: `code`
115
+ - Design scope — what are we designing?
116
+ - Full app or full redesign → `full` (default)
117
+ - Specific screens or flows → `partial` — which ones?
118
+ - Token/system refresh only → `tokens`
64
119
  - Key screens/pages needed?
65
120
  - Accessibility level (default: WCAG 2.2 AA)?
66
121
  - Timeline and constraints?
@@ -71,21 +126,16 @@ Use the questioning techniques from the reference. Ask in 3 conversational round
71
126
 
72
127
  Use inference over interrogation — state assumptions and let them correct. Offer concrete options when answers are vague.
73
128
 
74
- ## Step 3: Create project structure
75
-
76
- ```bash
77
- mkdir -p .design/{research,brand,system,screens,specs,review,build,launch}
78
- ```
79
-
80
- ## Step 4: Write artifacts
129
+ ## Step 5: Write artifacts
81
130
 
82
131
  Using the templates, fill in the gathered information:
83
132
  1. Write `.design/BRIEF.md` from the project template with all gathered info
84
133
  2. Write `.design/ROADMAP.md` from the roadmap template with project name and date
85
134
  3. Write `.design/STATE.md` from the state template
86
- 4. Write `.design/config.json` from the config template with preferences (including `implementation_target` from Round 2)
135
+ 4. Write `.design/config.json` from the config template with preferences (including `implementation_target`, `codebase_type`, `design_scope`, and `system_strategy` from Steps 3-4)
136
+ 5. Write `.design/codebase/INVENTORY.md` from the codebase inventory template (only when `codebase_type` is `boilerplate` or `existing`)
87
137
 
88
- ## Step 5: Confirm and route
138
+ ## Step 6: Confirm and route
89
139
 
90
140
  Display a summary of the brief and confirm with the user. Show:
91
141
  - Project name and type
package/commands/gsp/review.md CHANGED
@@ -76,6 +76,19 @@ Should deliver:
76
76
  1. Write critique to `.design/review/CRITIQUE.md`
77
77
  2. Write audit to `.design/review/ACCESSIBILITY.md`
78
78
 
79
+ ## Step 3.5: Generate chunked exports
80
+
81
+ After writing CRITIQUE.md and ACCESSIBILITY.md, generate agent-consumable chunks:
82
+
83
+ 1. Create `.design/review/exports/review-fixes.md` — Critical and Important fixes only, each with:
84
+ - Which screen/component is affected
85
+ - The specific issue
86
+ - Concrete remediation
87
+ 2. Create `.design/review/exports/accessibility-fixes.md` — Violations table and remediation steps
88
+ 3. If `.design/exports/INDEX.md` exists, replace the `<!-- BEGIN:review -->` … `<!-- END:review -->` section with populated tables
89
+
90
+ Each chunk follows the standard chunk format (see `references/chunk-format.md`).
91
+
79
92
  ## Step 4: Assess results
80
93
 
81
94
  Count critical and important issues across both reports.
package/commands/gsp/spec.md CHANGED
@@ -17,7 +17,7 @@ Phase 5 of the GSP design pipeline. Converts screen designs into implementation
17
17
  Generate implementation specifications from screen designs.
18
18
 
19
19
  **Input:** `.design/screens/SCREENS.md` + `.design/system/SYSTEM.md` + `.design/config.json`
20
- **Output:** `.design/specs/SPECS.md`
20
+ **Output:** `.design/specs/SPECS.md` + `.design/specs/exports/` + `.design/exports/INDEX.md` (updated)
21
21
  **Agent:** `gsp-spec-engineer`
22
22
  </objective>
23
23
 
@@ -30,7 +30,7 @@ Generate implementation specifications from screen designs.
30
30
  ## Step 1: Load context
31
31
 
32
32
  Read:
33
- - `.design/config.json` — get `implementation_target` (default: `code`)
33
+ - `.design/config.json` — get `implementation_target` (default: `code`), `design_scope`
34
34
  - `.design/screens/SCREENS.md` — screen designs to convert
35
35
  - `.design/system/SYSTEM.md` — design system (tokens, components)
36
36
  - `.design/system/tokens.json` — token values
@@ -39,14 +39,18 @@ If SCREENS.md doesn't exist, tell the user to run `/gsp:design` first.
39
39
 
40
40
  ## Step 2: Check for skip
41
41
 
42
- If `implementation_target` is `skip`:
42
+ If `implementation_target` is `skip` OR `design_scope` is `tokens`:
43
43
  1. Update `.design/STATE.md` — set Phase 5 (Spec) status to `skipped`
44
- 2. Display: "Spec phase skipped — implementation target is set to `skip`. Designs will feed directly into build."
44
+ 2. Display: "Spec phase skipped — implementation target is set to `skip` or design scope is `tokens`. Designs will feed directly into build."
45
45
  3. Route: "Run `/gsp:review` for design critique and accessibility audit."
46
46
  4. Stop here.
47
47
 
48
48
  ## Step 3: Gather target context
49
49
 
50
+ **If `.design/codebase/INVENTORY.md` exists**, read it and pass as target context to the agent. This provides component paths, token files, architecture patterns, and conventions.
51
+
52
+ **If INVENTORY.md doesn't exist** (legacy projects without codebase analysis), fall back to scanning:
53
+
50
54
  **When `existing`:** Scan the codebase for existing design system files:
51
55
  - Look for `components/`, `src/components/`, `components/ui/`, `lib/components/`
52
56
  - Look for token/theme files: `tailwind.config.*`, `theme.*`, `tokens.*`, `globals.css`
@@ -75,6 +79,23 @@ Spawn the `gsp-spec-engineer` agent with:
75
79
 
76
80
  Write specs to `.design/specs/SPECS.md`.
77
81
 
82
+ ## Step 5.5: Generate chunked exports
83
+
84
+ After writing SPECS.md, the agent generates agent-consumable chunks:
85
+
86
+ 1. Create `.design/specs/exports/` with:
87
+ - `component-mapping.md` — component-to-target mapping table
88
+ - `token-mapping.md` — design tokens to target format mapping
89
+ - `install-manifest.md` — install commands (only for `shadcn` and `rn-reusables` targets)
90
+ 2. Create `.design/specs/exports/screens/` with one spec per screen:
91
+ - `screen-01-spec.md`, `screen-02-spec.md`, etc.
92
+ 3. For `existing` target: generate `gap-analysis.md` + `file-references.md` instead of `install-manifest.md`
93
+ 4. Update `.design/exports/INDEX.md` — replace the `<!-- BEGIN:specs -->` … `<!-- END:specs -->` section with populated tables
94
+
95
+ Each chunk follows the standard format: header with phase/source/date, exact content from monolith (no summarization), and `## Related` footer with links to related chunks.
96
+
97
+ Per-screen spec chunks link to corresponding screen design chunk and component chunks.
98
+
78
99
  ## Step 6: Update state
79
100
 
80
101
  Update `.design/STATE.md`:
package/commands/gsp/system.md CHANGED
@@ -8,14 +8,14 @@ allowed-tools:
8
8
  - Task
9
9
  ---
10
10
  <context>
11
- Phase 3 of the GSP design pipeline. Uses the Design System Architect prompt to build a complete design system with foundations, components, and tokens.
11
+ Phase 3 of the GSP design pipeline. Uses the Design System Architect prompt to build a complete design system with foundations, components, and tokens. Adapts strategy based on codebase context — generates from scratch, extends an existing system, or redesigns with migration mapping.
12
12
  </context>
13
13
 
14
14
  <objective>
15
15
  Build a complete design system from the brand identity.
16
16
 
17
17
  **Input:** `.design/brand/IDENTITY.md`
18
- **Output:** `.design/system/SYSTEM.md` + `.design/system/tokens.json`
18
+ **Output:** `.design/system/SYSTEM.md` + `.design/system/tokens.json` + `.design/system/exports/` + `.design/exports/INDEX.md`
19
19
  **Agent:** `gsp-system-architect`
20
20
  </objective>
21
21
 
@@ -32,10 +32,45 @@ Read:
32
32
  - `.design/brand/IDENTITY.md` — brand colors, type, personality
33
33
  - `.design/brand/palettes.json` — tints.dev generated color palettes (11-stop OKLCH scales)
34
34
  - `.design/BRIEF.md` — platforms, tech stack, constraints
35
+ - `.design/config.json` — get `system_strategy`, `design_scope`, `implementation_target`, `codebase_type`
36
+ - `.design/codebase/INVENTORY.md` — existing tokens, components, architecture (if exists)
35
37
 
36
38
  If IDENTITY.md doesn't exist, tell the user to run `/gsp:brand` first.
37
39
  If palettes.json exists, use its OKLCH values as the foundation for the color system tokens.
38
40
 
41
+ ## Step 1.5: Determine system strategy
42
+
43
+ Read `system_strategy` from config.json (defaults to `generate` if missing).
44
+
45
+ Three strategies:
46
+
47
+ **GENERATE** (when `system_strategy` is `generate` or missing):
48
+ Full system from scratch. For `boilerplate` codebases, respect existing config structure (extend tailwind.config, not replace) and output tokens in the format the existing config uses (Tailwind extend, CSS custom properties, etc).
49
+
50
+ **EXTEND** (when `system_strategy` is `extend`):
51
+ Evolve the existing system rather than replacing it. The codebase already has tokens and components (from INVENTORY.md).
52
+ 1. Audit existing tokens against the brand identity — keep what works, adjust what doesn't, fill gaps
53
+ 2. Classify each existing component: KEEP (unchanged), RESTYLE (apply new tokens), REFACTOR (structural changes), REPLACE (redesign needed)
54
+ 3. Design only net-new components not covered by existing ones
55
+ 4. Output delta tokens — only new and changed values, referencing existing token names
56
+ 5. Preserve existing naming conventions, file patterns, and architecture from INVENTORY.md
57
+
58
+ **REFACTOR** (when `system_strategy` is `refactor`):
59
+ Redesign the system from the ground up, informed by what exists. The codebase has an existing system (from INVENTORY.md) that needs a complete rethink.
60
+ 1. Read and understand existing tokens, components, patterns from INVENTORY.md
61
+ 2. Design a complete new system (foundations, 30+ components, tokens) — same scope as GENERATE
62
+ 3. Produce a migration mapping for every change:
63
+ - Old token → new token (or "removed — use X instead")
64
+ - Old component → new component (or "replaced by X")
65
+ - Files that need updating and what changes
66
+ 4. Preserve conventions (naming, file org, import aliases) unless the brand requires changes
67
+ 5. Flag breaking changes explicitly
68
+
69
+ **When `design_scope` is `tokens` (any strategy):**
70
+ - Skip component design entirely
71
+ - Produce foundations + tokens.json only
72
+ - Add component-token mapping: which existing components are affected by token changes and how
73
+
39
74
  ## Step 2: Spawn system architect
40
75
 
41
76
  Spawn the `gsp-system-architect` agent with:
@@ -43,6 +78,9 @@ Spawn the `gsp-system-architect` agent with:
43
78
  - The Design System Architect prompt (01)
44
79
  - The system output template
45
80
  - The design tokens reference
81
+ - The `system_strategy` value
82
+ - The `design_scope` value
83
+ - The INVENTORY.md content (when exists)
46
84
 
47
85
  The agent should deliver:
48
86
  1. Color system (primary, semantic, dark mode, contrast ratios, usage)
@@ -51,7 +89,11 @@ The agent should deliver:
51
89
  4. Spacing system (8px base)
52
90
  5. Elevation / shadow scale
53
91
  6. Border radius tokens
54
- 7. 30+ components with states, anatomy, usage, accessibility, code specs
92
+ 7. Components:
93
+ - GENERATE: 30+ components (current behavior)
94
+ - EXTEND: Component audit table (KEEP/RESTYLE/REFACTOR/REPLACE) + specs for refactored and new only
95
+ - REFACTOR: 30+ components (redesigned) + migration mapping from old → new
96
+ - tokens scope: Component-token mapping table only
55
97
  8. Design patterns
56
98
  9. Design tokens as JSON (`tokens.json`)
57
99
  10. Design principles and do's/don'ts
@@ -61,6 +103,20 @@ The agent should deliver:
61
103
  1. Write system to `.design/system/SYSTEM.md`
62
104
  2. Write tokens to `.design/system/tokens.json`
63
105
 
106
+ ## Step 3.5: Generate chunked exports
107
+
108
+ After writing SYSTEM.md and tokens.json, the agent generates agent-consumable chunks:
109
+
110
+ 1. Create `.design/system/exports/foundations/` with one file per foundation:
111
+ - `color-system.md`, `typography.md`, `spacing.md`, `grid.md`, `elevation.md`, `border-radius.md`
112
+ 2. Create `.design/system/exports/components/` with one file per component:
113
+ - Singular kebab-case naming: "Buttons" → `button.md`, "Date Picker" → `date-picker.md`
114
+ 3. Create `.design/system/exports/principles.md`
115
+ 4. Copy `templates/exports-index.md` to `.design/exports/INDEX.md` (if it doesn't already exist)
116
+ 5. Update `.design/exports/INDEX.md` — replace the `<!-- BEGIN:system -->` … `<!-- END:system -->` section with populated foundations and components tables
117
+
118
+ Each chunk follows the standard format: header with phase/source/date, exact content from monolith (no summarization), and `## Related` footer with links to related chunks.
119
+
64
120
  ## Step 4: Update state
65
121
 
66
122
  Update `.design/STATE.md`:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "get-shit-pretty",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "A design engineering system for Claude Code, OpenCode, Gemini, and Codex. Research → Brand → System → Design → Spec → Review → Build → Launch.",
5
5
  "bin": {
6
6
  "get-shit-pretty": "bin/install.js"
package/prompts/01-design-system-architect.md CHANGED
@@ -1,19 +1,48 @@
1
1
  # The Design System Architect
2
2
 
3
3
  **Category:** Design Systems
4
- **Use when:** Building a complete design system from scratch for a brand
4
+ **Use when:** Building a complete design system from scratch, extending an existing one, or redesigning with migration mapping
5
5
 
6
6
  ---
7
7
 
8
8
  ## Prompt
9
9
 
10
- Act as Apple Principal Designer. Build a complete design system for [BRAND]. Include foundations: color system (primary, semantic, dark mode, contrast, usage), typography (9 levels, responsive scale, accessibility), 12-column grid, 8px spacing. Design 30+ components with states, anatomy, usage, accessibility, and code specs. Add patterns, design tokens JSON, principles, do's/don'ts, and dev guide. Publish-ready.
10
+ Act as Apple Principal Designer. Build a design system for [BRAND].
11
+
12
+ **When [SYSTEM_STRATEGY] is GENERATE:**
13
+ Build a complete design system from scratch. Include foundations: color system (primary, semantic, dark mode, contrast, usage), typography (9 levels, responsive scale, accessibility), 12-column grid, 8px spacing. Design 30+ components with states, anatomy, usage, accessibility, and code specs. Add patterns, design tokens JSON, principles, do's/don'ts, and dev guide. Publish-ready.
14
+ When [INVENTORY] is provided (boilerplate): respect existing config structure and output tokens in the format the existing config uses (Tailwind extend, CSS custom properties, etc).
15
+
16
+ **When [SYSTEM_STRATEGY] is EXTEND:**
17
+ Evolve the existing design system rather than replacing it. The codebase already has tokens and components (see [INVENTORY]).
18
+ 1. Audit existing tokens against the brand identity — keep what works, adjust what doesn't, fill gaps
19
+ 2. Classify each existing component: KEEP (unchanged), RESTYLE (apply new tokens), REFACTOR (structural changes), REPLACE (redesign needed)
20
+ 3. Design only net-new components not covered by existing ones
21
+ 4. Output delta tokens — only new and changed values, referencing existing token names
22
+ 5. Preserve existing naming conventions, file patterns, and architecture from [INVENTORY]
23
+
24
+ **When [SYSTEM_STRATEGY] is REFACTOR:**
25
+ Redesign the design system from the ground up, informed by what exists. The codebase has an existing system (see [INVENTORY]) that needs a complete rethink.
26
+ 1. Read and understand existing tokens, components, patterns from [INVENTORY]
27
+ 2. Design a complete new system (foundations, 30+ components, tokens) — same scope as GENERATE
28
+ 3. Produce a migration mapping for every change:
29
+ - Old token → new token (or "removed — use X instead")
30
+ - Old component → new component (or "replaced by X")
31
+ - Files that need updating and what changes
32
+ 4. Preserve conventions (naming, file org, import aliases) unless the brand requires changes
33
+ 5. Flag breaking changes explicitly
34
+
35
+ **When [DESIGN_SCOPE] is `tokens`:**
36
+ Focus exclusively on foundations and tokens. Do not design components. Produce a component-token mapping table showing which existing components are affected by token changes and how.
11
37
 
12
38
  ---
13
39
 
14
40
  ## Variables
15
41
 
16
42
  - `[BRAND]` — The brand/product name to build the system for
43
+ - `[SYSTEM_STRATEGY]` — GENERATE | EXTEND | REFACTOR
44
+ - `[INVENTORY]` — Contents of INVENTORY.md (empty when greenfield)
45
+ - `[DESIGN_SCOPE]` — full | partial | tokens
17
46
 
18
47
  ## Expected Output
19
48
 
@@ -21,7 +50,10 @@ Act as Apple Principal Designer. Build a complete design system for [BRAND]. Inc
21
50
  - Typography scale (9 levels, responsive, accessible)
22
51
  - Grid system (12-column)
23
52
  - Spacing system (8px base)
24
- - 30+ components with: states, anatomy, usage rules, accessibility specs, code specs
53
+ - 30+ components with: states, anatomy, usage rules, accessibility specs, code specs (GENERATE/REFACTOR)
54
+ - Component audit table with KEEP/RESTYLE/REFACTOR/REPLACE classifications (EXTEND)
55
+ - Migration mapping: old → new for tokens and components (REFACTOR)
56
+ - Component-token mapping table (tokens scope)
25
57
  - Design patterns
26
58
  - Design tokens (JSON)
27
59
  - Design principles
package/prompts/03-ui-ux-pattern-master.md CHANGED
@@ -9,12 +9,22 @@
9
9
 
10
10
  Act as a Senior Apple UI Designer. Design a full UI for [APP TYPE] based on [PERSONA], goals, and pain points. Follow Apple HIG. Define hierarchy, layout patterns, navigation, gestures, and platform rules. Detail 8 core screens with wireframes, components, interactions, empty/error/loading states. Specify buttons, forms, cards, data viz, accessibility (WCAG, VoiceOver, Dynamic Type), micro-interactions, and responsive behavior. Include Designer's Notes.
11
11
 
12
+ **Screen scope:**
13
+ - When `design_scope` is `full`: design [SCREEN_COUNT] core screens (default 8)
14
+ - When `design_scope` is `partial`: design only [TARGET_SCREENS]
15
+
16
+ **When [INVENTORY] is provided (existing codebase):**
17
+ Reference existing components and patterns from [INVENTORY]. Use existing component names in wireframes where applicable. When redesigning existing screens, note what changes vs what stays.
18
+
12
19
  ---
13
20
 
14
21
  ## Variables
15
22
 
16
23
  - `[APP TYPE]` — Type of application (e.g., fitness tracker, finance app)
17
24
  - `[PERSONA]` — Target user persona
25
+ - `[SCREEN_COUNT]` — Number of screens (default 8)
26
+ - `[TARGET_SCREENS]` — Specific screens when partial scope
27
+ - `[INVENTORY]` — INVENTORY.md contents (empty when greenfield)
18
28
 
19
29
  ## Expected Output
20
30
 
@@ -22,7 +32,7 @@ Act as a Senior Apple UI Designer. Design a full UI for [APP TYPE] based on [PER
22
32
  - Information hierarchy and layout patterns
23
33
  - Navigation system and gesture definitions
24
34
  - Platform-specific rules (Apple HIG)
25
- - 8 core screens with wireframes
35
+ - 8 core screens with wireframes (or target screens when partial)
26
36
  - Component specs (buttons, forms, cards, data viz)
27
37
  - State designs (empty, error, loading)
28
38
  - Accessibility (WCAG, VoiceOver, Dynamic Type)
package/prompts/09-design-to-code-translator.md CHANGED
@@ -9,12 +9,21 @@
9
9
 
10
10
  Act as a Vercel Design Engineer. Convert [DESIGN] into production-ready frontend code using [TECH STACK]. Deliver component hierarchy, props, state, data flow, copy-paste code, responsive layout, ARIA/accessibility, error/loading states, animations, styling (CSS/Tailwind with design tokens, dark mode, breakpoints, states), asset optimization, performance tips, testing strategy, and documentation.
11
11
 
12
+ **When [INVENTORY] is provided (existing codebase):**
13
+ You are working in an existing codebase. Follow conventions from [INVENTORY]:
14
+ - Use the project's naming conventions, import aliases, and export patterns
15
+ - Follow the project's component style (forwardRef, compound components, etc.)
16
+ - Place new files according to the project's file organization
17
+ - Use the project's styling approach (cn() utility, className patterns, etc.)
18
+ - When modifying existing components, show the diff rather than full rewrite
19
+
12
20
  ---
13
21
 
14
22
  ## Variables
15
23
 
16
24
  - `[DESIGN]` — Description or screenshot of the design to implement
17
25
  - `[TECH STACK]` — Frontend stack (e.g., React + Tailwind, Next.js, Vue, SwiftUI)
26
+ - `[INVENTORY]` — INVENTORY.md contents (empty when greenfield)
18
27
 
19
28
  ## Expected Output
20
29
 
package/references/chunk-format.md ADDED
@@ -0,0 +1,35 @@
1
+ # Chunk Format Reference
2
+
3
+ Standard format for all GSP chunked exports. Referenced by agent `<chunked-exports>` sections.
4
+
5
+ ## File Format
6
+
7
+ Every chunk follows this structure:
8
+
9
+ # {Section/Component/Screen Name}
10
+
11
+ > Phase: {System|Design|Spec|Review} | Source: [{FILENAME}]({relative-path}) | Generated: {DATE}
12
+
13
+ ---
14
+
15
+ {Exact content extracted from source monolith — no summarization}
16
+
17
+ ---
18
+
19
+ ## Related
20
+
21
+ - [{Related chunk name}]({relative-path-to-related-chunk})
22
+
23
+ ## Naming Conventions
24
+
25
+ - **Singular, kebab-case, lowercase:** "Buttons" → `button.md`, "Date Picker" → `date-picker.md`
26
+ - **Screen files:** `screen-{NN}-{kebab-case-name}.md` (e.g., `screen-01-home.md`)
27
+ - **Spec files:** `screen-{NN}-spec.md`
28
+
29
+ ## Rules
30
+
31
+ - **Preserve exact content** — no summarization, no rewriting, no omission
32
+ - **Size target:** 50-200 lines per chunk
33
+ - **Self-contained:** each chunk must be understandable without loading other chunks
34
+ - **Cross-references:** `## Related` section uses relative paths to related chunks
35
+ - **Idempotent:** re-running a phase regenerates all chunks in that phase's `exports/` directory
package/templates/codebase-inventory.md ADDED
@@ -0,0 +1,71 @@
1
+ # Codebase Inventory
2
+
3
+ > Auto-generated by `/gsp:new-project` during codebase analysis.
4
+ > Downstream phases consume this instead of rescanning.
5
+
6
+ ## Classification
7
+
8
+ **Codebase type:** `{greenfield | boilerplate | existing}`
9
+
10
+ **Rationale:** {Why this classification — e.g., "Fresh create-next-app with no custom components", "Has 12 custom components and a theme system"}
11
+
12
+ ## Tech Stack
13
+
14
+ | Layer | Value |
15
+ |-------|-------|
16
+ | Framework | {e.g., Next.js 14, Expo 51, Vite + React} |
17
+ | Language | {e.g., TypeScript, JavaScript} |
18
+ | Styling | {e.g., Tailwind CSS, CSS Modules, StyleSheet} |
19
+ | UI Kit | {e.g., shadcn/ui, RN Reusables, none} |
20
+ | Package Manager | {e.g., npm, pnpm, bun, yarn} |
21
+ | Build Tool | {e.g., Next.js built-in, Vite, Metro} |
22
+
23
+ ## Existing Components
24
+
25
+ | Component | Path | Props / Variants | Reusable? | Notes |
26
+ |-----------|------|------------------|-----------|-------|
27
+ | {name} | {path} | {key props} | {yes/no/partially} | {notes} |
28
+
29
+ ## Tokens & Theming
30
+
31
+ **Token source:** {e.g., `tailwind.config.ts`, `globals.css`, `theme.ts`, `tokens.json`}
32
+ **Format:** {e.g., CSS custom properties, Tailwind theme, JS object, JSON tokens}
33
+
34
+ | Category | Defined? | Details |
35
+ |----------|----------|---------|
36
+ | Colors | {yes/no} | {e.g., "Custom palette in tailwind.config.ts extend.colors"} |
37
+ | Typography | {yes/no} | {e.g., "Custom fonts via next/font, scale in Tailwind"} |
38
+ | Spacing | {yes/no} | {e.g., "Default Tailwind spacing"} |
39
+ | Radii | {yes/no} | {details} |
40
+ | Shadows | {yes/no} | {details} |
41
+ | Dark mode | {yes/no} | {e.g., "CSS class strategy via next-themes"} |
42
+
43
+ ## Architecture Patterns
44
+
45
+ | Pattern | Value |
46
+ |---------|-------|
47
+ | Component style | {e.g., functional components, forwardRef wrappers, compound components} |
48
+ | State management | {e.g., React Context, Zustand, Redux, useState only} |
49
+ | Data fetching | {e.g., Server Components, React Query, SWR, fetch in useEffect} |
50
+ | Routing | {e.g., Next.js App Router, Expo Router, React Router} |
51
+ | File organization | {e.g., feature-based, type-based, flat} |
52
+
53
+ ## Conventions
54
+
55
+ | Convention | Value |
56
+ |------------|-------|
57
+ | Naming | {e.g., PascalCase components, kebab-case files, camelCase utils} |
58
+ | Exports | {e.g., named exports, default exports, barrel files} |
59
+ | Styling approach | {e.g., `cn()` utility, `className` strings, `StyleSheet.create`} |
60
+ | Import aliases | {e.g., `@/` → `src/`, `~/` → project root} |
61
+
62
+ ## Key Paths
63
+
64
+ | Path | Purpose |
65
+ |------|---------|
66
+ | Components | {e.g., `src/components/`, `components/ui/`} |
67
+ | Layouts | {e.g., `src/app/layout.tsx`, `app/(tabs)/_layout.tsx`} |
68
+ | Pages / Screens | {e.g., `src/app/`, `app/(tabs)/`} |
69
+ | Tokens / Theme | {e.g., `tailwind.config.ts`, `src/styles/globals.css`} |
70
+ | Config | {e.g., `next.config.js`, `app.json`} |
71
+ | Public / Assets | {e.g., `public/`, `assets/`} |
package/templates/config.json CHANGED
@@ -11,6 +11,9 @@
11
11
  "accessibility_level": "WCAG 2.2 AA",
12
12
  "design_tool": "Figma",
13
13
  "implementation_target": "code",
14
+ "codebase_type": "greenfield",
15
+ "design_scope": "full",
16
+ "system_strategy": "generate",
14
17
  "auto_review": true
15
18
  },
16
19
  "phases": {
package/templates/exports-index.md ADDED
@@ -0,0 +1,69 @@
1
+ # GSP Design Exports
2
+
3
+ > Load this file first, then load only the chunks needed for your task.
4
+
5
+ ## Usage
6
+
7
+ This file is the entry point for coding agents consuming GSP design output.
8
+
9
+ 1. Read this file to find chunk paths for your task
10
+ 2. Load only the chunks relevant to your current screen or component
11
+ 3. Do not load monolith files (SYSTEM.md, SCREENS.md, SPECS.md) unless chunks are unavailable
12
+ 4. Each chunk is self-contained — follow `## Related` links for cross-references
13
+
14
+ ## Quick Reference
15
+
16
+ - Building a screen? → Screens table → load screen chunk + referenced components
17
+ - Need a component spec? → Components table
18
+ - Need color/type/spacing? → Foundations table
19
+ - Need implementation details? → Specs table
20
+
21
+ ## Design System
22
+
23
+ <!-- BEGIN:system -->
24
+ | Section | Chunk | Lines |
25
+ |---------|-------|-------|
26
+ | _(populated by /gsp:system)_ | | |
27
+
28
+ ### Foundations
29
+
30
+ | Foundation | File | Tokens |
31
+ |------------|------|--------|
32
+ | | | |
33
+
34
+ ### Components
35
+
36
+ | Component | File | States | Variants |
37
+ |-----------|------|--------|----------|
38
+ | | | | |
39
+ <!-- END:system -->
40
+
41
+ ## Screens
42
+
43
+ <!-- BEGIN:screens -->
44
+ | # | Screen | File | Components Used |
45
+ |---|--------|------|-----------------|
46
+ | _(populated by /gsp:design)_ | | | |
47
+
48
+ ### Shared
49
+
50
+ | Section | File |
51
+ |---------|------|
52
+ | | |
53
+ <!-- END:screens -->
54
+
55
+ ## Implementation Specs
56
+
57
+ <!-- BEGIN:specs -->
58
+ | Section | File |
59
+ |---------|------|
60
+ | _(populated by /gsp:spec)_ | | |
61
+ <!-- END:specs -->
62
+
63
+ ## Review Fixes
64
+
65
+ <!-- BEGIN:review -->
66
+ | Section | File |
67
+ |---------|------|
68
+ | _(populated by /gsp:review)_ | |
69
+ <!-- END:review -->
package/templates/phases/system.md CHANGED
@@ -3,6 +3,13 @@
3
3
  ## Project: {PROJECT_NAME}
4
4
  **Date:** {DATE}
5
5
 
6
+ ## System Strategy
7
+ - **Approach:** {GENERATE | EXTEND | REFACTOR}
8
+ - **Codebase type:** {greenfield | boilerplate | existing}
9
+ - **Design scope:** {full | partial | tokens}
10
+ - **Existing token source:** {path or "none"}
11
+ - **Existing component count:** {N or 0}
12
+
6
13
  ---
7
14
 
8
15
  ## Foundations
@@ -51,6 +58,13 @@
51
58
  | lg | | |
52
59
  | full | 9999px | Pills, avatars |
53
60
 
61
+ <!-- When strategy is EXTEND, include Component Audit before Components -->
62
+ <!-- ## Component Audit
63
+ | Existing Component | Path | Action | Rationale |
64
+ |-------------------|------|--------|-----------|
65
+ | {name} | {path} | KEEP / RESTYLE / REFACTOR / REPLACE | {why} |
66
+ -->
67
+
54
68
  ## Components
55
69
 
56
70
  ### Buttons
@@ -70,6 +84,20 @@
70
84
 
71
85
  <!-- Continue for 30+ components -->
72
86
 
87
+ <!-- When strategy is REFACTOR, include Migration Mapping after Components -->
88
+ <!-- ## Migration Mapping
89
+
90
+ ### Token Migration
91
+ | Old Token | New Token | Change | Breaking? |
92
+ |-----------|-----------|--------|-----------|
93
+ | {old} | {new} | {what changed} | {yes/no} |
94
+
95
+ ### Component Migration
96
+ | Old Component | New Component | Change | Files Affected |
97
+ |--------------|---------------|--------|---------------|
98
+ | {old} | {new} | {replaced/redesigned/merged} | {paths} |
99
+ -->
100
+
73
101
  ## Design Tokens
74
102
  See `tokens.json` for machine-readable token export.
75
103
 
package/templates/project.md CHANGED
@@ -29,6 +29,12 @@
29
29
  - **Budget:** {BUDGET}
30
30
  - **Accessibility:** WCAG 2.2 AA (default)
31
31
 
32
+ ## Scope
33
+ - **Design scope:** {full | partial | tokens}
34
+ - **Target screens:** {ALL or list of specific screens/flows}
35
+ - **Codebase type:** {greenfield | boilerplate | existing}
36
+ - **Implementation target:** {code | shadcn | rn-reusables | existing | figma | skip}
37
+
32
38
  ## Inspiration
33
39
  - **Brands admired:** {BRANDS}
34
40
  - **Styles liked:** {STYLES}