@withmata/blueprints 0.2.0 → 0.3.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.
Files changed (46) hide show
  1. package/{.opencode/commands/audit.md → .claude/skills/audit/SKILL.md} +8 -6
  2. package/.claude/skills/blueprint-catalog/SKILL.md +63 -0
  3. package/.claude/{commands/discover.md → skills/discover/SKILL.md} +8 -3
  4. package/{.cursor/commands/new-blueprint.md → .claude/skills/new-blueprint/SKILL.md} +13 -8
  5. package/{.cursor/commands/new-project.md → .claude/skills/new-project/SKILL.md} +11 -6
  6. package/.claude/{commands/scaffold-auth.md → skills/scaffold-auth/SKILL.md} +24 -23
  7. package/{.cursor/commands/scaffold-db.md → .claude/skills/scaffold-db/SKILL.md} +17 -16
  8. package/.claude/skills/scaffold-env/SKILL.md +222 -0
  9. package/.claude/{commands/scaffold-foundation.md → skills/scaffold-foundation/SKILL.md} +17 -16
  10. package/.claude/skills/scaffold-tailwind/SKILL.md +177 -0
  11. package/.claude/skills/scaffold-ui/SKILL.md +206 -0
  12. package/ENGINEERING.md +2 -2
  13. package/blueprints/features/env-t3/BLUEPRINT.md +332 -0
  14. package/blueprints/features/env-t3/files/nextjs/.env.example +17 -0
  15. package/blueprints/features/env-t3/files/nextjs/.env.local +0 -0
  16. package/blueprints/features/env-t3/files/nextjs/env/client.ts +13 -0
  17. package/blueprints/features/env-t3/files/nextjs/env/server.ts +12 -0
  18. package/blueprints/features/env-t3/files/server/.env.example +14 -0
  19. package/blueprints/features/env-t3/files/server/.env.local +0 -0
  20. package/blueprints/features/env-t3/files/server/env.ts +17 -0
  21. package/blueprints/features/tailwind-v4/BLUEPRINT.md +262 -12
  22. package/blueprints/features/tailwind-v4/files/tailwind-config/package.json +20 -0
  23. package/blueprints/features/tailwind-v4/files/tailwind-config/shared-styles.css +131 -0
  24. package/blueprints/features/ui-shared-components/BLUEPRINT.md +350 -13
  25. package/blueprints/features/ui-shared-components/files/ui/components.json +21 -0
  26. package/blueprints/features/ui-shared-components/files/ui/package.json +42 -0
  27. package/blueprints/features/ui-shared-components/files/ui/styles/globals.css +2 -0
  28. package/blueprints/features/ui-shared-components/files/ui/tsconfig.json +9 -0
  29. package/blueprints/features/ui-shared-components/files/ui/utils/cn.ts +6 -0
  30. package/blueprints/features/ui-shared-components/files/ui/utils/cva.ts +4 -0
  31. package/dist/index.js +210 -166
  32. package/package.json +6 -7
  33. package/.claude/commands/audit.md +0 -179
  34. package/.claude/commands/new-blueprint.md +0 -265
  35. package/.claude/commands/new-project.md +0 -230
  36. package/.claude/commands/scaffold-db.md +0 -270
  37. package/.cursor/commands/audit.md +0 -179
  38. package/.cursor/commands/discover.md +0 -92
  39. package/.cursor/commands/scaffold-auth.md +0 -310
  40. package/.cursor/commands/scaffold-foundation.md +0 -158
  41. package/.opencode/commands/discover.md +0 -96
  42. package/.opencode/commands/new-blueprint.md +0 -269
  43. package/.opencode/commands/new-project.md +0 -234
  44. package/.opencode/commands/scaffold-auth.md +0 -314
  45. package/.opencode/commands/scaffold-db.md +0 -274
  46. package/.opencode/commands/scaffold-foundation.md +0 -162
