mycontext-cli 4.2.12 → 4.2.13

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 (42) hide show
  1. package/README.md +46 -605
  2. package/dist/README.md +46 -605
  3. package/dist/cli.js +8 -0
  4. package/dist/cli.js.map +1 -1
  5. package/dist/commands/build-app.d.ts +1 -0
  6. package/dist/commands/build-app.d.ts.map +1 -1
  7. package/dist/commands/build-app.js +2 -1
  8. package/dist/commands/build-app.js.map +1 -1
  9. package/dist/commands/build-feature.d.ts +5 -0
  10. package/dist/commands/build-feature.d.ts.map +1 -0
  11. package/dist/commands/build-feature.js +39 -0
  12. package/dist/commands/build-feature.js.map +1 -0
  13. package/dist/commands/init.d.ts +0 -3
  14. package/dist/commands/init.d.ts.map +1 -1
  15. package/dist/commands/init.js +24 -7
  16. package/dist/commands/init.js.map +1 -1
  17. package/dist/commands/plan.d.ts +5 -0
  18. package/dist/commands/plan.d.ts.map +1 -0
  19. package/dist/commands/plan.js +32 -0
  20. package/dist/commands/plan.js.map +1 -0
  21. package/dist/commands/test.d.ts +4 -0
  22. package/dist/commands/test.d.ts.map +1 -1
  23. package/dist/commands/test.js +90 -0
  24. package/dist/commands/test.js.map +1 -1
  25. package/dist/commands/vision-test.d.ts +6 -4
  26. package/dist/commands/vision-test.d.ts.map +1 -1
  27. package/dist/commands/vision-test.js +81 -22
  28. package/dist/commands/vision-test.js.map +1 -1
  29. package/dist/generator/scaffold.d.ts +11 -0
  30. package/dist/generator/scaffold.d.ts.map +1 -0
  31. package/dist/generator/scaffold.js +107 -0
  32. package/dist/generator/scaffold.js.map +1 -0
  33. package/dist/generator/templates/nextjs.d.ts +11 -0
  34. package/dist/generator/templates/nextjs.d.ts.map +1 -0
  35. package/dist/generator/templates/nextjs.js +499 -0
  36. package/dist/generator/templates/nextjs.js.map +1 -0
  37. package/dist/package.json +1 -1
  38. package/dist/planner/index.d.ts +11 -0
  39. package/dist/planner/index.d.ts.map +1 -0
  40. package/dist/planner/index.js +142 -0
  41. package/dist/planner/index.js.map +1 -0
  42. package/package.json +1 -1
package/README.md CHANGED
@@ -1,645 +1,86 @@
1
1
  # MyContext CLI — Deterministic Full-Stack App Compiler
2
2
 
3
- **Transform natural language into production-ready Next.js applications through deterministic compilation.**
3
+ Transform natural language into production-ready Next.js applications through deterministic compilation.
4
4
 
5
- MyContext is not an AI code generator—it's a **natural-language-to-project compiler** that uses LLMs only for intent parsing while all code generation is performed by deterministic script templates. No hallucinations. No guessing. Just facts → manifest → complete application.
5
+ MyContext is not an AI code generator—it's a natural-language-to-project compiler that uses LLMs only for intent parsing, while all code generation is performed by deterministic script templates. No hallucinations. No guessing. Just facts → manifest → complete application.
6
6
 
