@withmata/blueprints 0.2.0 → 0.3.1
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/{.opencode/commands/audit.md → .claude/skills/audit/SKILL.md} +8 -6
- package/.claude/skills/blueprint-catalog/SKILL.md +52 -0
- package/.claude/{commands/discover.md → skills/discover/SKILL.md} +8 -3
- package/{.cursor/commands/new-blueprint.md → .claude/skills/new-blueprint/SKILL.md} +13 -8
- package/{.cursor/commands/new-project.md → .claude/skills/new-project/SKILL.md} +11 -6
- package/.claude/{commands/scaffold-auth.md → skills/scaffold-auth/SKILL.md} +24 -23
- package/{.cursor/commands/scaffold-db.md → .claude/skills/scaffold-db/SKILL.md} +17 -16
- package/.claude/{commands/scaffold-foundation.md → skills/scaffold-foundation/SKILL.md} +17 -16
- package/ENGINEERING.md +2 -2
- package/dist/index.js +210 -166
- package/package.json +6 -7
- package/.claude/commands/audit.md +0 -179
- package/.claude/commands/new-blueprint.md +0 -265
- package/.claude/commands/new-project.md +0 -230
- package/.claude/commands/scaffold-db.md +0 -270
- package/.cursor/commands/audit.md +0 -179
- package/.cursor/commands/discover.md +0 -92
- package/.cursor/commands/scaffold-auth.md +0 -310
- package/.cursor/commands/scaffold-foundation.md +0 -158
- package/.opencode/commands/discover.md +0 -96
- package/.opencode/commands/new-blueprint.md +0 -269
- package/.opencode/commands/new-project.md +0 -234
- package/.opencode/commands/scaffold-auth.md +0 -314
- package/.opencode/commands/scaffold-db.md +0 -274
- 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."
|