@@ -1,270 +0,0 @@
1
- # Scaffold DB Blueprint
2
-
3
- Scaffold the `db-drizzle-postgres` blueprint into the current project. Read the full blueprint first, then adapt it to this project's stack.
4
-
5
- ## Step 1: Read the Blueprint
6
-
7
- Read the full BLUEPRINT.md and all template files from the db blueprint:
8
-
9
- ```
10
- blueprints/features/db-drizzle-postgres/BLUEPRINT.md
11
- blueprints/features/db-drizzle-postgres/files/**/*
12
- ```
13
-
14
- If these files are not in the current project, look for them at `~/Documents/WithMata/my-blueprints/blueprints/features/db-drizzle-postgres/`. If still not found, ask the user for the path to their blueprints repo.
15
-
16
- ## Step 1.5: Read Project Context
17
-
18
- Check if `.project-context.md` exists in the target project root:
19
-
20
- - **If it exists**: read it to understand:
21
- - Product name and scope (from Discovery)
22
- - npm scope, workspace layout, TypeScript config package name (from Foundation)
23
- - What other blueprints are already installed (from Installed Blueprints)
24
- - Use this information to pre-fill configuration questions in Step 3 and adapt file paths in Step 4
25
-
26
- - **If it does not exist**: proceed normally — explore the project manually (Step 2) and ask all configuration questions (Step 3)
27
-
28
- When project context provides clear answers, skip the corresponding questions in Step 3. For example:
29
- - Context says `npm_scope: "@acme"` -> use `@acme` for package references
30
- - Context has `db-drizzle-postgres` in Installed Blueprints -> warn about existing install
31
- - Context has `auth-better-auth` installed -> `packages/db/` likely exists already
32
-
33
- ## Step 2: Understand the Target Project
34
-
35
- Before making any changes, explore the target project to understand:
36
-
37
- ### 2a. Detect Project Type
38
-
39
- Check `.project-context.md` for `project_type`. If not present, detect:
40
-
41
- - **Monorepo indicators**: `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, or `"workspaces"` in root `package.json`
42
- - **Single-repo indicators**: Single `package.json` at root, `src/` directory, no workspace config
43
-
44
- Confirm with user: "This looks like a [monorepo|single-repo] project. Is that right?"
45
-
46
- Record the project type in `.project-context.md` if not already there (add `project_type: monorepo` or `project_type: single-repo` under `## Foundation`).
47
-
48
- ### 2b. Explore Structure
49
-
50
- **If monorepo:**
51
- 1. What workspaces exist? Where do apps, APIs, and packages live?
52
- 2. Does `packages/db/` already exist? (The auth blueprint may have created it.) If so, what exports, scripts, and schema groups are already present?
53
- 3. What npm scope is used? Check root or any workspace `package.json`.
54
- 4. What is the shared TypeScript config package name? Check `config/typescript-config/` or similar.
55
- 5. Does `turbo.json` exist? Are there any existing db-related tasks?
56
- 6. Does `pnpm-workspace.yaml` include `packages/*`?
57
-
58
- **If single-repo:**
59
- 1. Does `src/db/` already exist? If so, what's in it?
60
- 2. What framework is this? (Next.js, Node/Express, Hono, Bun?)
61
- 3. What import convention is used? (`@/` paths, `#` subpath imports, relative?)
62
- 4. Is there an existing `.env` or `.env.local`?
63
-
64
- **Both:**
65
- - Package manager — pnpm, npm, yarn, or bun?
66
-
67
- Skip exploration for anything already documented in `.project-context.md`.
68
-
69
- ## Step 3: Ask Clarifying Questions
70
-
71
- Before scaffolding, ask the user about their preferences:
72
-
73
- 1. **Schema group name** — "What should your main schema group be called? This groups related database tables together (e.g., 'core' for your main application data, 'app' for a simpler name). Default: `core`"
74
-
75
- 2. **Include example entity?** — "Include an example entity file demonstrating the full Drizzle pattern (pgTable, pgEnum, indexes, type exports)? Recommended if this is your first time using Drizzle." (Default: yes)
76
-
77
- 3. **Include seed script?** — "Include a seed script template for populating development data?" (Default: yes)
78
-
79
- 4. **Connection helper** — "Should the database connection helper live in the db package (simpler — import and use directly), or will each consuming app create its own connection (more flexible — each app controls its own pool settings)?" (Default: in db package)
80
-
81
- 5. **Existing `packages/db/`** — If it already exists (e.g., from the auth blueprint): "I found an existing `packages/db/` package. I'll add the new schema group to it without overwriting existing files. Does that sound right?"
82
-
83
- Skip questions where the answer is obvious from the project structure or from `.project-context.md`.
84
-
85
- ## Step 4: Adapt and Scaffold
86
-
87
- Based on the project structure, project context, and user answers, adapt the blueprint files.
88
-
89
- ### 4a. Project Setup
90
-
91
- **If monorepo — Package Setup (or merge if exists):**
92
-
93
- If `packages/db/` does NOT exist:
94
- - Create the full package: `package.json`, `tsconfig.json`, `.env.example`
95
- - Replace all placeholders:
96
- - `{{SCOPE}}` -> the project's npm scope (e.g., `@acme`)
97
- - `{{GROUP}}` -> the schema group name (e.g., `core`)
98
- - `{{GROUP_UPPER}}` -> uppercase for env vars (e.g., `CORE`)
99
-
100
- If `packages/db/` already exists:
101
- - Merge the new schema group's export into existing `package.json` exports
102
- - Merge new scripts into existing scripts (don't overwrite existing ones like `build`, `typecheck`, `clean`)
103
- - Skip `tsconfig.json` if it already exists and looks correct
104
- - Add `{{GROUP_UPPER}}_DATABASE_URL` to existing `.env.example`
105
-
106
- **If single-repo — Directory Setup:**
107
-
108
- - Create `src/db/` directory (no separate `package.json` — use root)
109
- - Add `{{GROUP_UPPER}}_DATABASE_URL` to root `.env.example` (or `.env` if that's the convention)
110
- - No separate `tsconfig.json` needed — inherits from root
111
- - Replace placeholders in files: `{{GROUP}}`, `{{GROUP_UPPER}}`
112
- - Skip `{{SCOPE}}` — use direct imports instead (`@/db/{{GROUP}}` or `#db/{{GROUP}}`)
113
-
114
- ### 4b. Schema Group Files
115
-
116
- - Create `src/{{GROUP}}/` directory
117
- - Copy example entity file (if user said yes) — replace all placeholders
118
- - Create barrel `index.ts` with re-exports
119
- - Copy `client.ts` helper (if user chose "in db package") — replace placeholders
120
-
121
- ### 4c. Drizzle Config
122
-
123
- - **Monorepo:** Create `packages/db/drizzle/{{GROUP}}/` directory
124
- - **Single-repo:** Create `drizzle/{{GROUP}}/` at project root
125
- - Copy `drizzle.config.ts` — replace `{{GROUP}}`, `{{GROUP_UPPER}}`
126
- - Adjust schema file paths based on project type:
127
- - Monorepo: `"./src/{{GROUP}}/example.ts"` (relative to `packages/db/`)
128
- - Single-repo: `"./src/db/{{GROUP}}/example.ts"` (relative to project root)
129
- - Verify schema file paths match actual files created in 4b
130
-
131
- ### 4d. Seed Script (optional)
132
-
133
- - Create `src/scripts/` directory (if it doesn't exist)
134
- - Copy `seed.ts` — replace placeholders, adjust entity imports
135
- - If a seed script already exists, ask before overwriting
136
-
137
- ### 4e. Project Integration
138
-
139
- **If monorepo:**
140
- - Add `{{GROUP}}:generate`, `{{GROUP}}:migrate` tasks to `turbo.json` (both `cache: false`) — merge into existing tasks
141
- - Add convenience scripts to root `package.json`:
142
- - `db:generate` -> `turbo run {{GROUP}}:generate --filter={{SCOPE}}/db --no-cache`
143
- - `db:migrate` -> `turbo run {{GROUP}}:migrate --filter={{SCOPE}}/db --no-cache`
144
- - `db:studio` -> `turbo run drizzle:studio:{{GROUP}} --filter={{SCOPE}}/db --no-cache`
145
- - `db:seed` -> `turbo run seed --filter={{SCOPE}}/db --no-cache`
146
- - Verify `pnpm-workspace.yaml` includes `packages/*`
147
-
148
- **If single-repo:**
149
- - Add scripts directly to root `package.json` (direct drizzle-kit calls, no Turbo):
150
- - `db:generate` -> `drizzle-kit generate --config ./drizzle/{{GROUP}}/drizzle.config.ts`
151
- - `db:migrate` -> `drizzle-kit generate --config ./drizzle/{{GROUP}}/drizzle.config.ts && drizzle-kit migrate --config ./drizzle/{{GROUP}}/drizzle.config.ts`
152
- - `db:studio` -> `drizzle-kit studio --config ./drizzle/{{GROUP}}/drizzle.config.ts`
153
- - `db:seed` -> `tsx src/db/scripts/seed.ts`
154
- - Add drizzle-orm, dotenv as dependencies and drizzle-kit, pg, @types/pg, tsx as devDependencies
155
- - No `turbo.json` changes needed
156
-
157
- ## Step 5: Update Project Context
158
-
159
- Append an entry to `.project-context.md` under `## Installed Blueprints`:
160
-
161
- ```yaml
162
- ### db-drizzle-postgres
163
- blueprint: db-drizzle-postgres
164
- choices:
165
- schema_group: <group name>
166
- include_example: <true|false>
167
- include_seed: <true|false>
168
- connection_helper: <in-db-package|per-app>
169
- files_created:
170
- - <list of all files created or modified>
171
- env_vars_added:
172
- - <GROUP_UPPER>_DATABASE_URL
173
- scripts_added:
174
- db_package:
175
- - <group>:generate
176
- - <group>:migrate
177
- - drizzle:studio:<group>
178
- - seed
179
- root:
180
- - db:generate
181
- - db:migrate
182
- - db:studio
183
- - db:seed
184
- turbo_tasks:
185
- - <group>:generate
186
- - <group>:migrate
187
- ```
188
-
189
- If `.project-context.md` does not exist, create it with the standard header and the Installed Blueprints section. Log a note: "No discovery or foundation context found. Consider running `/discover` and `/scaffold-foundation` for a complete project context."
190
-
191
- ### Inject Maintenance Rules
192
-
193
- Append the condensed maintenance rules to the target project's rules file(s):
194
-
195
- 1. If `CLAUDE.md` exists in the target project -> append rules there
196
- 2. If `AGENTS.md` exists in the target project -> append rules there
197
- 3. If both exist -> append to both (keep them in sync)
198
- 4. If neither exists -> ask the user which AI coding tool(s) they use:
199
- - Claude Code -> create CLAUDE.md with a `## Maintenance Rules` section
200
- - OpenCode or Cursor -> create AGENTS.md with a `## Maintenance Rules` section (both tools read AGENTS.md)
201
- - Multiple tools -> create all applicable files
202
-
203
- The maintenance rules content is identical regardless of which file it goes into:
204
-
205
- ```markdown
206
- ### db-drizzle-postgres maintenance
207
- - After creating a new schema file: add it to `drizzle/<group>/drizzle.config.ts` schema array AND the group's `index.ts` barrel export
208
- - After any schema change: run `pnpm <group>:generate && pnpm <group>:migrate`
209
- - After adding a new schema group: create drizzle config, add package.json export, add scripts (see BLUEPRINT.md "Adding a New Schema Group")
210
- - After updating drizzle-orm/drizzle-kit: run generate and check migration diff for unexpected changes
211
- - Never use glob patterns in drizzle.config.ts schema — always list files explicitly, excluding index.ts
212
- ```
213
-
214
- If the `## Maintenance Rules` heading already exists (from another blueprint), only add the `### db-drizzle-postgres maintenance` subsection — do not duplicate the heading.
215
-
216
- ## Step 6: Output Summary
217
-
218
- After scaffolding, provide the user with a clear summary:
219
-
220
- ### Packages to Install
221
-
222
- List every package that needs to be installed. Adjust based on project type and what's already installed:
223
-
224
- **If monorepo:**
225
- ```bash
226
- # In packages/db/
227
- pnpm add drizzle-orm dotenv
228
- pnpm add -D drizzle-kit pg @types/pg tsx typescript
229
- ```
230
-
231
- **If single-repo:**
232
- ```bash
233
- # At project root
234
- pnpm add drizzle-orm dotenv
235
- pnpm add -D drizzle-kit pg @types/pg tsx
236
- ```
237
-
238
- ### Environment Variables
239
-
240
- ```env
241
- # Monorepo: packages/db/.env | Single-repo: .env at root
242
- {{GROUP_UPPER}}_DATABASE_URL=postgresql://user:password@localhost:5432/{{GROUP}}_db
243
- ```
244
-
245
- ### Manual Steps Remaining
246
-
247
- 1. **Create a PostgreSQL database** — `createdb {{GROUP}}_db` (or use your database hosting provider)
248
- 2. **Set DATABASE_URL** — update the `.env` file with your actual connection string
249
- 3. **Install dependencies** — `pnpm install` from the project root
250
- 4. **Generate initial migration** — `pnpm db:generate`
251
- 5. **Apply migration** — `pnpm db:migrate`
252
- 6. **Verify** — `pnpm db:studio` (should open Drizzle Studio showing your tables)
253
- 7. **(Optional) Run seed** — `pnpm db:seed` (inserts sample data)
254
-
255
- ### Files Created
256
-
257
- List every file that was created or modified, with a one-line description.
258
-
259
- ### Next Steps
260
-
261
- - Replace the example entity with your actual domain entities
262
- - For each new entity: copy the example file pattern, then follow the "Adding New Entities" checklist in BLUEPRINT.md
263
- - If you need authentication: run `/scaffold-auth` — it will add auth schemas to the existing `packages/db/`
264
-
265
- ## Important Notes
266
-
267
- - When adapting code, preserve the `// CONFIGURE:` comments so the user can find customization points later.
268
- - If the project structure differs significantly from the blueprint's assumptions, explain the differences and suggest how to adapt rather than forcing the blueprint's structure.
269
- - Never overwrite existing files without asking. If a file exists (like `package.json` or `turbo.json`), merge the new additions into it.
270
- - If `packages/db/` already exists from the auth blueprint, be especially careful to merge — not overwrite — the `package.json` exports, scripts, and dependencies.
@@ -1,179 +0,0 @@
1
- # Project Audit
2
-
3
- Run a health check against available blueprints. Analyze this project's current state and recommend improvements, missing best practices, or blueprints that could replace hand-rolled infrastructure. This command is read-only — it does not modify any files.
4
-
5
- ## Step 1: Read Available Blueprints
6
-
7
- Load all available blueprint specs to understand what is possible:
8
-
9
- ```
10
- ~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/BLUEPRINT.md
11
- ~/Documents/WithMata/my-blueprints/blueprints/foundation/monorepo-turbo/BLUEPRINT.md
12
- ~/Documents/WithMata/my-blueprints/blueprints/features/auth-better-auth/BLUEPRINT.md
13
- ```
14
-
15
- Also scan for any additional feature blueprints:
16
-
17
- ```
18
- ~/Documents/WithMata/my-blueprints/blueprints/features/*/BLUEPRINT.md
19
- ```
20
-
21
- Only consider a blueprint "available" if its BLUEPRINT.md has `Status: Complete`. If not found at these paths, ask the user for the path to their blueprints repo.
22
-
23
- ## Step 2: Read Project Context
24
-
25
- Check if `.project-context.md` exists in this project root.
26
-
27
- - **If it exists**: read it fully. Note which stages are complete (Discovery, Foundation, Installed Blueprints) and what choices were made.
28
- - **If it does not exist**: note this — it means either no blueprints have been used, or the project predates the blueprint system.
29
-
30
- ## Step 3: Explore the Project
31
-
32
- Regardless of whether project context exists, explore the actual project to understand its true state. If `.project-context.md` contradicts what you find in the actual files, trust the files and note the discrepancy.
33
-
34
- ### 3a. Product & Planning
35
-
36
- - Does `docs/product/` exist? Are there product briefs, user stories, or discovery artifacts?
37
- - Is there any structured product documentation, or just a README?
38
-
39
- ### 3b. Project Structure & Type
40
-
41
- - **Detect project type:**
42
- - **Monorepo indicators**: `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, or `"workspaces"` in root `package.json`
43
- - **Single-repo indicators**: Single `package.json` at root, `src/` directory, no workspace config
44
- - Record as `monorepo` or `single-repo` in the report
45
- - What package manager? Check for `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`, `bun.lock`
46
- - If monorepo: What workspaces exist? List `apps/`, `packages/`, `apis/`, `config/` or equivalent
47
- - Is there a `biome.json`? ESLint config? Prettier config?
48
- - Is TypeScript strict? Check `tsconfig.json` for `strict: true` and `noUncheckedIndexedAccess`
49
- - Are there shared config packages? Or is config duplicated?
50
-
51
- ### 3c. Authentication
52
-
53
- - Is there an auth system? Search for:
54
- - Better Auth config files (`better-auth`, `createAuthClient`)
55
- - NextAuth/Auth.js files (`auth.ts`, `[...nextauth]`, `authOptions`)
56
- - Hand-rolled auth (JWT imports, `bcrypt`, `jsonwebtoken`, session handling in middleware)
57
- - Third-party services (Clerk, Auth0, Supabase auth, Firebase auth)
58
- - Are there login/signup pages? Route protection middleware?
59
- - Are there organization/team/workspace features?
60
-
61
- ### 3d. Database
62
-
63
- - Is Drizzle set up? Check for `drizzle.config.ts`, `drizzle-kit`
64
- - Other ORMs? Check for Prisma (`schema.prisma`), TypeORM, Knex
65
- - Is there a shared DB package, or is database access scattered?
66
-
67
- ### 3e. Styling & UI
68
-
69
- - Tailwind version? Check `tailwindcss` version in package.json — v3 (JS config) vs v4 (CSS config)
70
- - Is there a shared UI package, or are components duplicated?
71
- - Component library? shadcn/ui, Radix, MUI, Chakra?
72
-
73
- ### 3f. Environment & Validation
74
-
75
- - How are env vars handled? t3-env, raw `process.env`, dotenv only?
76
- - Is there input validation? Zod, Valibot, Yup, Joi?
77
-
78
- ### 3g. Code Quality
79
-
80
- - Are there patterns that diverge from best practices?
81
- - Default exports where named exports are preferred
82
- - Missing barrel exports (`index.ts`) in packages
83
- - File-type organization instead of feature-based
84
- - Missing or inconsistent error handling
85
-
86
- ### 3h. Blueprint Dependency Check
87
-
88
- For each blueprint listed under `## Installed Blueprints` in `.project-context.md`:
89
- - Read its `## Blueprint Dependencies` section from the BLUEPRINT.md
90
- - Check if each `required` dependency is also listed in Installed Blueprints
91
- - If a required dependency is missing, include it in the report as a recommendation
92
-
93
- Example finding: "auth-better-auth is installed but its required dependency db-drizzle-postgres is not. Auth created a minimal db structure that lacks the full schema-group patterns. Run `/scaffold-db` to add the complete db patterns — it will merge without overwriting auth files."
94
-
95
- ## Step 4: Generate the Audit Report
96
-
97
- Present findings as a structured report. Be concrete and specific — reference actual files and patterns found.
98
-
99
- ### Report Format
100
-
101
- ---
102
-
103
- **Project Audit: [project name or directory name]**
104
-
105
- ### Current State
106
-
107
- | Area | Status | Details |
108
- |------|--------|---------|
109
- | Product Discovery | [done / not found / partial] | [Brief note] |
110
- | Foundation / Structure | [done / partial / needs work] | [Brief note] |
111
- | Authentication | [blueprint / hand-rolled / third-party / none] | [Brief note] |
112
- | Database | [Drizzle / Prisma / other / none] | [Brief note] |
113
- | Styling | [Tailwind v4 / v3 / other] | [Brief note] |
114
- | Code Quality | [good / needs attention] | [Brief note] |
115
-
116
- ### Recommendations
117
-
118
- For each recommendation:
119
-
120
- 1. **[Priority: High/Medium/Low] [Category] — [One-line summary]**
121
- - **What we found:** [Specific observation referencing actual files]
122
- - **Why it matters:** [Impact on the project — explain for non-technical users too]
123
- - **Action:** [Exact command or step to fix it]
124
-
125
- ---
126
-
127
- ### Recommendation Priority Guidelines
128
-
129
- **High priority** — things that block progress or create real risk:
130
- - No auth system and the product needs user accounts
131
- - No monorepo structure in a multi-workspace project
132
- - Hand-rolled auth with security gaps (plain text passwords, no CSRF, no rate limiting)
133
- - Missing environment variable validation
134
-
135
- **Medium priority** — things that improve quality and maintainability:
136
- - A blueprint could replace hand-rolled infrastructure
137
- - Missing product documentation for a project still figuring out its direction
138
- - Inconsistent patterns across workspaces
139
- - Tailwind v3 when v4 is available
140
- - ESLint + Prettier when Biome could replace both
141
-
142
- **Low priority** — nice-to-haves:
143
- - Blueprints in development that are not yet available (mention them as "coming soon")
144
- - Style preferences that do not affect functionality
145
- - Optimizations for mature projects
146
-
147
- ## Step 5: Provide Actionable Next Steps
148
-
149
- End the report with a clear list of what to do, in recommended order:
150
-
151
- ### Next Steps
152
-
153
- ```
154
- # Run these in order — each one is independent, stop whenever you want
155
-
156
- 1. [command] # [what it does and why]
157
- 2. [command] # [what it does and why]
158
- ...
159
- ```
160
-
161
- For blueprint commands, use the slash command format: `/discover`, `/scaffold-foundation`, `/scaffold-auth`
162
-
163
- For non-blueprint improvements, include the actual shell commands or instructions.
164
-
165
- ## Tone Guidelines
166
-
167
- - **Be honest.** If the project is in great shape, say so. Do not manufacture recommendations.
168
- - **Be warm and accessible.** The user may be non-technical. Explain WHY something matters, not just what to do.
169
- - **Be specific.** "Your auth looks hand-rolled" is not helpful. "I found JWT signing in `lib/auth.ts` without CSRF protection — the auth blueprint handles this with Better Auth's built-in security" is helpful.
170
- - **Separate facts from opinions.** "You are using ESLint + Prettier" is a fact. "Biome could replace both with simpler config" is a recommendation — label it as such.
171
- - **Do not overwhelm.** Lead with the 3-5 most impactful recommendations. If there are many findings, prioritize.
172
- - **Celebrate what is done well.** If something follows best practices, acknowledge it briefly.
173
-
174
- ## Important Notes
175
-
176
- - This command is **read-only**. It does not modify any files — it only reads and reports.
177
- - Only recommend blueprints with `Status: Complete`. Mention planned blueprints (tailwind-v4, ui-shared-components) as "coming soon" if relevant, but do not suggest running commands for them.
178
- - If the project is empty or brand new, keep the report short: "This is a fresh project. Here is where to start." and suggest `/discover` or `/scaffold-foundation`.
179
- - If everything looks good, say so: "This project is in great shape. No immediate recommendations."
@@ -1,92 +0,0 @@
1
- # Run Product Discovery
2
-
3
- Run a rigorous product discovery session. This produces product documentation — no code is generated. The session is a structured 60-minute deep dive that transforms a raw idea into a defensible product strategy.
4
-
5
- ## Step 1: Read the Blueprint
6
-
7
- Read the full discovery blueprint and all templates:
8
-
9
- ```
10
- ~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/BLUEPRINT.md
11
- ~/Documents/WithMata/my-blueprints/blueprints/discovery/product-discovery/templates/*
12
- ```
13
-
14
- If not found at that path, ask the user for the path to their blueprints repo.
15
-
16
- The BLUEPRINT.md contains the full methodology: phased session structure, frameworks, operating principles, research strategy, challenge patterns, and quality checkpoints. Follow it precisely.
17
-
18
- ## Step 2: Check for Existing Discovery
19
-
20
- Check if `.project-context.md` exists and already contains a `## Product Discovery` section. If it does:
21
-
22
- - Show the user what was previously discovered
23
- - Ask: "Product discovery was already completed. Would you like to redo it (replaces existing), refine it (update specific sections), or skip?"
24
-
25
- ## Step 3: Run the Discovery Session
26
-
27
- Follow the full 5-phase discovery process documented in BLUEPRINT.md. The blueprint contains the complete methodology: phase structure, frameworks, operating principles, research strategy, challenge patterns, and quality gates. Follow it precisely. Do not abbreviate or skip phases.
28
-
29
- This is conversational — you are guiding the user through structured discovery, not filling in a form.
30
-
31
- Quick reference for the phases:
32
- 1. **Phase 1: Initial Framing** — what and who
33
- 2. **Phase 2: Problem Deep Dive** — root cause via 5 Whys
34
- 3. **Phase 3: User Definition** — archetypes and persona variations
35
- 4. **Phase 4: Solution Positioning** — competitive landscape and differentiation
36
- 5. **Phase 5: Synthesis** — distill findings for documentation
37
-
38
- ## Step 4: Verify Quality Checkpoints
39
-
40
- Before generating documentation, verify ALL quality checkpoints listed in BLUEPRINT.md pass. If any fail, continue probing — do not rush to documentation.
41
-
42
- ## Step 5: Generate Documentation
43
-
44
- Create the `docs/product/` directory structure in the target project. Use the templates from the blueprint as the structural guide — fill them with the session's findings.
45
-
46
- ```
47
- docs/
48
- └── product/
49
- ├── product-thesis.md
50
- ├── product-brief.md
51
- └── users/
52
- ├── archetype-[name].md # One per archetype identified
53
- └── research-summary.md
54
- ```
55
-
56
- See BLUEPRINT.md for document quality standards and writing guidelines for each document type. Do not create files beyond what's specified. Do not rename the structure.
57
-
58
- ## Step 6: Update Project Context
59
-
60
- Create or update `.project-context.md` in the target project root:
61
-
62
- - If the file does not exist, create it with a header and the `## Product Discovery` section
63
- - If the file exists but has no discovery section, add the discovery section after the header
64
- - If the file exists with a discovery section (user chose to redo), replace that section only
65
-
66
- Append this structured YAML block:
67
-
68
- ```yaml
69
- ## Product Discovery
70
- product_name: "<name>"
71
- problem_statement: "<one sentence>"
72
- core_pillars:
73
- - "<pillar 1>"
74
- - "<pillar 2>"
75
- - "<pillar 3>"
76
- primary_archetype: "<archetype name>"
77
- discovery_completed: <date>
78
- artifacts:
79
- - docs/product/product-thesis.md
80
- - docs/product/product-brief.md
81
- - docs/product/users/archetype-<name>.md
82
- - docs/product/users/research-summary.md
83
- ```
84
-
85
- ## Step 7: Summary
86
-
87
- Tell the user:
88
-
89
- - What documents were generated (list each with a one-line description)
90
- - Key findings: core pillars, primary archetype, main competitive gap
91
- - Critical assumptions that need validation
92
- - Suggest next step: "Run `/scaffold-foundation` to set up the project skeleton, or `/new-project` to continue the full workflow."