7
7
  [![npm version](https://img.shields.io/npm/v/mycontext-cli.svg)](https://www.npmjs.com/package/mycontext-cli)
8
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9
- [![Inference Verified](https://img.shields.io/badge/Inference-Verified%20✓-green)](../../docs/TEST_RESULTS.md)
10
- [![Prompt Reduction](https://img.shields.io/badge/Prompt%20Reduction-90%25-blue)](../../docs/INFERENCE_ENGINE.md)
11
- [![Confidence](https://img.shields.io/badge/Confidence-92%25-brightgreen)](../../docs/TEST_RESULTS.md)
12
9
 
13
10
  ---
14
11
 
15
- ## 🎯 NEW: Self-Organizing Planner (VERIFIED ✓)
12
+ ## 🚀 NEW: Phase 0.7 — Premium Product Engineering (VERIFIED ✓)
16
13
 
17
- **90% Prompt Reduction Achieved!**
14
+ MyContext has evolved from a basic scaffolder into a high-fidelity **Product Engineering Partner**.
18
15
 
19
- MyContext now features an intelligent **Self-Organizing Planner** that auto-infers 67-90% of your specification, reducing setup time from 10-15 minutes to 2-3 minutes!
16
+ ### 1. Smart Layout Engine (8/12 Grid)
17
+ MyContext now intelligently places components based on their functional `weight`.
18
+ - **Primary Components**: Automatically assigned to the 8-column main content area.
19
+ - **Secondary Components**: Placed in a 4-column side-rail for tools, status, or navigation.
20
+ - **Result**: Perfectly balanced, premium-grade layouts without manual CSS tweaking.
20
21
 
21
- ### Before vs After
22
+ ### 2. Test-Mode Fast-Forward
23
+ Generated stateful components are now "test-aware."
24
+ - When `window.__MYCONTEXT_TEST_MODE__` is detected, 3-second "AI thinking" simulations fast-forward to **100ms**.
25
+ - **Result**: Blazing fast automated test suites (60x speed improvement).
22
26
 
23
- **Traditional Approach** (20+ questions):
24
- ```
25
- ❓ What entities do you need?
26
- ❓ What fields should User have?
27
- ❓ What fields should Post have?
28
- ❓ What fields should Comment have?
29
- ❓ How are entities related?
30
- ❓ What auth provider?
31
- ❓ What roles do you need?
32
- ❓ What permissions for admin?
33
- ❓ What permissions for author?
34
- ❓ What permissions for reader?
35
- ❓ What pages do you need?
36
- ❓ What's in the navigation?
37
- ... 15+ more questions
38
- ```
39
-
40
- **Inference Approach** (1 description + 2-4 confirmations):
27
+ ### 3. FSR-Driven Test Generation (`mycontext test:generate`)
28
+ Stop writing boilerplate tests. MyContext now generates Playwright specs directly from your FSR (Feature Structured Representation).
41
29
  ```bash
42
- npx mycontext-cli init --interactive
43
-
44
- ❓ What are you building?
45
- → "A blog with user authentication"
46
-
47
- 🤖 AI auto-infers (67-90% of specification):
48
- ✓ User, Post, Comment entities (95% confidence)
49
- ✓ Entity fields and relationships (90-95% confidence)
50
- ✓ RBAC roles and permissions (92% confidence)
51
- ✓ Pages and navigation (90% confidence)
52
-
53
- Only asks about ambiguous items:
54
- ? Auth provider? [Email] [OAuth GitHub] [OAuth Google]
55
- ? Design theme? [Light] [Dark] [System]
56
-
57
- ✅ Complete specification in 2-3 minutes!
58
- ```
59
-
60
- ### Verified Performance
61
-
62
- | Metric | Result |
63
- |--------|--------|
64
- | **Prompt Reduction** | 67-90% fewer questions |
65
- | **Time Savings** | 67% faster setup |
66
- | **Overall Confidence** | 92% accuracy |
67
- | **Auto-Inference Rate** | 8 out of 12 tasks |
68
- | **Status** | Production-ready ✅ |
69
-
70
- **Real Example** (Blog with Authentication):
71
- - **Input**: "A blog with user authentication"
72
- - **Tasks Generated**: 12 total
73
- - **Auto-Inferred**: 8 tasks (67%)
74
- - **User Prompts**: 4 questions
75
- - **Time**: 2-3 minutes vs 10-15 minutes
76
-
77
- 📚 **Learn More**:
78
- - [Inference Engine Architecture](../../docs/INFERENCE_ENGINE.md)
79
- - [Test Results & Verification](../../docs/TEST_RESULTS.md)
80
- - [Quick Start Guide](../../docs/QUICK_START_INFERENCE.md)
81
-
82
- ---
83
-
84
- ## 🎯 Ultimate Goal
85
-
86
- Run **ONE "mega script"** after the agent validates your specification, and get a complete Next.js application with all pages, features, roles, components, auth, and actions already wired—with minimal manual intervention.
87
-
88
- ---
89
-
90
- ## 🧠 Core Philosophy
91
-
92
- ### What MyContext Is
93
-
94
- - ✅ A **deterministic compiler** (natural language → manifest → scripted generation)
95
- - ✅ A **recursive clarification agent** (100% specification before code)
96
- - ✅ A **canonical project brain** (context.json as single source of truth)
97
-
98
- ### What MyContext Is NOT
99
-
100
- - ❌ An autonomous coder (AI does not guess or hallucinate)
101
- - ❌ A trial-and-error generator (no brute-force LLM coding)
102
- - ❌ A chat-based assistant (it's a compiler with a conversational interface)
103
-
104
- ---
105
-
106
- ## 🏗️ How It Works
107
-
108
- **Traditional Flow:**
109
- ```
110
- [User Input (Natural Language)]
111
-
112
- [Agent: Parse Intent → ASL]
113
-
114
- [Planner: Validate → Ask Questions → Ensure 100% Complete]
115
-
116
- [User: Approve Diff]
117
-
118
- [Script Engine: Deterministic Generation]
119
-
120
- [Verifier: TypeScript, Build, Schema Drift]
121
-
122
- [Brain: Update context.json + Registries]
30
+ mycontext test:generate --feature <feature-name>
123
31
  ```
32
+ - **Result**: Functional test coverage for your entire feature flow in seconds.
124
33
 
125
- **NEW: Inference-Enhanced Flow (90% Faster):**
126
- ```
127
- [User Input (Natural Language)]
128
-
129
- [Planner: Decompose into 12-15 Tasks]
130
-
131
- [InferenceEngine: Auto-Infer High-Confidence Tasks (≥90%)]
132
-
133
- [Self-Critique: Validate Inferences]
134
-
135
- [Reveal Context Progressively]
136
-
137
- [User: Confirm Only Ambiguous Items (70-89%)]
138
-
139
- [Checkpoint: Review Auto-Inferred Summary]
140
-
141
- [User: Approve Final Diff]
142
-
143
- [Script Engine: Deterministic Generation]
144
-
145
- [Verifier: TypeScript, Build, Schema Drift]
146
-
147
- [Brain: Update context.json + Registries]
34
+ ### 4. Visual Density Guardrails
35
+ Built-in vision-test detection for "Rammed UI" syndrome.
36
+ ```bash
37
+ mycontext test:vision --check-density
148
38
  ```
149
-
150
- **Key Advantages:**
151
- - ✅ **67-90% fewer questions** (only ask about truly ambiguous items)
152
- - ✅ **Self-critique loops** prevent hallucinations
153
- - ✅ **Session learning** from user corrections
154
- - ✅ **Confidence scoring** ensures accuracy
155
-
156
- ### The 6 Core Principles
157
-
158
- 1. **Deterministic Compilation**
159
- - LLM interprets intent into ASL (Abstract Specification Language)
160
- - Scripts generate code (no LLM involved in generation)
161
- - Same manifest always produces same output
162
-
163
- 2. **Canonical Project State**
164
- ```
165
- .mycontext/
166
- ├── context.json # Master brain
167
- ├── components_registry.json # Component catalog
168
- ├── types_registry.json # Type definitions
169
- ├── design_manifest.json # Design tokens
170
- └── permissions_manifest.json # RBAC rules
171
- ```
172
-
173
- 3. **Self-Organizing Planner with Confidence-Based Inference (NEW ✓)**
174
- - **90% Prompt Reduction**: AI auto-infers 67-90% of specification
175
- - **Smart Decomposition**: Breaks project into 12-15 inference tasks
176
- - **Confidence Scoring**: Each task scored 0-100% based on certainty
177
- - **Auto-Inference**: Tasks ≥90% confidence inferred automatically
178
- - **Self-Critique**: AI validates its own work, drops confidence if issues found
179
- - **Session Learning**: Adapts to user's terminology and preferences
180
- - **Minimal Prompts**: Only asks about truly ambiguous items (70-89% confidence)
181
-
182
- **Verified Results**: 67% prompt reduction, 92% confidence, 67% faster setup
183
-
184
- 4. **Recursive Clarification Loop**
185
- - Agent asks questions until manifest is 100% complete
186
- - Certainty > speed (but now with 90% fewer questions!)
187
- - No code generation until specification is perfect
188
-
189
- 5. **Separation of Concerns**
190
- - LLM: Natural language → ASL
191
- - InferenceEngine: Auto-complete high-confidence tasks
192
- - Planner: Validate, detect gaps, query user
193
- - Scripts: Generate files deterministically
194
- - Verifier: TypeScript, build, lint, schema drift
195
-
196
- 6. **Iterative Refinement**
197
- - Templates improve with each project
198
- - Inference engine learns from patterns
199
- - Future projects benefit automatically
200
- - Goal: 99% correct by Project 20
39
+ - Automatically flags nested card patterns and visual clutter to maintain a premium aesthetic score.
201
40
 
202
41
  ---
203
42
 
204
- ## 📦 What Gets Generated
205
-
206
- The "mega script" scaffolds a **COMPLETE Next.js application** including:
207
-
208
- - ✅ Full project scaffold (Next.js 15+ App Router)
209
- - ✅ Pages, layouts, nested routes
210
- - ✅ Client and server components
211
- - ✅ Server actions and data manipulation
212
- - ✅ Authentication flows (login, register, logout)
213
- - ✅ Role-based access control (guards, middleware)
214
- - ✅ Permission checks (RBAC)
215
- - ✅ User profile pages
216
- - ✅ shadCN UI components (fully typed props, animations)
217
- - ✅ InstantDB schema (instant.schema.ts)
218
- - ✅ TypeScript types (Insert, WithRelations, entity types)
219
- - ✅ **Everything defined in the manifest**
220
-
221
-
222
- ## 🛠️ Post-Scaffold LLM Enhancement (NEW)
223
-
224
- After the deterministic mega script scaffolds the full application, MyContext supports **LLM-driven enhancement and refactoring** of existing components. The LLM is never used to generate code from scratch. Instead, the workflow is:
43
+ ## 🏗️ How it Works
225
44
 
226
- 1. **Mega script completes deterministic scaffold** (all code matches manifest/context).
227
- 2. **Planner agent** identifies opportunities for enhancement or refactor (e.g., improve a component, add animation, refactor logic).
228
- 3. **LLM receives a single component or group of components** (never the whole app) and a specific enhancement/refactor query.
229
- 4. **LLM output is reviewed and integrated**—all changes update the component registry and context.json.
45
+ ### 1. The Planner (`mycontext plan`)
46
+ Listens to your natural language intent and auto-infers up to **90% of your specification**.
47
+ - It decomposes your project into a strict, validated JSON AST called the **Feature Structured Representation (FSR)**.
48
+ - Reduces setup time from 15 minutes to **2 minutes**.
230
49
 
231
- This ensures all LLM-driven code is traceable, reviewable, and always based on existing, deterministic code. No hallucination, no guessing.
232
-
233
- > **Note:** As the CLI and planner enforce alignment and deterministic scaffolding, the ALIGN file's role becomes advisory/redundant and may be deprecated in the future.
50
+ ### 2. The Generator (`mycontext build`)
51
+ Deterministically renders the FSR AST into high-fidelity Next.js output files.
52
+ - **Pages & Layouts**: Next.js 15+ App Router patterns.
53
+ - **Components**: shadcn/ui integration with premium design tokens.
54
+ - **Logic**: Decoupled event-driven architecture using DOM events.
234
55
 
235
56
  ---
236
57
 
237
- ## 🚀 Quick Start
58
+ ## 📦 Quick Start
238
59
 
239
60
  ### Installation
240
-
241
61
  ```bash
242
62
  # Install globally
243
63
  npm install -g mycontext-cli
244
-
245
- # Or use with npx
246
- npx mycontext-cli init
247
- ```
248
-
249
- ### Usage (New Workflow with Inference)
250
-
251
- ```bash
252
- # Step 1: Initialize with self-organizing planner (NEW!)
253
- mycontext init --interactive
254
-
255
- # 🤖 Smart inference happens automatically:
256
- # ✓ AI auto-infers 67-90% of your specification
257
- # ✓ Only asks about truly ambiguous items (2-4 questions instead of 20+)
258
- # ✓ Self-critique validates all inferences
259
- # ✓ Shows confidence scores transparently
260
-
261
- # Example conversation:
262
- # Agent: "What are you building?"
263
- # You: "A blog with user authentication"
264
- #
265
- # Agent: "🤖 Auto-inferring specification..."
266
- # ✓ [95%] User, Post, Comment entities
267
- # ✓ [90%] Entity fields and relationships
268
- # ✓ [92%] RBAC roles (admin, author, reader)
269
- # ⚠ [85%] Auth provider → needs confirmation
270
- #
271
- # Agent: "Which auth provider?"
272
- # [ ] Email/password
273
- # [ ] OAuth GitHub
274
- # [ ] OAuth Google
275
- # You: "Email/password"
276
- #
277
- # Agent: "✅ Specification complete! (92% confidence)"
278
-
279
- # Step 2: Review checkpoint summary
280
- # The planner shows all auto-inferred items for final review
281
- # [Approve / Modify / Cancel]
282
-
283
- # Step 3: Approve final diff
284
- # See exactly what will be generated
285
- # [Approve / Edit / Cancel]
286
-
287
- # Step 4: Run the mega-script to scaffold entire project
288
- mycontext scaffold --from-manifest
289
-
290
- # Step 5: Verify build
291
- mycontext doctor
292
-
293
- # Done! Your complete app is ready in 2-3 minutes (vs 10-15 minutes).
294
- ```
295
-
296
- ---
297
-
298
- ## 📖 Commands Reference
299
-
300
- ### `mycontext init --interactive`
301
-
302
- **Start the self-organizing planner with confidence-based inference. (NEW!)**
303
-
304
- The agent auto-infers 67-90% of your specification and only asks about ambiguous items. No guessing—everything is validated with self-critique loops.
305
-
306
- ```bash
307
- mycontext init --interactive
308
- ```
309
-
310
- **Example Session (Blog with Auth):**
311
- ```
312
- Agent: "What are you building?"
313
- User: "A blog with authentication"
314
-
315
- Agent: "🤖 Decomposing into tasks..."
316
- 📋 Generated 12 tasks:
317
- 1. ✓ [95%] Infer core entities from 'blog' context
318
- 2. ✓ [90%] Infer User entity fields
319
- 3. ✓ [95%] Infer Post entity fields
320
- 4. ✓ [90%] Infer Comment entity fields
321
- 5. ✓ [95%] Infer relationships between entities
322
- 6. ⚠ [85%] Infer authentication requirements
323
- 7. ⚠ [80%] Infer authorization requirements
324
- 8. ✓ [90%] Define pages for blog
325
-
326
- 📊 Summary: 8 auto-inferred, 4 need confirmation
327
-
328
- Agent: "🤖 Auto-inferring high-confidence tasks..."
329
- ✓ Inferred: User, Post, Comment entities
330
- ✓ Inferred: Entity fields and relationships
331
- ✓ Inferred: Pages (/posts, /posts/[id], /profile)
332
- ✓ Self-critique passed (92% confidence)
333
-
334
- Agent: "⚠ Need confirmation for auth provider (85% confidence)"
335
- Suggested: Email/password
336
- Reasoning: "Most blogs use simple email/password auth"
337
- [✓ Accept] [✗ Reject] [? Custom Answer]
338
- User: [Accept]
339
-
340
- Agent: "⚠ Need confirmation for roles (80% confidence)"
341
- Suggested: admin, author, reader
342
- [✓ Accept] [✗ Reject] [? Custom Answer]
343
- User: [Accept]
344
-
345
- Agent: "📸 Checkpoint: Review auto-inferred items"
346
- Entities: User, Post, Comment
347
- Auth: Email/password
348
- Roles: admin, author, reader
349
- Pages: 7 pages generated
350
- [✓ Approve] [✎ Edit] [✗ Cancel]
351
- User: [Approve]
352
-
353
- Agent: "✅ Specification complete! (92% overall confidence)"
354
- Agent: "📄 Showing final diff..."
355
- Agent: "Ready to generate. Proceed?"
356
- [✓ Yes] [✗ No]
357
- ```
358
-
359
- **Time Savings:**
360
- - Traditional: 10-15 minutes (20+ questions)
361
- - Inference: 2-3 minutes (4 confirmations)
362
- - **67% faster!**
363
-
364
- ---
365
-
366
- ### `mycontext scaffold --from-manifest`
367
-
368
- **Generate the entire project from the validated manifest.**
369
-
370
- This is the "mega script" that deterministically creates all files.
371
-
372
- ```bash
373
- mycontext scaffold --from-manifest
374
- ```
375
-
376
- **Output:**
377
64
  ```
378
- ✓ Generated instant.schema.ts (3 entities, 2 links)
379
- ✓ Generated types/schema.ts (Insert, WithRelations types)
380
- ✓ Generated 7 pages
381
- ✓ Generated 12 components
382
- ✓ Generated 3 action files
383
- ✓ Generated auth guards and middleware
384
- ✓ Updated registries
385
65
 
386
- Total: 35 files created
387
- Build: Passed
388
- Doctor: All checks passed
389
- ```
390
-
391
- ---
392
-
393
- ### `mycontext doctor`
394
-
395
- **Verify your project for type safety, schema drift, and best practices.**
396
-
397
- ```bash
398
- mycontext doctor
399
-
400
- # Auto-fix issues
401
- mycontext doctor --fix
402
-
403
- # Show detailed diagnostics
404
- mycontext doctor --verbose
405
-
406
- # Run only specific checks
407
- mycontext doctor --category typescript
408
- ```
409
-
410
- **Checks:**
411
- - ✅ TypeScript compilation
412
- - ✅ Schema field drift detection (NEW!)
413
- - Catches: `payment.payment_method` when schema has `payment.method`
414
- - ✅ `as any` cast detection (NEW!)
415
- - ✅ Unknown[] transaction array typing (NEW!)
416
- - ✅ Duplicate type declarations (NEW!)
417
- - ✅ Next.js best practices
418
- - ✅ Dead code detection
419
-
420
- ---
421
-
422
- ### `mycontext sync`
423
-
424
- **Update the canonical brain after manual code changes.**
425
-
426
- ```bash
427
- # Full sync (context.json + README)
428
- mycontext sync
429
-
430
- # Preview changes
431
- mycontext sync --dry-run
432
-
433
- # Sync only context or README
434
- mycontext sync --context
435
- mycontext sync --readme
436
- ```
437
-
438
- **How it works:**
439
- 1. Scans project files
440
- 2. Compares against context.json
441
- 3. Detects drift (code changed but brain didn't)
442
- 4. Updates brain with AI-generated diff
443
- 5. Regenerates README
444
-
445
- ---
446
-
447
- ### `mycontext generate types --from-schema`
448
-
449
- **Generate TypeScript types from InstantDB schema.**
450
-
451
- ```bash
452
- mycontext generate types --from-schema
453
- ```
454
-
455
- **Output:** `.mycontext/types.ts` with:
456
- - Entity types (`User`, `Post`, `Comment`)
457
- - Insert types (`PostInsert` = `Omit<Post, "id" | "created_at">`)
458
- - WithRelations types (`PostWithRelations` = `Post & { author?: User; comments?: Comment[] }`)
459
- - Component prop types
460
- - Dummy data generators
461
-
462
- ---
463
-
464
- ## 🧪 Progressive Testing Roadmap
465
-
466
- We build MyContext iteratively through progressive complexity:
467
-
468
- | Phase | Complexity | Example | Goal |
469
- |-------|------------|---------|------|
470
- | **Phase 1** | ★☆☆☆☆ | Todo App | Prove deterministic scaffolding works |
471
- | **Phase 2** | ★★★☆☆ | Blog (Auth) | Prove auth guards and RBAC work |
472
- | **Phase 3** | ★★★★☆ | E-commerce | Prove complex state management works |
473
- | **Phase 4** | ★★★★★ | SaaS Dashboard | Prove enterprise-grade scaffolding |
474
-
475
- See [docs/TESTING_ROADMAP.md](./docs/TESTING_ROADMAP.md) for full details.
476
-
477
- ---
478
-
479
- ## 📚 Documentation
480
-
481
- ### Core Architecture
482
- - [**ARCHITECTURE.md**](./docs/ARCHITECTURE.md) — System layers, data flow, registries
483
- - [**COMPILER_SPEC.md**](./docs/COMPILER_SPEC.md) — Input/output contracts, script templates
484
- - [**ALIGN**](../../.mycontext/ALIGN) — Philosophical foundation
485
-
486
- ### Inference Engine (NEW!)
487
- - [**INFERENCE_ENGINE.md**](../../docs/INFERENCE_ENGINE.md) — Self-organizing planner architecture
488
- - [**TEST_RESULTS.md**](../../docs/TEST_RESULTS.md) — Verified performance metrics
489
- - [**QUICK_START_INFERENCE.md**](../../docs/QUICK_START_INFERENCE.md) — How to use inference mode
490
-
491
- ### Testing & Development
492
- - [**TESTING_ROADMAP.md**](./docs/TESTING_ROADMAP.md) — Progressive complexity plan
493
- - [**IMPLEMENTATION_COMPLETE.md**](../../docs/IMPLEMENTATION_COMPLETE.md) — Full implementation summary
494
-
495
- ---
496
-
497
- ## 🔧 Technology Stack
498
-
499
- - **TypeScript** — Type-safe script templates
500
- - **Next.js 15+** — App Router, Server Components
501
- - **InstantDB** — Realtime database with schema
502
- - **shadCN** — UI component library
503
- - **Commander.js** — CLI framework
504
-
505
- ---
506
-
507
- ## 🎨 Example: Blog Generation
508
-
509
- ### Input (Natural Language)
510
- ```
511
- "Build a blog with user authentication.
512
- Authors can create and edit posts.
513
- Readers can view and comment."
514
- ```
515
-
516
- ### Agent Questions
517
- ```
518
- 1. Auth provider? → Email/password
519
- 2. Post fields? → title, content, published, author_id
520
- 3. Comment nesting? → Flat
521
- 4. Markdown support? → Yes
522
- ```
523
-
524
- ### Generated Output (35 files)
525
- ```
526
- src/
527
- ├── app/
528
- │ ├── (auth)/
529
- │ │ ├── login/page.tsx
530
- │ │ └── register/page.tsx
531
- │ ├── (dashboard)/
532
- │ │ ├── posts/
533
- │ │ │ ├── page.tsx
534
- │ │ │ ├── [id]/page.tsx
535
- │ │ │ ├── [id]/edit/page.tsx
536
- │ │ │ └── new/page.tsx
537
- │ │ └── layout.tsx (with auth guard)
538
- │ └── page.tsx
539
- ├── components/
540
- │ ├── auth/ (LoginForm, RegisterForm)
541
- │ ├── posts/ (PostCard, PostList, PostForm)
542
- │ └── comments/ (CommentList, CommentForm)
543
- ├── actions/
544
- │ ├── auth.ts (login, register, logout)
545
- │ ├── posts.ts (CRUD)
546
- │ └── comments.ts (CRUD)
547
- └── lib/
548
- ├── guards.ts (withAuthGuard, withRoleGuard)
549
- └── permissions.ts (hasPermission, canEdit)
550
-
551
- instant.schema.ts (User, Post, Comment entities)
552
- middleware.ts (route protection)
553
- ```
554
-
555
- ### Verification
556
- ```bash
557
- $ mycontext doctor
558
- ✓ TypeScript compilation passed
559
- ✓ Schema drift check passed
560
- ✓ Build successful
561
- ```
562
-
563
- ---
564
-
565
- ## 🚢 Differentiators
566
-
567
- | Traditional AI Generators | MyContext Compiler |
568
- |---------------------------|-------------------|
569
- | LLM writes code directly | LLM only parses intent |
570
- | Trial-and-error generation | Deterministic script execution |
571
- | Unpredictable output | Output matches manifest exactly |
572
- | No validation before generation | 100% spec validation required |
573
- | Hallucinations common | Zero hallucination (no LLM in generation) |
574
- | Hard to debug | Transparent script templates |
575
- | Doesn't improve over time | Templates refine with each project |
576
- | **Asks 20+ sequential questions** | **Auto-infers 67-90% (2-4 questions)** |
577
- | **No confidence scoring** | **Transparent confidence scores** |
578
- | **No self-validation** | **Self-critique loops prevent errors** |
579
- | **No learning from corrections** | **Session-based learning and patterns** |
66
+ ### Usage Workflow
67
+ 1. **Plan**: `mycontext plan "build a background removal tool with token tracking"`
68
+ 2. **Review**: Adjust the generated `.fsr.json` blueprint.
69
+ 3. **Build**: `mycontext build --feature removebg`
70
+ 4. **Test**: `mycontext test:generate --feature removebg`
71
+ 5. **Score**: `mycontext build --score` (Verify premium design tokens)
580
72
 
581
73
  ---
582
74
 
583
75
  ## 🛣️ Roadmap
584
-
585
- - [x] Phase 1: Doctor command with type safety checks
586
- - [x] Phase 1: Type generation from InstantDB schema
587
- - [x] **Phase 2: Self-organizing planner with inference (VERIFIED ✓)**
588
- - [x] Confidence-based task decomposition
589
- - [x] Auto-inference for high-confidence tasks (≥90%)
590
- - [x] Self-critique validation loops
591
- - [x] Session-based learning
592
- - [x] 67-90% prompt reduction achieved
593
- - [ ] Phase 2: `init --interactive` full UX implementation
594
- - [ ] Phase 2: `scaffold --from-manifest` deterministic generation
595
- - [ ] Phase 3: Component registry implementation
596
- - [ ] Phase 3: Permissions manifest validation
597
- - [ ] Phase 4: Progressive testing (Todo → Blog → E-commerce → SaaS)
598
- - [ ] Phase 5: Visual schema builder
599
- - [ ] Phase 6: Template marketplace
600
- - [ ] Phase 7: Pattern persistence across sessions
601
-
602
- ---
603
-
604
- ## 🤝 Contributing
605
-
606
- We welcome contributions! Areas of focus:
607
-
608
- 1. **Script templates** — Improve deterministic generators
609
- 2. **Validation rules** — Add planner checks
610
- 3. **Doctor diagnostics** — New type safety rules
611
- 4. **Testing** — Help test progressive complexity phases
76
+ - [x] **Phase 0.6**: Deterministic Scaffolding & Token Tracking
77
+ - [x] **Phase 0.7**: Premium Layout Engine & Test-Mode
78
+ - [ ] **Phase 1**: Global Registry & Multi-Agent Orchestration
79
+ - [ ] **Phase 2**: Granular component-level targeted LLM refactors
612
80
 
613
81
  ---
614
82
 
615
- ## 📄 License
616
-
83
+ ## 📄 License & Links
617
84
  MIT © [MyContext Team](https://github.com/farajabien/mycontext-cli)
618
-
619
- ---
620
-
621
- ## 🙏 Acknowledgments
622
-
623
- Built with:
624
- - [InstantDB](https://instantdb.com) — Realtime database
625
- - [shadCN](https://ui.shadcn.com) — UI components
626
- - [Next.js](https://nextjs.org) — React framework
627
- - [Commander.js](https://github.com/tj/commander.js) — CLI framework
628
-
629
- ---
630
-
631
- ## 📧 Contact & Support
632
-
633
- - **Issues:** [GitHub Issues](https://github.com/farajabien/mycontext-cli/issues)
634
- - **Discussions:** [GitHub Discussions](https://github.com/farajabien/mycontext-cli/discussions)
635
- - **Twitter:** [@mycontextcli](https://twitter.com/mycontextcli)
636
-
637
- ---
638
-
639
- **This is not just a tool—it's a paradigm shift in full-stack development.**
640
-
641
- ```bash
642
- npx mycontext-cli init --interactive
643
- ```
644
-
645
- Let's build the future, deterministically.
85
+ - [Documentation](https://mycontext.framer.website)
86
+ - [NPM: mycontext-cli](https://www.npmjs.com/package/mycontext-cli)