@polymorphism-tech/morph-spec 4.16.0 → 4.18.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.
- package/CLAUDE.md +36 -0
- package/README.md +2 -2
- package/bin/morph-spec.js +3 -0
- package/bin/task-manager.js +999 -962
- package/claude-plugin.json +1 -1
- package/docs/CHEATSHEET.md +1 -1
- package/docs/QUICKSTART.md +1 -1
- package/framework/agents/ai-agents/vector-search-expert.md +247 -233
- package/framework/agents/backend/ms-agent-expert.md +1 -1
- package/framework/agents/backend/neon-expert.md +379 -0
- package/framework/agents/frontend/gsap-animator.md +131 -0
- package/framework/agents/integrations/neon-auth.md +151 -0
- package/framework/agents.json +1183 -1085
- package/framework/commands/morph-preflight.md +200 -192
- package/framework/hooks/claude-code/session-start/inject-morph-context.js +1 -1
- package/framework/rules/gsap-standards.md +13 -0
- package/framework/rules/neon-auth-standards.md +13 -0
- package/framework/rules/neon-standards.md +26 -0
- package/framework/skills/level-0-meta/mcp-registry.json +1 -1
- package/framework/skills/level-0-meta/morph-agent-teams/SKILL.md +472 -472
- package/framework/skills/level-0-meta/morph-frontend-review/SKILL.md +1 -1
- package/framework/skills/level-0-meta/morph-init/SKILL.md +12 -12
- package/framework/skills/level-0-meta/morph-post-implementation/SKILL.md +5 -5
- package/framework/skills/level-0-meta/morph-tool-usage-guide/SKILL.md +5 -5
- package/framework/skills/level-0-meta/morph-tool-usage-guide/references/tools-per-phase.md +7 -7
- package/framework/skills/level-1-workflows/morph-phase-codebase-analysis/SKILL.md +24 -24
- package/framework/skills/level-1-workflows/morph-phase-design/SKILL.md +12 -12
- package/framework/skills/level-1-workflows/morph-phase-implement/SKILL.md +9 -9
- package/framework/skills/level-1-workflows/morph-phase-plan/SKILL.md +1 -1
- package/framework/skills/level-1-workflows/morph-phase-tasks/SKILL.md +1 -1
- package/framework/skills/level-1-workflows/morph-phase-tasks/references/task-planning-patterns.md +143 -143
- package/framework/skills/level-1-workflows/morph-phase-uiux/SKILL.md +1 -1
- package/framework/skills/level-1-workflows/morph-scope-escalation/SKILL.md +1 -1
- package/framework/standards/STANDARDS.json +197 -116
- package/framework/standards/ai-agents/production.md +1 -0
- package/framework/standards/ai-agents/setup.md +3 -2
- package/framework/standards/ai-agents/workflows.md +1 -0
- package/framework/standards/architecture/vertical-slice/vertical-slice.md +4 -4
- package/framework/standards/backend/database/postgresql/database.md +63 -83
- package/framework/standards/backend/dotnet/scalar-ui.md +172 -172
- package/framework/standards/backend/dotnet/vsa-handler-patterns.md +274 -274
- package/framework/standards/backend/integrations/asaas/asaas-api.md +2 -2
- package/framework/standards/backend/integrations/neon-auth/neon-auth.md +364 -0
- package/framework/standards/frontend/design-system/animations.md +9 -0
- package/framework/standards/frontend/gsap/gsap-core.md +463 -0
- package/framework/standards/frontend/gsap/gsap-plugins.md +294 -0
- package/framework/standards/frontend/gsap/gsap-scrolltrigger.md +318 -0
- package/framework/standards/frontend/nextjs/motion-patterns.md +1 -0
- package/framework/standards/frontend/nextjs/nextjs-patterns.md +47 -37
- package/framework/standards/infrastructure/docker/easypanel-deploy.md +4 -8
- package/framework/standards/infrastructure/neon/neon-pgrag.md +239 -0
- package/framework/standards/infrastructure/neon/neon-pgvector.md +236 -0
- package/framework/standards/infrastructure/neon/neon-semantic-kernel.md +310 -0
- package/framework/standards/infrastructure/neon/neon-setup.md +186 -0
- package/framework/standards/integration/mcp/mcp-tools.md +32 -34
- package/framework/templates/README.md +20 -20
- package/framework/templates/REGISTRY.json +54 -101
- package/framework/templates/code/dotnet/abstractions/api-endpoint.cs +7 -7
- package/framework/templates/code/dotnet/backend/repository.cs +148 -148
- package/framework/templates/code/dotnet/contracts/contracts-vsa.cs +2 -2
- package/framework/templates/code/dotnet/database/vector-entity.cs +93 -0
- package/framework/templates/code/dotnet/feature/endpoint.cs.hbs +1 -1
- package/framework/templates/code/sql/{supabase-migration.sql → postgresql-migration.sql} +12 -21
- package/framework/templates/code/sql/{supabase-migration.template.sql → postgresql-migration.template.sql} +13 -18
- package/framework/templates/code/sql/{rls-policy.sql → postgresql-rls-policy.sql} +6 -9
- package/framework/templates/code/typescript/contracts.ts +167 -168
- package/framework/templates/context/CONTEXT.md +3 -3
- package/framework/templates/docs/proposal.md +6 -6
- package/framework/templates/docs/ui-components.md +1 -1
- package/framework/templates/feature/decisions.md +122 -121
- package/framework/templates/feature/recap.md +145 -145
- package/framework/templates/feature/tasks.md +199 -199
- package/framework/templates/frontend/nextjs/gsap-scroll-section.tsx.hbs +44 -0
- package/framework/templates/infrastructure/docker/docker-compose.template.yml +50 -67
- package/framework/templates/infrastructure/docker/dockerfile-api.dockerfile +38 -38
- package/framework/templates/infrastructure/docker/dockerfile-web.dockerfile +48 -48
- package/framework/templates/infrastructure/docker/easypanel.template.json +46 -54
- package/framework/templates/infrastructure/github/README.md +56 -56
- package/framework/templates/integrations/neon-auth-config.cs +133 -0
- package/framework/templates/integrations/semantic-kernel-neon.cs +125 -0
- package/framework/workflows/README.md +1 -1
- package/framework/workflows/docs/full-morph.md +69 -69
- package/package.json +1 -1
- package/src/commands/agents/dispatch-agents.js +19 -15
- package/src/commands/state/advance-phase.js +5 -0
- package/src/commands/tasks/task.js +3 -0
- package/src/core/state/state-manager.js +45 -1
- package/src/core/templates/template-registry.js +1 -66
- package/src/lib/detectors/index.js +4 -4
- package/src/lib/generators/architecture-scanner.js +639 -640
- package/src/lib/installers/mcp-installer.js +1 -1
- package/src/lib/tasks/task-classifier.js +15 -1
- package/src/lib/tasks/test-runner.js +5 -1
- package/src/lib/validators/content/content-validator.js +9 -10
- package/src/lib/validators/validation-runner.js +7 -5
- package/framework/agents/backend/supabase-expert.md +0 -256
- package/framework/agents/integrations/clerk-auth.md +0 -109
- package/framework/rules/clerk-standards.md +0 -13
- package/framework/rules/supabase-standards.md +0 -29
- package/framework/standards/backend/integrations/clerk/clerk-auth.md +0 -290
- package/framework/standards/infrastructure/supabase/mcp-setup.md +0 -142
- package/framework/standards/infrastructure/supabase/supabase-auth.md +0 -176
- package/framework/standards/infrastructure/supabase/supabase-custom-jwt.md +0 -206
- package/framework/standards/infrastructure/supabase/supabase-pgvector.md +0 -169
- package/framework/standards/infrastructure/supabase/supabase-rls.md +0 -184
- package/framework/standards/infrastructure/supabase/supabase-storage.md +0 -153
- package/framework/templates/integrations/clerk-config.cs +0 -217
|
@@ -10,7 +10,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion,
|
|
|
10
10
|
mcp__playwright__browser_navigate, mcp__playwright__browser_resize,
|
|
11
11
|
mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot,
|
|
12
12
|
mcp__playwright__browser_evaluate, mcp__playwright__browser_console_messages
|
|
13
|
-
cliVersion: "4.
|
|
13
|
+
cliVersion: "4.18.0"
|
|
14
14
|
stacks:
|
|
15
15
|
- nextjs
|
|
16
16
|
---
|
|
@@ -101,28 +101,28 @@ Gather evidence to build a stack map. Run these in parallel:
|
|
|
101
101
|
|
|
102
102
|
| Tool | Pattern | Signal |
|
|
103
103
|
|------|---------|--------|
|
|
104
|
-
| `Glob` | `**/package.json` | Detect next,
|
|
104
|
+
| `Glob` | `**/package.json` | Detect next, neon, @neondatabase/auth, stripe in deps |
|
|
105
105
|
| `Glob` | `**/*.csproj` | .NET projects at any depth |
|
|
106
106
|
| `Glob` | `**/next.config.{js,ts,mjs}` | Next.js in any subdirectory |
|
|
107
107
|
| `Glob` | `**/components.json` | shadcn/ui |
|
|
108
108
|
| `Glob` | `**/docker-compose*.yml` | Container services |
|
|
109
|
-
| `Glob` | `database/migrations/**` |
|
|
110
|
-
| `
|
|
109
|
+
| `Glob` | `database/migrations/**` | Database migrations |
|
|
110
|
+
| `Grep` | `DATABASE_URL\|NEON_\|neonctl` | Neon database config |
|
|
111
111
|
|
|
112
112
|
| `Glob` | `**/Abstractions/IHandler.cs` | VSA pattern (KanaiyaKatarmal) |
|
|
113
113
|
| `Glob` | `**/Pipelines/ValidationDecorator.cs` | VSA pipeline |
|
|
114
114
|
| `Glob` | `**/Features/**/*Feature` | VSA feature folder suffix |
|
|
115
115
|
| `Read` | `.env.example` | Env vars reveal integrations |
|
|
116
116
|
| `Read` | `README.md` | Existing project description |
|
|
117
|
-
| `Grep` | `@
|
|
118
|
-
| `Grep` |
|
|
117
|
+
| `Grep` | `@neondatabase/serverless` | Neon dep in any package.json |
|
|
118
|
+
| `Grep` | `@neondatabase/auth\|auth0\|nextauth` | Auth provider |
|
|
119
119
|
| `Grep` | `stripe\|asaas` | Payment provider |
|
|
120
120
|
|
|
121
121
|
Read each found `package.json` for dependency names. Build an **evidence map**:
|
|
122
122
|
|
|
123
123
|
```
|
|
124
124
|
stack: [nextjs, dotnet, ...]
|
|
125
|
-
integrations: [
|
|
125
|
+
integrations: [neon, docker, neon-auth, ...]
|
|
126
126
|
uiLibrary: shadcn | null
|
|
127
127
|
monorepo: true | false
|
|
128
128
|
frontendPath: src/frontend (if monorepo)
|
|
@@ -147,7 +147,7 @@ Ask at most 3 questions, only those that apply:
|
|
|
147
147
|
|---|----------|-----------|---------|
|
|
148
148
|
| 1 | *"In one sentence: what is the main purpose of **[ProjectName]**?"* | Always | README.md Overview |
|
|
149
149
|
| 2 | *"Confirmed: frontend at `{frontendPath}`, backend at `{backendPath}`. Correct?"* | Monorepo detected | Validate paths before persisting |
|
|
150
|
-
| 3 | *"
|
|
150
|
+
| 3 | *"Neon (cloud PostgreSQL) or self-hosted Postgres?"* | Neon detected | Database configuration |
|
|
151
151
|
|
|
152
152
|
Do **not** ask about technology already confirmed by file evidence.
|
|
153
153
|
|
|
@@ -326,7 +326,7 @@ Read `.morph/config/config.json` and merge into `project`:
|
|
|
326
326
|
"stack": "[stacks joined with +, e.g. nextjs+dotnet]",
|
|
327
327
|
"architecture": "[monorepo | single-stack | detected pattern]",
|
|
328
328
|
"uiLibrary": "[detected or null]",
|
|
329
|
-
"integrations": ["
|
|
329
|
+
"integrations": ["neon", "docker", "neon-auth"],
|
|
330
330
|
"frontendPath": "[path if monorepo, else omit]",
|
|
331
331
|
"backendPath": "[path if monorepo, else omit]"
|
|
332
332
|
}
|
|
@@ -385,9 +385,9 @@ Output confirms: `✓ setup-infra (reinstall): complete.`
|
|
|
385
385
|
|
|
386
386
|
For each detected integration with an available MCP:
|
|
387
387
|
|
|
388
|
-
**
|
|
389
|
-
> *"
|
|
390
|
-
> No MCP configuration needed — CLI is the primary
|
|
388
|
+
**Neon detected:**
|
|
389
|
+
> *"Neon database detected. Use `neonctl` for branch management and `psql` for direct database operations."*
|
|
390
|
+
> No MCP configuration needed — CLI is the primary tool for Neon interaction.
|
|
391
391
|
|
|
392
392
|
**GitHub:**
|
|
393
393
|
> *"Configure GitHub MCP? Requires Docker + a `GITHUB_PERSONAL_ACCESS_TOKEN`."*
|
|
@@ -421,7 +421,7 @@ Only offer Docker, Azure if explicitly detected in `.env.example`.
|
|
|
421
421
|
|
|
422
422
|
> **Format rules for MCP configs:**
|
|
423
423
|
>
|
|
424
|
-
> **Remote MCPs** (
|
|
424
|
+
> **Remote MCPs** (Vercel) — no credentials, OAuth-based:
|
|
425
425
|
> ```json
|
|
426
426
|
> "mcp-name": { "type": "http", "url": "https://mcp.example.com" }
|
|
427
427
|
> ```
|
|
@@ -104,11 +104,11 @@ Read validation output, fix reported issues, and re-run until it passes.
|
|
|
104
104
|
|
|
105
105
|
---
|
|
106
106
|
|
|
107
|
-
### Step 4b — Verify RLS Policies (
|
|
107
|
+
### Step 4b — Verify RLS Policies (Neon/PostgreSQL projects)
|
|
108
108
|
|
|
109
|
-
> **
|
|
109
|
+
> **Neon CLI (`neonctl`):** If the project uses Neon/PostgreSQL, verify RLS policies on the database:
|
|
110
110
|
>
|
|
111
|
-
> 1. Get DB URL: `
|
|
111
|
+
> 1. Get DB URL: `neonctl connection-string`
|
|
112
112
|
> 2. Query: `psql <DB_URL> -c "SELECT tablename, policyname, cmd, qual FROM pg_policies WHERE schemaname = 'public'"`
|
|
113
113
|
> 3. For each table modified in this feature, verify:
|
|
114
114
|
> - [ ] RLS is enabled (`ALTER TABLE ... ENABLE ROW LEVEL SECURITY`)
|
|
@@ -116,13 +116,13 @@ Read validation output, fix reported issues, and re-run until it passes.
|
|
|
116
116
|
> - [ ] INSERT/UPDATE/DELETE policies match feature requirements
|
|
117
117
|
> 4. If any table is missing RLS → **flag as CRITICAL** (blocks PR)
|
|
118
118
|
>
|
|
119
|
-
> If
|
|
119
|
+
> If Neon database is not accessible, check for RLS policy files in the `migrations/` directory and verify they cover modified tables. If no Neon/PostgreSQL in the stack, skip this step.
|
|
120
120
|
|
|
121
121
|
---
|
|
122
122
|
|
|
123
123
|
## Step 5 — Smoke Test (Playwright MCP)
|
|
124
124
|
|
|
125
|
-
> **Docker CLI:** Before smoke testing, verify local services are running: `docker ps --format "table {{.Names}}\t{{.Status}}"` — all expected containers should show "Up".
|
|
125
|
+
> **Docker CLI:** Before smoke testing, verify local services are running: `docker ps --format "table {{.Names}}\t{{.Status}}"` — all expected containers should show "Up".
|
|
126
126
|
|
|
127
127
|
> **MCP:** Smoke testing via **Playwright MCP** is the primary method. If Playwright MCP is not available, fall back to `curl`/`WebFetch` for endpoint verification (limited — cannot test JS-rendered pages or interactions).
|
|
128
128
|
|
|
@@ -137,10 +137,10 @@ Criterion: if reading file B does not depend on the CONTENT of file A, read both
|
|
|
137
137
|
|-------|-------------|---------------------|
|
|
138
138
|
| Proposal | GitHub (optional) | No |
|
|
139
139
|
| UI/UX | Playwright, Context7 | No |
|
|
140
|
-
| Design |
|
|
140
|
+
| Design | Neon CLI, Context7, GitHub | Yes (architect + schema in parallel) |
|
|
141
141
|
| Plan | Context7, GitHub | No |
|
|
142
142
|
| Tasks | Context7, GitHub | Yes (when spec has 20+ reqs or 3+ domains) |
|
|
143
|
-
| Implement |
|
|
143
|
+
| Implement | Neon CLI, Context7, Playwright, GitHub | Yes (when tasks.total ≥ 6 and 2+ domains) |
|
|
144
144
|
|
|
145
145
|
---
|
|
146
146
|
|
|
@@ -164,7 +164,7 @@ Criterion: if reading file B does not depend on the CONTENT of file A, read both
|
|
|
164
164
|
|
|
165
165
|
| MCP | When to Use | Fallback |
|
|
166
166
|
|-----|-------------|----------|
|
|
167
|
-
| **
|
|
167
|
+
| **Neon CLI (`neonctl`) + `psql`** | Schema analysis, migrations, RLS | Grep + Read code files |
|
|
168
168
|
| **GitHub** | Issues, PRs, repo metadata, code search | Bash `gh` CLI |
|
|
169
169
|
| **Context7** | Library documentation lookups | WebSearch + WebFetch |
|
|
170
170
|
| **Playwright** | Browser automation, screenshots, page inspection, smoke tests | WebFetch (read-only), Manual testing |
|
|
@@ -215,9 +215,9 @@ For the canonical list of MCPs, their tools, phase relevance, and fallbacks, see
|
|
|
215
215
|
| Proposal | Context7 | WebSearch |
|
|
216
216
|
| Setup | GitHub | `gh` CLI |
|
|
217
217
|
| UI/UX | Playwright, Context7 | WebFetch, Read CSS |
|
|
218
|
-
| Design |
|
|
218
|
+
| Design | Neon CLI, Context7, GitHub | Grep + Read code |
|
|
219
219
|
| Tasks | Context7, GitHub | WebSearch, `gh` CLI |
|
|
220
|
-
| Implement |
|
|
220
|
+
| Implement | Neon CLI, Context7, Playwright, GitHub | CLI tools |
|
|
221
221
|
|
|
222
222
|
### Detected Plugins & MCPs
|
|
223
223
|
|
|
@@ -68,7 +68,7 @@
|
|
|
68
68
|
| **Get dispatch config** | **Bash** `morph-spec dispatch-agents {feature} design` | Which agents to spawn + their task prompts |
|
|
69
69
|
| **Dispatch architecture analyst** (parallel) | **Task** subagent with prompt from dispatch config | Analyze architecture complexity independently |
|
|
70
70
|
| **Dispatch tech leads** (parallel) | **Task** subagents (dotnet-senior, nextjs-expert, etc.) | Validate architecture independently |
|
|
71
|
-
| Get database schema | **Bash** `
|
|
71
|
+
| Get database schema | **Bash** `pg_dump $(neonctl connection-string)` or `psql <DB_URL>` | **PREFERRED** — real schema |
|
|
72
72
|
| Get table relationships | **Bash** `psql <DB_URL>` FK queries | Real FK/constraint data |
|
|
73
73
|
| Get RLS policies | **Bash** `psql <DB_URL>` pg_policies query | Security analysis |
|
|
74
74
|
| **Fallback:** Find query files | **Grep** `\.from\(` or `\.select\(` in `*.ts,*.tsx,*.js,*.cs` | When no DB MCP available |
|
|
@@ -83,14 +83,14 @@
|
|
|
83
83
|
| Create schema-analysis.md | **Write** to output directory | Document findings |
|
|
84
84
|
| Update state | **Bash** `morph-spec state mark-output {feature} schemaAnalysis && morph-spec state mark-output {feature} spec && morph-spec state mark-output {feature} contracts && morph-spec state mark-output {feature} decisions` | CLI command |
|
|
85
85
|
|
|
86
|
-
**Tools used:**
|
|
86
|
+
**Tools used:** Neon CLI (`neonctl`) / psql (schema analysis), Context7 (library research), GitHub (code search).
|
|
87
87
|
|
|
88
88
|
**Parallel dispatch opportunity:** Architecture complexity analysis and schema analysis (phase-codebase-analysis) are **independent** — run them as parallel Task subagents to cut design phase time.
|
|
89
89
|
|
|
90
90
|
**Anti-patterns:**
|
|
91
91
|
- ❌ Guessing field names without checking schema (use MCP or Grep first!)
|
|
92
92
|
- ❌ Task agent to read a single spec file (use Read directly)
|
|
93
|
-
- ❌ WebSearch for database schema (use
|
|
93
|
+
- ❌ WebSearch for database schema (use Neon CLI/psql or code analysis)
|
|
94
94
|
- ❌ Manually writing contracts-level{N}.cs from scratch (use template render)
|
|
95
95
|
- ❌ Running domain analysis and schema analysis sequentially (they're independent — run in parallel)
|
|
96
96
|
|
|
@@ -138,12 +138,12 @@
|
|
|
138
138
|
| Create new files | **Write** new source files | New entities, services, pages |
|
|
139
139
|
| Modify existing files | **Edit** existing source files | Add features to existing code |
|
|
140
140
|
| Look up API during coding | **Context7 MCP** `query_docs()` | Accurate library usage |
|
|
141
|
-
| Run database migrations | **Bash** `
|
|
142
|
-
| **Fallback:** Run migrations | **Bash** `
|
|
141
|
+
| Run database migrations | **Bash** `dotnet ef database update` | DDL via psql |
|
|
142
|
+
| **Fallback:** Run migrations | **Bash** `dotnet ef ...` or `psql` | CLI tools |
|
|
143
143
|
| Build project | **Bash** `dotnet build` or `npm run build` | Verify compilation |
|
|
144
144
|
| Run tests | **Bash** `dotnet test` or `npm test` | Verify implementation |
|
|
145
145
|
| Checkpoint validation | **Bash** `morph-spec checkpoint ...` | Every 3 tasks |
|
|
146
|
-
| Create RLS policies | **Bash** write SQL migration + `
|
|
146
|
+
| Create RLS policies | **Bash** write SQL migration + `dotnet ef database update` | Security policies |
|
|
147
147
|
| Manage containers | **Bash** `docker ps`, `docker logs`, `docker compose` | Container health + debugging |
|
|
148
148
|
| Create infrastructure | **Bash** `az bicep ...` or Bicep files via Write | IaC |
|
|
149
149
|
| Create PR | **GitHub MCP** `create_pull_request()` or **Bash** `gh pr create` | Ship code |
|
|
@@ -153,7 +153,7 @@
|
|
|
153
153
|
| Screenshot para recap.md | **Playwright MCP** `browser_take_screenshot()` | Manual screenshot |
|
|
154
154
|
| Mark recap output | **Bash** `morph-spec state mark-output {feature} recap` | CLI command |
|
|
155
155
|
|
|
156
|
-
**Tools used:**
|
|
156
|
+
**Tools used:** Neon CLI (`neonctl`) / EF Core CLI (migrations), Context7 (API lookup), GitHub (PRs), Playwright (smoke test, verification).
|
|
157
157
|
|
|
158
158
|
**Parallel dispatch threshold:**
|
|
159
159
|
- `tasks.total ≥ 6` AND feature spans 2+ domains (e.g. `dotnet-senior` + `nextjs-expert`) → dispatch parallel implementers
|
|
@@ -3,7 +3,7 @@ name: morph-phase-codebase-analysis
|
|
|
3
3
|
description: MORPH-SPEC Design sub-phase that analyzes existing codebase and database schema, producing schema-analysis.md with real column names, types, relationships, and field mismatches. Use at the start of Design phase before generating contracts.cs to prevent incorrect field names or types.
|
|
4
4
|
user-invocable: false
|
|
5
5
|
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
|
|
6
|
-
cliVersion: "4.
|
|
6
|
+
cliVersion: "4.18.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# MORPH Codebase Analysis - Design Sub-phase
|
|
@@ -26,7 +26,7 @@ Automates existing code analysis to generate `schema-analysis.md` with real data
|
|
|
26
26
|
|
|
27
27
|
| Action | Tool | Alternative |
|
|
28
28
|
|------|------------|-------------|
|
|
29
|
-
| List database tables | **Bash** `
|
|
29
|
+
| List database tables | **Bash** `pg_dump $(neonctl connection-string)` or `psql <DB_URL>` | **Grep** `.from(` in code |
|
|
30
30
|
| Get table schema | **Bash** `psql <DB_URL> -c "SELECT ... FROM information_schema.columns"` | **Read** type definitions |
|
|
31
31
|
| Get FK relationships | **Bash** `psql <DB_URL> -c "SELECT ... FROM information_schema.table_constraints"` | **Grep** JOIN/FK patterns |
|
|
32
32
|
| Get RLS policies | **Bash** `psql <DB_URL> -c "SELECT ... FROM pg_policies"` | **Read** policy files |
|
|
@@ -36,7 +36,7 @@ Automates existing code analysis to generate `schema-analysis.md` with real data
|
|
|
36
36
|
| Complex multi-file analysis | **Task** (subagent Explore) | Read individual |
|
|
37
37
|
| Generate schema-analysis.md | **Write** using template | **Bash** template render |
|
|
38
38
|
|
|
39
|
-
**Tools for this phase:**
|
|
39
|
+
**Tools for this phase:** Neon CLI (`neonctl`) / psql (schema — **PRIORITY**), Generic database CLIs.
|
|
40
40
|
|
|
41
41
|
---
|
|
42
42
|
|
|
@@ -48,37 +48,37 @@ Automates existing code analysis to generate `schema-analysis.md` with real data
|
|
|
48
48
|
Verify first with a test call before attempting to use it.
|
|
49
49
|
|
|
50
50
|
```
|
|
51
|
-
0. **
|
|
52
|
-
→ IF
|
|
53
|
-
→ Ask user via AskUserQuestion:
|
|
51
|
+
0. **Database connectivity check:** Run `neonctl connection-string` to verify Neon CLI is configured.
|
|
52
|
+
→ IF Neon CLI is not configured → warn user: "Neon CLI not configured — run `neonctl auth`."
|
|
53
|
+
→ Ask user via AskUserQuestion: configure Neon or fall back to Method B.
|
|
54
54
|
|
|
55
|
-
1. IF
|
|
56
|
-
→ Run `
|
|
55
|
+
1. IF Neon/PostgreSQL database detected (DATABASE_URL env var exists OR config.json stack includes database):
|
|
56
|
+
→ Run `neonctl connection-string` to get the DB URL
|
|
57
57
|
→ IF running (exit 0): extract DB URL from output → Use Method A (direct CLI/psql)
|
|
58
58
|
→ IF not running (exit non-zero):
|
|
59
|
-
→ Log: "
|
|
60
|
-
→ Ask user via AskUserQuestion:
|
|
59
|
+
→ Log: "Neon database not accessible — run `neonctl auth`"
|
|
60
|
+
→ Ask user via AskUserQuestion: configure it or fall back to Method B
|
|
61
61
|
|
|
62
|
-
2. IF no
|
|
62
|
+
2. IF no Neon/PostgreSQL database detected:
|
|
63
63
|
→ Use Method B (static code analysis)
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
-
**Signs of unavailable
|
|
67
|
-
- `
|
|
68
|
-
-
|
|
69
|
-
- Project uses database other than
|
|
66
|
+
**Signs of unavailable Neon database:**
|
|
67
|
+
- `neonctl connection-string` exits with non-zero code
|
|
68
|
+
- Neon CLI not authenticated or project not configured
|
|
69
|
+
- Project uses database other than Neon (CloudSQL, RDS, Azure SQL, etc.)
|
|
70
70
|
|
|
71
|
-
### Step 2A: CLI Method (Preferred —
|
|
71
|
+
### Step 2A: CLI Method (Preferred — Neon CLI)
|
|
72
72
|
|
|
73
|
-
**Tools:** Bash (
|
|
73
|
+
**Tools:** Bash (Neon CLI + psql)
|
|
74
74
|
|
|
75
75
|
```bash
|
|
76
|
-
# 0. Get
|
|
77
|
-
|
|
78
|
-
# →
|
|
76
|
+
# 0. Get DB URL
|
|
77
|
+
neonctl connection-string
|
|
78
|
+
# → Returns connection string, e.g.: postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/neondb
|
|
79
79
|
|
|
80
80
|
# 1. List all tables
|
|
81
|
-
|
|
81
|
+
pg_dump $(neonctl connection-string) --schema public 2>/dev/null | grep "CREATE TABLE"
|
|
82
82
|
|
|
83
83
|
# 2. For each feature-relevant table:
|
|
84
84
|
|
|
@@ -107,7 +107,7 @@ psql $DB_URL -c "SELECT policyname, cmd, qual FROM pg_policies WHERE tablename =
|
|
|
107
107
|
**Phase B1: Find Queries**
|
|
108
108
|
|
|
109
109
|
```
|
|
110
|
-
Grep: "\.from\(|\.select\(|SELECT |
|
|
110
|
+
Grep: "\.from\(|\.select\(|SELECT |context\.|dbContext\.|DbSet<"
|
|
111
111
|
Type: ts,tsx,js,jsx,cs
|
|
112
112
|
Output: files_with_matches
|
|
113
113
|
```
|
|
@@ -138,12 +138,12 @@ Glob: "**/Models/**/*.cs"
|
|
|
138
138
|
|
|
139
139
|
Use Task subagent **ONLY** when:
|
|
140
140
|
- Project has 20+ query files
|
|
141
|
-
- Multiple data access patterns (
|
|
141
|
+
- Multiple data access patterns (Neon + EF Core + raw SQL)
|
|
142
142
|
- Precise cross-context analysis across many files
|
|
143
143
|
|
|
144
144
|
Do not use Task subagent when:
|
|
145
145
|
- Project has < 10 query files (direct Read is faster)
|
|
146
|
-
- Data access pattern is uniform (only
|
|
146
|
+
- Data access pattern is uniform (only Neon OR only EF Core)
|
|
147
147
|
|
|
148
148
|
### Step 2B-Format: Standardized Format for Static Analysis
|
|
149
149
|
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: morph-phase-design
|
|
3
|
-
description: MORPH-SPEC Phase 2 (Design). Schema-first interactive design: reads EF models/
|
|
3
|
+
description: MORPH-SPEC Phase 2 (Design). Schema-first interactive design: reads EF models/Neon PostgreSQL/DB, validates findings with user, then generates VSA Blueprint based on config.architecture.style, producing spec.md, contracts.cs, schema-analysis.md, and decisions.md through a unified quality + clarification loop (score 0-100). Use after proposal phase to create technical specifications grounded in the real database schema.
|
|
4
4
|
argument-hint: "[feature-name]"
|
|
5
5
|
user-invocable: false
|
|
6
6
|
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
|
|
7
|
-
cliVersion: "4.
|
|
7
|
+
cliVersion: "4.18.0"
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
# MORPH Design — Phase 2
|
|
@@ -28,7 +28,7 @@ Schema-first interactive design: read the real schema, validate with user, gener
|
|
|
28
28
|
|--------|------|-------------|
|
|
29
29
|
| Read proposal + UI specs | **Read** output files | — |
|
|
30
30
|
| **Detect architecture** | **Read** `.morph/config/config.json` → check `architecture.style` | **Bash** `grep` |
|
|
31
|
-
| **Schema:
|
|
31
|
+
| **Schema: Neon PostgreSQL** | **Bash** `neonctl connection-string` → `pg_dump $(neonctl connection-string)` / `psql <DB_URL>` | **Grep** `.from(` in code |
|
|
32
32
|
| **Schema: EF Core** | **Glob** `**/Entities/**/*.cs` + **Glob** `**/*Context.cs` → **Read** | **Grep** `DbSet<` |
|
|
33
33
|
| **Schema: Next.js/TS** | **Glob** `src/**/types/**/*.ts` + **Grep** `interface\|type.*=` | — |
|
|
34
34
|
| Schema: RLS policies | **Bash** `psql <DB_URL> -c "SELECT ... FROM pg_policies"` | **Read** policy files |
|
|
@@ -53,8 +53,8 @@ Schema-first interactive design: read the real schema, validate with user, gener
|
|
|
53
53
|
## Pre-flight — Tool Availability
|
|
54
54
|
|
|
55
55
|
Check session context lines for tool readiness:
|
|
56
|
-
- `
|
|
57
|
-
- `
|
|
56
|
+
- `neonctl ✓` → Neon CLI method for schema analysis
|
|
57
|
+
- `neonctl ✗` → Static code analysis fallback (Grep/Read)
|
|
58
58
|
- `context7 ✓` → Use for library docs when writing spec.md
|
|
59
59
|
- `context7 ✗` → WebSearch + WebFetch fallback
|
|
60
60
|
|
|
@@ -116,16 +116,16 @@ If scope ≥ 20 tasks or refactor touches ≥ 5 domain files → **EnterPlanMode
|
|
|
116
116
|
|
|
117
117
|
Execute in parallel according to the stack detected in `config.json`:
|
|
118
118
|
|
|
119
|
-
**
|
|
119
|
+
**Neon PostgreSQL (via Neon CLI):**
|
|
120
120
|
|
|
121
|
-
> **
|
|
122
|
-
> Then use `
|
|
123
|
-
>
|
|
124
|
-
> If
|
|
121
|
+
> **Neon CLI (`neonctl`):** Run `neonctl connection-string` to get the DB URL.
|
|
122
|
+
> Then use `pg_dump $(neonctl connection-string)` for full schema export, or `psql <DB_URL>` for targeted queries.
|
|
123
|
+
> Cross-reference existing schema with the proposal to avoid duplicating tables or missing foreign keys to existing data.
|
|
124
|
+
> If Neon database is not accessible, rely on EF Core/TypeScript entity scanning as described below.
|
|
125
125
|
|
|
126
126
|
```
|
|
127
|
-
Bash:
|
|
128
|
-
+
|
|
127
|
+
Bash: neonctl connection-string → extract DB URL
|
|
128
|
+
+ pg_dump $(neonctl connection-string) | grep -A20 "CREATE TABLE relevant_table"
|
|
129
129
|
+ psql <DB_URL> -c "SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = 'X'"
|
|
130
130
|
+ psql <DB_URL> -c "SELECT tablename, policyname, cmd, qual FROM pg_policies WHERE schemaname = 'public'"
|
|
131
131
|
```
|
|
@@ -5,7 +5,7 @@ argument-hint: "[feature-name]"
|
|
|
5
5
|
context: fork
|
|
6
6
|
agent: general-purpose
|
|
7
7
|
user-invocable: false
|
|
8
|
-
cliVersion: "4.
|
|
8
|
+
cliVersion: "4.18.0"
|
|
9
9
|
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
|
|
10
10
|
---
|
|
11
11
|
|
|
@@ -81,9 +81,9 @@ Before starting tasks, verify that CLIs and MCPs needed for this phase are avail
|
|
|
81
81
|
|
|
82
82
|
| CLI | Required for | If missing |
|
|
83
83
|
|-----|-------------|------------|
|
|
84
|
-
| `docker` | Container services (
|
|
85
|
-
| `
|
|
86
|
-
| `psql` | Direct DB queries |
|
|
84
|
+
| `docker` | Container services (Redis, etc.) | Start Docker Desktop |
|
|
85
|
+
| `neonctl` | Neon database management, migrations | `npm install -g neonctl` |
|
|
86
|
+
| `psql` | Direct DB queries | Install PostgreSQL client |
|
|
87
87
|
| `az` | Azure resource management | `winget install Microsoft.AzureCLI` |
|
|
88
88
|
| `gh` | GitHub PRs, issues | `winget install GitHub.cli` |
|
|
89
89
|
|
|
@@ -103,7 +103,7 @@ For each MCP showing `✗ (recommended)`:
|
|
|
103
103
|
| **GitHub** | `gh` CLI |
|
|
104
104
|
| **Vercel** | `vercel` CLI |
|
|
105
105
|
|
|
106
|
-
> **Design:** This check is fail-open — consistent with morph-spec philosophy. Missing tools are warnings, not blockers (except `docker` for
|
|
106
|
+
> **Design:** This check is fail-open — consistent with morph-spec philosophy. Missing tools are warnings, not blockers (except `docker` for container-dependent projects).
|
|
107
107
|
|
|
108
108
|
---
|
|
109
109
|
|
|
@@ -160,7 +160,7 @@ See `.morph/framework/templates/` for the full template index (abstractions, ext
|
|
|
160
160
|
| Create new files | **Write** source files | — |
|
|
161
161
|
| Modify existing files | **Edit** source files | — |
|
|
162
162
|
| Look up library API | **Context7 MCP** `query_docs()` | **WebSearch** + **WebFetch** |
|
|
163
|
-
| Run migrations | **Bash** `
|
|
163
|
+
| Run migrations | **Bash** `dotnet ef database update` | `psql <DB_URL>` for verification |
|
|
164
164
|
| Build project | **Bash** `dotnet build` or `npm run build` | — |
|
|
165
165
|
| Run tests | **Bash** `dotnet test` or `npm test` | — |
|
|
166
166
|
| Checkpoint validation | **Bash** `morph-spec validate-feature ...` | — |
|
|
@@ -172,9 +172,9 @@ See `.morph/framework/templates/` for the full template index (abstractions, ext
|
|
|
172
172
|
| Create PR | **Bash** `gh pr create ...` | **GitHub MCP** `create_pull_request()` |
|
|
173
173
|
| Update state | **Bash** `morph-spec state set ...` | — |
|
|
174
174
|
|
|
175
|
-
**Phase tools:** Docker CLI (container health, logs),
|
|
175
|
+
**Phase tools:** Docker CLI (container health, logs), Neon CLI (`neonctl`) (database management), EF Core CLI (migrations), Context7 (API lookup), Playwright (smoke test), GitHub (PRs), Vercel (deploy, logs, env vars).
|
|
176
176
|
|
|
177
|
-
> **
|
|
177
|
+
> **Database Migrations:** When creating or running database migrations, use `dotnet ef migrations add <name>` to create, then `dotnet ef database update` to apply. Verify with `pg_dump $(neonctl connection-string) --schema public` or `psql` against the Neon database (get DB URL from `neonctl connection-string`).
|
|
178
178
|
|
|
179
179
|
**Anti-patterns:**
|
|
180
180
|
- Task agent for editing a single file (use Edit directly)
|
|
@@ -189,7 +189,7 @@ See `.morph/framework/templates/` for the full template index (abstractions, ext
|
|
|
189
189
|
- **(VSA)** Using `Guid.NewGuid()` — use `Guid.CreateVersion7()`
|
|
190
190
|
- Trying to fix a bug without invoking `systematic-debugging` first
|
|
191
191
|
|
|
192
|
-
> **Docker CLI:** If a build or test fails with connection errors to local services (
|
|
192
|
+
> **Docker CLI:** If a build or test fails with connection errors to local services (Redis, etc.), check container health first: `docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"`. For debugging: `docker logs <container> --tail 50` to see recent logs. To restart a stuck container: `docker restart <container>`.
|
|
193
193
|
|
|
194
194
|
---
|
|
195
195
|
|
|
@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 3 (Plan). Generates a detailed implementation plan
|
|
|
4
4
|
argument-hint: "[feature-name]"
|
|
5
5
|
user-invocable: false
|
|
6
6
|
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
|
|
7
|
-
cliVersion: "4.
|
|
7
|
+
cliVersion: "4.18.0"
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
# MORPH Plan — Phase 3
|
|
@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 4 (Tasks). Breaks approved spec into bottom-up ord
|
|
|
4
4
|
argument-hint: "[feature-name]"
|
|
5
5
|
user-invocable: false
|
|
6
6
|
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
|
|
7
|
-
cliVersion: "4.
|
|
7
|
+
cliVersion: "4.18.0"
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
# MORPH Tasks — Phase 4
|