popeye-cli 1.2.1 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. package/.env.example +4 -1
  2. package/CONTRIBUTING.md +10 -0
  3. package/README.md +224 -17
  4. package/dist/adapters/claude.d.ts +3 -2
  5. package/dist/adapters/claude.d.ts.map +1 -1
  6. package/dist/adapters/claude.js +214 -0
  7. package/dist/adapters/claude.js.map +1 -1
  8. package/dist/adapters/gemini.d.ts +2 -2
  9. package/dist/adapters/gemini.d.ts.map +1 -1
  10. package/dist/adapters/grok.d.ts +2 -1
  11. package/dist/adapters/grok.d.ts.map +1 -1
  12. package/dist/adapters/grok.js.map +1 -1
  13. package/dist/adapters/index.d.ts +8 -0
  14. package/dist/adapters/index.d.ts.map +1 -0
  15. package/dist/adapters/index.js +12 -0
  16. package/dist/adapters/index.js.map +1 -0
  17. package/dist/adapters/openai.d.ts +2 -2
  18. package/dist/adapters/openai.d.ts.map +1 -1
  19. package/dist/adapters/openai.js.map +1 -1
  20. package/dist/cli/commands/create.d.ts.map +1 -1
  21. package/dist/cli/commands/create.js +25 -5
  22. package/dist/cli/commands/create.js.map +1 -1
  23. package/dist/cli/index.d.ts +1 -0
  24. package/dist/cli/index.d.ts.map +1 -1
  25. package/dist/cli/index.js +5 -2
  26. package/dist/cli/index.js.map +1 -1
  27. package/dist/cli/interactive.d.ts.map +1 -1
  28. package/dist/cli/interactive.js +354 -28
  29. package/dist/cli/interactive.js.map +1 -1
  30. package/dist/config/index.d.ts +2 -0
  31. package/dist/config/index.d.ts.map +1 -1
  32. package/dist/config/schema.d.ts +4 -0
  33. package/dist/config/schema.d.ts.map +1 -1
  34. package/dist/config/schema.js +2 -1
  35. package/dist/config/schema.js.map +1 -1
  36. package/dist/generators/all.d.ts +70 -0
  37. package/dist/generators/all.d.ts.map +1 -0
  38. package/dist/generators/all.js +826 -0
  39. package/dist/generators/all.js.map +1 -0
  40. package/dist/generators/fullstack.d.ts +9 -0
  41. package/dist/generators/fullstack.d.ts.map +1 -1
  42. package/dist/generators/fullstack.js.map +1 -1
  43. package/dist/generators/index.d.ts +3 -1
  44. package/dist/generators/index.d.ts.map +1 -1
  45. package/dist/generators/index.js +33 -0
  46. package/dist/generators/index.js.map +1 -1
  47. package/dist/generators/templates/index.d.ts +2 -0
  48. package/dist/generators/templates/index.d.ts.map +1 -1
  49. package/dist/generators/templates/index.js +2 -0
  50. package/dist/generators/templates/index.js.map +1 -1
  51. package/dist/generators/templates/website.d.ts +85 -0
  52. package/dist/generators/templates/website.d.ts.map +1 -0
  53. package/dist/generators/templates/website.js +877 -0
  54. package/dist/generators/templates/website.js.map +1 -0
  55. package/dist/generators/website.d.ts +56 -0
  56. package/dist/generators/website.d.ts.map +1 -0
  57. package/dist/generators/website.js +269 -0
  58. package/dist/generators/website.js.map +1 -0
  59. package/dist/types/consensus.d.ts +18 -23
  60. package/dist/types/consensus.d.ts.map +1 -1
  61. package/dist/types/consensus.js +8 -3
  62. package/dist/types/consensus.js.map +1 -1
  63. package/dist/types/index.d.ts +2 -2
  64. package/dist/types/index.d.ts.map +1 -1
  65. package/dist/types/index.js +2 -2
  66. package/dist/types/index.js.map +1 -1
  67. package/dist/types/project.d.ts +130 -17
  68. package/dist/types/project.d.ts.map +1 -1
  69. package/dist/types/project.js +55 -8
  70. package/dist/types/project.js.map +1 -1
  71. package/dist/types/workflow.d.ts +2 -0
  72. package/dist/types/workflow.d.ts.map +1 -1
  73. package/dist/types/workflow.js +2 -1
  74. package/dist/types/workflow.js.map +1 -1
  75. package/dist/upgrade/context.d.ts +37 -0
  76. package/dist/upgrade/context.d.ts.map +1 -0
  77. package/dist/upgrade/context.js +284 -0
  78. package/dist/upgrade/context.js.map +1 -0
  79. package/dist/upgrade/handlers.d.ts +103 -0
  80. package/dist/upgrade/handlers.d.ts.map +1 -0
  81. package/dist/upgrade/handlers.js +384 -0
  82. package/dist/upgrade/handlers.js.map +1 -0
  83. package/dist/upgrade/index.d.ts +26 -0
  84. package/dist/upgrade/index.d.ts.map +1 -0
  85. package/dist/upgrade/index.js +194 -0
  86. package/dist/upgrade/index.js.map +1 -0
  87. package/dist/upgrade/transitions.d.ts +34 -0
  88. package/dist/upgrade/transitions.d.ts.map +1 -0
  89. package/dist/upgrade/transitions.js +56 -0
  90. package/dist/upgrade/transitions.js.map +1 -0
  91. package/dist/workflow/consensus.d.ts +2 -1
  92. package/dist/workflow/consensus.d.ts.map +1 -1
  93. package/dist/workflow/consensus.js.map +1 -1
  94. package/dist/workflow/index.d.ts +6 -0
  95. package/dist/workflow/index.d.ts.map +1 -1
  96. package/dist/workflow/index.js +8 -0
  97. package/dist/workflow/index.js.map +1 -1
  98. package/dist/workflow/plan-mode.d.ts +3 -3
  99. package/dist/workflow/plan-mode.d.ts.map +1 -1
  100. package/dist/workflow/plan-mode.js +41 -5
  101. package/dist/workflow/plan-mode.js.map +1 -1
  102. package/dist/workflow/plan-parser.d.ts +97 -0
  103. package/dist/workflow/plan-parser.d.ts.map +1 -0
  104. package/dist/workflow/plan-parser.js +235 -0
  105. package/dist/workflow/plan-parser.js.map +1 -0
  106. package/dist/workflow/plan-storage.d.ts +40 -12
  107. package/dist/workflow/plan-storage.d.ts.map +1 -1
  108. package/dist/workflow/plan-storage.js +47 -20
  109. package/dist/workflow/plan-storage.js.map +1 -1
  110. package/dist/workflow/seo-tests.d.ts +43 -0
  111. package/dist/workflow/seo-tests.d.ts.map +1 -0
  112. package/dist/workflow/seo-tests.js +192 -0
  113. package/dist/workflow/seo-tests.js.map +1 -0
  114. package/dist/workflow/separation-guard.d.ts +35 -0
  115. package/dist/workflow/separation-guard.d.ts.map +1 -0
  116. package/dist/workflow/separation-guard.js +154 -0
  117. package/dist/workflow/separation-guard.js.map +1 -0
  118. package/dist/workflow/task-workflow.d.ts.map +1 -1
  119. package/dist/workflow/task-workflow.js +3 -2
  120. package/dist/workflow/task-workflow.js.map +1 -1
  121. package/dist/workflow/test-runner.d.ts.map +1 -1
  122. package/dist/workflow/test-runner.js +128 -0
  123. package/dist/workflow/test-runner.js.map +1 -1
  124. package/dist/workflow/workspace-manager.d.ts +31 -20
  125. package/dist/workflow/workspace-manager.d.ts.map +1 -1
  126. package/dist/workflow/workspace-manager.js +38 -9
  127. package/dist/workflow/workspace-manager.js.map +1 -1
  128. package/package.json +1 -1
  129. package/src/adapters/claude.ts +221 -4
  130. package/src/adapters/gemini.ts +2 -2
  131. package/src/adapters/grok.ts +2 -1
  132. package/src/adapters/index.ts +15 -0
  133. package/src/adapters/openai.ts +2 -2
  134. package/src/cli/commands/create.ts +25 -5
  135. package/src/cli/index.ts +5 -2
  136. package/src/cli/interactive.ts +400 -29
  137. package/src/config/schema.ts +2 -1
  138. package/src/generators/all.ts +897 -0
  139. package/src/generators/fullstack.ts +10 -0
  140. package/src/generators/index.ts +54 -0
  141. package/src/generators/templates/index.ts +2 -0
  142. package/src/generators/templates/website.ts +906 -0
  143. package/src/generators/website.ts +350 -0
  144. package/src/types/consensus.ts +20 -8
  145. package/src/types/index.ts +35 -0
  146. package/src/types/project.ts +157 -11
  147. package/src/types/workflow.ts +2 -1
  148. package/src/upgrade/context.ts +332 -0
  149. package/src/upgrade/handlers.ts +477 -0
  150. package/src/upgrade/index.ts +244 -0
  151. package/src/upgrade/transitions.ts +80 -0
  152. package/src/workflow/consensus.ts +3 -2
  153. package/src/workflow/index.ts +8 -0
  154. package/src/workflow/plan-mode.ts +44 -10
  155. package/src/workflow/plan-parser.ts +317 -0
  156. package/src/workflow/plan-storage.ts +69 -30
  157. package/src/workflow/seo-tests.ts +246 -0
  158. package/src/workflow/separation-guard.ts +200 -0
  159. package/src/workflow/task-workflow.ts +3 -2
  160. package/src/workflow/test-runner.ts +149 -0
  161. package/src/workflow/workspace-manager.ts +68 -31
  162. package/tests/cli/model-command.test.ts +93 -0
  163. package/tests/types/project.test.ts +90 -15
  164. package/tests/types/workflow-schema.test.ts +59 -0
  165. package/tests/upgrade/context.test.ts +211 -0
  166. package/tests/upgrade/transitions.test.ts +85 -0
package/.env.example CHANGED
@@ -14,7 +14,7 @@ POPEYE_GEMINI_KEY=
14
14
  POPEYE_GROK_KEY=
15
15
 
16
16
  # Default output language for generated projects
17
- # Options: python, typescript, fullstack
17
+ # Options: python/be (backend), typescript/fe (frontend), fullstack/fs, website/web, all
18
18
  POPEYE_DEFAULT_LANGUAGE=python
19
19
 
20
20
  # Default OpenAI model for consensus reviews
@@ -28,6 +28,9 @@ POPEYE_GEMINI_MODEL=gemini-2.0-flash
28
28
  # Common models: grok-3, grok-2
29
29
  POPEYE_GROK_MODEL=grok-3
30
30
 
31
+ # Grok API URL (optional, defaults to https://api.x.ai/v1)
32
+ # POPEYE_GROK_API_URL=https://api.x.ai/v1
33
+
31
34
  # Consensus reviewer provider
32
35
  # Options: openai, gemini, grok
33
36
  POPEYE_CONSENSUS_REVIEWER=openai
package/CONTRIBUTING.md CHANGED
@@ -188,8 +188,18 @@ src/
188
188
  ├── state/ # State management
189
189
  ├── types/ # TypeScript type definitions
190
190
  └── workflow/ # Core workflow logic
191
+ ├── plan-storage.ts # Consensus docs per-app storage
192
+ └── workspace-manager.ts # Multi-app workspace management
191
193
  ```
192
194
 
195
+ ### App Target Types
196
+
197
+ For fullstack and ALL projects, feedback is tracked per app target:
198
+ - `frontend` - React/Vue application
199
+ - `backend` - FastAPI/Express API
200
+ - `website` - Marketing/landing pages (ALL projects)
201
+ - `unified` - Cross-app integration concerns
202
+
193
203
  ### Formatting
194
204
 
195
205
  We use Prettier for code formatting:
package/README.md CHANGED
@@ -312,6 +312,12 @@ popeye create "A React component library for data visualization" --language type
312
312
 
313
313
  # Create a Fullstack project (React frontend + FastAPI backend)
314
314
  popeye create "A task management app with user authentication" --language fullstack
315
+
316
+ # Create a Website project (Next.js marketing/landing site)
317
+ popeye create "A marketing website with blog and pricing page" --language website
318
+
319
+ # Create an ALL project (React app + FastAPI backend + Marketing website)
320
+ popeye create "A SaaS product with landing page and dashboard" --language all
315
321
  ```
316
322
 
317
323
  ### 3. Monitor Progress
@@ -346,7 +352,7 @@ Popeye provides real-time feedback:
346
352
 
347
353
  - **Fully Autonomous**: Runs from idea to complete project without manual intervention
348
354
  - **Dual-AI Consensus**: Plans validated by multiple AI systems before execution
349
- - **Multi-Language Support**: Generate projects in Python, TypeScript, or Fullstack (React + FastAPI)
355
+ - **Multi-Language Support**: Generate projects in Python, TypeScript, Fullstack (React + FastAPI), Website, or ALL (React + FastAPI + Website)
350
356
  - **Automatic Testing**: Tests are generated and run for each implementation
351
357
  - **Error Recovery**: Failed tests trigger automatic fix attempts (up to 3 retries)
352
358
  - **Auto-Generated README**: At project completion, generates a comprehensive README with:
@@ -355,6 +361,8 @@ Popeye provides real-time feedback:
355
361
  - Environment setup guide
356
362
  - How to run (development, tests, production)
357
363
  - Project structure overview
364
+ - **Project Type Upgrade**: Upgrade projects in-place (e.g., python to fullstack, fullstack to all) with automatic file restructuring, scaffolding, and planning integration
365
+ - **Flexible Model Switching**: Use any AI model name for OpenAI, Gemini, or Grok providers -- not limited to a predefined list
358
366
 
359
367
  ### Automatic UI/UX Design
360
368
 
@@ -408,6 +416,26 @@ Example fullstack task in a plan:
408
416
  **Dependencies**: Task 1.1, Task 1.2
409
417
  ```
410
418
 
419
+ ### ALL Project Support (Fullstack + Website)
420
+
421
+ For comprehensive projects that need both an application and a marketing/landing website, Popeye supports the `all` project type which includes:
422
+
423
+ - **Frontend App**: React application (same as fullstack)
424
+ - **Backend API**: FastAPI backend (same as fullstack)
425
+ - **Website**: Static marketing/landing site (Astro, Next.js static, or similar)
426
+
427
+ Tasks can be tagged with:
428
+ - `[FE]` - Frontend application work
429
+ - `[BE]` - Backend API work
430
+ - `[WEB]` - Website/marketing pages work
431
+ - `[INT]` - Integration work across multiple apps
432
+
433
+ The consensus system tracks approval separately for each app target:
434
+ - `frontend` - React/Vue application components
435
+ - `backend` - API endpoints and database logic
436
+ - `website` - Marketing pages, landing pages, SEO content
437
+ - `unified` - Cross-app integration and shared concerns
438
+
411
439
  ### Reliability Features
412
440
 
413
441
  - **Rate Limit Handling**: Automatically waits and retries when API rate limits are hit
@@ -460,6 +488,33 @@ Example fullstack task in a plan:
460
488
  - Checks component library setup
461
489
  - Validates theme configuration
462
490
 
491
+ ### Consensus Documentation Storage
492
+
493
+ For fullstack and ALL projects, Popeye maintains detailed consensus documentation with per-app feedback tracking:
494
+
495
+ - **Per-App Feedback**: Feedback is stored separately for each app target:
496
+ - `unified/` - Cross-app and integration concerns
497
+ - `frontend/` - React/Vue application feedback
498
+ - `backend/` - API and database feedback
499
+ - `website/` - Marketing/landing page feedback (ALL projects only)
500
+
501
+ - **Hierarchical Storage**: Feedback is organized by plan level:
502
+ - `docs/plans/master/` - Master plan feedback
503
+ - `docs/plans/milestone-N/` - Milestone-level feedback
504
+ - `docs/plans/milestone-N/tasks/task-N/` - Task-level feedback
505
+
506
+ - **Tracked Metadata**: Each plan level includes `metadata.json` with:
507
+ - Per-app scores (frontendScore, backendScore, websiteScore, unifiedScore)
508
+ - Per-app approval status
509
+ - Correction history and iteration counts
510
+ - Timestamps for auditing
511
+
512
+ - **Human-Readable Feedback**: Both JSON and Markdown formats:
513
+ - `feedback.json` - Structured data for programmatic access
514
+ - `feedback.md` - Human-readable reviewer feedback
515
+
516
+ This system ensures full traceability of all AI decisions and enables debugging of consensus failures.
517
+
463
518
  ## Commands
464
519
 
465
520
  ### `popeye create <idea>`
@@ -477,7 +532,7 @@ popeye create "A CLI tool for converting markdown to PDF" \
477
532
  | Option | Description | Default |
478
533
  |--------|-------------|---------|
479
534
  | `-n, --name <name>` | Project name | Derived from idea |
480
- | `-l, --language <lang>` | `python` or `typescript` | `python` |
535
+ | `-l, --language <lang>` | `python`, `typescript`, `fullstack`, `website`, or `all` | `python` |
481
536
  | `-d, --directory <dir>` | Output directory | Current directory |
482
537
  | `-m, --model <model>` | OpenAI model for consensus | `gpt-4o` |
483
538
 
@@ -557,7 +612,11 @@ popeye
557
612
  /config View/edit configuration
558
613
  /config reviewer <ai> Set reviewer (openai/gemini/grok)
559
614
  /config arbitrator <ai> Set arbitrator (openai/gemini/grok/off)
560
- /lang <lang> Set language (py/ts/fs or python/typescript/fullstack)
615
+ /config model Manage AI models via config subcommand
616
+ /lang <lang> Set language (py/ts/fs/web/all)
617
+ /model [provider] [model] Show/set AI model (openai/gemini/grok)
618
+ /model <provider> list Show known models for a provider
619
+ /upgrade [target] Upgrade project type (e.g., fullstack -> all)
561
620
  /info Show system info (Claude CLI status, API keys, etc.)
562
621
  /clear Clear screen
563
622
  /exit Exit interactive mode
@@ -567,14 +626,84 @@ popeye
567
626
  - `/lang py` or `/lang python` - Python projects
568
627
  - `/lang ts` or `/lang typescript` - TypeScript projects
569
628
  - `/lang fs` or `/lang fullstack` - Fullstack projects (React + FastAPI)
629
+ - `/lang web` or `/lang website` - Website projects (Next.js SSG/SSR)
630
+ - `/lang all` - ALL projects (React + FastAPI + Website)
570
631
 
571
632
  **Status Bar Indicators:**
572
633
  The input box shows current configuration:
573
- - Language: `py`, `ts`, or `fs`
634
+ - Language: `py`, `ts`, `fs`, `web`, or `all`
574
635
  - Reviewer: `O` (OpenAI), `G` (Gemini), or `X` (Grok)
575
636
  - Arbitrator: `O`, `G`, `X`, or `-` (disabled)
576
637
  - Auth status: Filled circle when all required APIs are authenticated
577
638
 
639
+ ### Model Switching (`/model`)
640
+
641
+ The `/model` command supports multi-provider model switching across OpenAI, Gemini, and Grok. Model names are flexible -- any valid model string is accepted, not just a predefined list. Unknown models are accepted with a warning note, allowing you to use newly released models immediately.
642
+
643
+ ```bash
644
+ # Show current models for all providers
645
+ /model
646
+
647
+ # Set model for a specific provider
648
+ /model openai gpt-5
649
+ /model gemini gemini-2.5-pro
650
+ /model grok grok-3
651
+
652
+ # List known models for a provider (suggestions only)
653
+ /model openai list
654
+ /model gemini list
655
+
656
+ # Backward compatible: set OpenAI model directly
657
+ /model gpt-4o-mini
658
+ ```
659
+
660
+ **Known Models (for reference):**
661
+
662
+ | Provider | Known Models |
663
+ |----------|-------------|
664
+ | OpenAI | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`, `o1-preview`, `o1-mini` |
665
+ | Gemini | `gemini-2.0-flash`, `gemini-1.5-pro`, `gemini-1.5-flash` |
666
+ | Grok | `grok-3` (flexible string, any model accepted) |
667
+
668
+ All three model values (openaiModel, geminiModel, grokModel) are:
669
+ - Persisted to `popeye.md` and loaded automatically on resume
670
+ - Passed through to the consensus workflow for the reviewer and arbitrator
671
+ - Displayed by `/config` and `/config model`
672
+
673
+ ### Project Type Upgrade (`/upgrade`)
674
+
675
+ The `/upgrade` command allows upgrading an existing project to a more comprehensive type without starting over. The upgrade is transactional: it creates backups before making changes and rolls back on failure.
676
+
677
+ ```bash
678
+ # Show valid upgrade targets for current project
679
+ /upgrade
680
+
681
+ # Upgrade to a specific target
682
+ /upgrade fullstack
683
+ /upgrade all
684
+ ```
685
+
686
+ **Valid Upgrade Paths:**
687
+
688
+ | From | Valid Targets | Description |
689
+ |------|-------------|-------------|
690
+ | `python` | `fullstack`, `all` | Add frontend (and website), move backend to `apps/backend/` |
691
+ | `typescript` | `fullstack`, `all` | Add backend (and website), move frontend to `apps/frontend/` |
692
+ | `fullstack` | `all` | Add website app to existing workspace |
693
+ | `website` | `all` | Add frontend + backend, move website to `apps/website/` |
694
+ | `all` | (none) | Already the most comprehensive type |
695
+
696
+ **What happens during an upgrade:**
697
+
698
+ 1. **Backup**: Critical files are backed up for rollback
699
+ 2. **Restructure**: For single-app projects (python, typescript, website), existing code is moved into the `apps/` monorepo structure
700
+ 3. **Scaffold**: New app directories are created with starter files
701
+ 4. **Update State**: Project state and workspace configuration are updated
702
+ 5. **Validate**: The upgrade result is verified (directories exist, state is correct)
703
+ 6. **Plan**: After a successful upgrade, Popeye automatically builds context about the existing project and triggers planning mode focused only on the new apps and integration tasks
704
+
705
+ The planner receives explicit instructions to focus only on new apps and not rebuild existing ones, along with integration guidance tailored to the specific upgrade path.
706
+
578
707
  ## Configuration
579
708
 
580
709
  ### Project Configuration File (`popeye.md`)
@@ -593,6 +722,9 @@ When you create a new project, Popeye automatically generates a `popeye.md` file
593
722
  language: fullstack
594
723
  reviewer: openai
595
724
  arbitrator: gemini
725
+ openaiModel: gpt-4o
726
+ geminiModel: gemini-2.0-flash
727
+ grokModel: grok-3
596
728
  created: 2024-01-15T10:30:00.000Z
597
729
  lastRun: 2024-01-15T14:45:00.000Z
598
730
  projectName: task-manager
@@ -613,13 +745,16 @@ Add any guidance or notes for Claude here...
613
745
  - **Language**: fullstack
614
746
  - **Reviewer**: openai
615
747
  - **Arbitrator**: gemini
748
+ - **OpenAI Model**: gpt-4o
749
+ - **Gemini Model**: gemini-2.0-flash
750
+ - **Grok Model**: grok-3
616
751
 
617
752
  ## Session History
618
753
  - 2024-01-15: Project created
619
754
  - 2024-01-15: Last session
620
755
  ```
621
756
 
622
- This means you no longer need to run `/lang fullstack` every time you resume a project - the configuration is automatically restored.
757
+ This means you no longer need to run `/lang fullstack` or `/model` every time you resume a project - the configuration (including all three model selections) is automatically restored.
623
758
 
624
759
  ### Global Configuration File
625
760
 
@@ -640,13 +775,18 @@ consensus:
640
775
  # API settings
641
776
  apis:
642
777
  openai:
643
- model: gpt-4o
778
+ model: gpt-4o # Accepts any model name (e.g., gpt-5)
644
779
  temperature: 0.3
645
780
  max_tokens: 4096
646
781
  gemini:
647
- model: gemini-2.0-flash
782
+ model: gemini-2.0-flash # Accepts any model name
783
+ temperature: 0.3
784
+ max_tokens: 4096
785
+ grok:
786
+ model: grok-3 # Accepts any model name
648
787
  temperature: 0.3
649
788
  max_tokens: 4096
789
+ api_url: https://api.x.ai/v1
650
790
 
651
791
  # Rate limit settings
652
792
  rateLimit:
@@ -673,7 +813,7 @@ POPEYE_OPENAI_KEY=sk-... # OpenAI API key
673
813
 
674
814
  # Optional
675
815
  POPEYE_GEMINI_KEY=... # Gemini API key (for arbitration)
676
- POPEYE_DEFAULT_LANGUAGE=python # Default output language
816
+ POPEYE_DEFAULT_LANGUAGE=python # Default output language (python/typescript/fullstack/website/all)
677
817
  POPEYE_OPENAI_MODEL=gpt-4o # OpenAI model
678
818
  POPEYE_GEMINI_MODEL=gemini-2.0-flash # Gemini model
679
819
  POPEYE_CONSENSUS_THRESHOLD=95 # Consensus threshold (0-100)
@@ -681,13 +821,14 @@ POPEYE_MAX_ITERATIONS=10 # Max iterations before escalation
681
821
  POPEYE_REVIEWER=openai # Primary reviewer (openai, gemini, or grok)
682
822
  POPEYE_ARBITRATOR=gemini # Arbitrator (openai, gemini, grok, or off)
683
823
  POPEYE_GROK_KEY=... # Grok API key (optional)
824
+ POPEYE_GROK_MODEL=grok-3 # Grok model (any model name accepted)
684
825
  POPEYE_LOG_LEVEL=debug # Enable verbose logging
685
826
  ```
686
827
 
687
828
  ### Configuration Priority
688
829
 
689
830
  1. Environment variables (highest)
690
- 2. Project-level `popeye.md` (for language, reviewer, arbitrator)
831
+ 2. Project-level `popeye.md` (for language, reviewer, arbitrator, and all 3 model selections)
691
832
  3. Project-level `popeye.config.yaml` or `.popeyerc.yaml`
692
833
  4. Global `~/.popeye/config.yaml`
693
834
  5. Built-in defaults (lowest)
@@ -794,7 +935,38 @@ my-project/
794
935
 
795
936
  ├── docs/
796
937
  │ ├── PLAN.md # Development plan with [FE], [BE], [INT] tags
797
- └── WORKFLOW_LOG.md
938
+ ├── WORKFLOW_LOG.md
939
+ │ └── plans/ # Consensus documentation (fullstack/all projects)
940
+ │ ├── master/
941
+ │ │ ├── plan.md
942
+ │ │ ├── metadata.json
943
+ │ │ ├── unified/ # Cross-app feedback
944
+ │ │ │ ├── feedback.json
945
+ │ │ │ └── feedback.md
946
+ │ │ ├── frontend/ # Frontend-specific feedback
947
+ │ │ │ ├── feedback.json
948
+ │ │ │ └── feedback.md
949
+ │ │ ├── backend/ # Backend-specific feedback
950
+ │ │ │ ├── feedback.json
951
+ │ │ │ └── feedback.md
952
+ │ │ └── website/ # Website-specific feedback (ALL projects)
953
+ │ │ ├── feedback.json
954
+ │ │ └── feedback.md
955
+ │ └── milestone-N/
956
+ │ ├── plan.md
957
+ │ ├── metadata.json
958
+ │ ├── unified/
959
+ │ ├── frontend/
960
+ │ ├── backend/
961
+ │ ├── website/
962
+ │ └── tasks/
963
+ │ └── task-N/
964
+ │ ├── plan.md
965
+ │ ├── metadata.json
966
+ │ ├── unified/
967
+ │ ├── frontend/
968
+ │ ├── backend/
969
+ │ └── website/
798
970
  ├── README.md
799
971
  ├── .gitignore
800
972
  ├── .env.example
@@ -802,9 +974,34 @@ my-project/
802
974
  ├── popeye.md # Project configuration
803
975
  └── .popeye/
804
976
  ├── state.json
977
+ ├── workspace.json # Workspace configuration for multi-app projects
805
978
  └── ui-spec.json
806
979
  ```
807
980
 
981
+ ### ALL Projects (Fullstack + Website)
982
+
983
+ For projects using the `all` language option, an additional `website/` app is included:
984
+
985
+ ```
986
+ my-project/
987
+ ├── apps/
988
+ │ ├── frontend/ # React application
989
+ │ ├── backend/ # FastAPI backend
990
+ │ └── website/ # Marketing/landing site
991
+ │ ├── src/
992
+ │ │ ├── pages/
993
+ │ │ ├── components/
994
+ │ │ └── content/
995
+ │ ├── public/
996
+ │ ├── package.json
997
+ │ └── astro.config.mjs # (or next.config.js, etc.)
998
+
999
+ ├── docs/
1000
+ │ └── plans/ # Includes website/ directories
1001
+ │ └── ...
1002
+ └── ...
1003
+ ```
1004
+
808
1005
  ## UI Design System
809
1006
 
810
1007
  Popeye automatically generates a complete UI design system for frontend projects. The design decisions are based on analyzing your project idea and are fully customizable.
@@ -945,7 +1142,7 @@ src/
945
1142
  ├── cli/ # CLI interface
946
1143
  │ ├── index.ts # Command setup
947
1144
  │ ├── output.ts # Output formatting
948
- │ ├── interactive.ts # REPL mode
1145
+ │ ├── interactive.ts # REPL mode (with /model, /upgrade commands)
949
1146
  │ └── commands/ # Individual commands
950
1147
  ├── adapters/ # AI service adapters
951
1148
  │ ├── claude.ts # Claude Agent SDK (with rate limiting)
@@ -956,33 +1153,43 @@ src/
956
1153
  │ ├── keychain.ts # Credential storage
957
1154
  │ └── server.ts # OAuth callback server
958
1155
  ├── config/ # Configuration
959
- │ ├── schema.ts # Zod schemas
1156
+ │ ├── schema.ts # Zod schemas (uses OutputLanguageSchema for default_language)
960
1157
  │ ├── defaults.ts # Default values
961
1158
  │ └── index.ts # Config loading
962
1159
  ├── generators/ # Project generators
963
1160
  │ ├── python.ts # Python scaffolding
964
1161
  │ ├── typescript.ts # TypeScript scaffolding
1162
+ │ ├── fullstack.ts # Fullstack scaffolding (React + FastAPI)
1163
+ │ ├── website.ts # Website scaffolding (Next.js)
1164
+ │ ├── all.ts # ALL project scaffolding (exports 5 generator functions)
965
1165
  │ └── templates/ # File templates
966
1166
  ├── state/ # State management
967
1167
  │ ├── persistence.ts # File operations
968
1168
  │ └── index.ts # State API + verification
1169
+ ├── upgrade/ # Project type upgrade system
1170
+ │ ├── transitions.ts # Valid upgrade paths and transition details
1171
+ │ ├── handlers.ts # Upgrade handlers (4 paths with file scaffolding)
1172
+ │ ├── index.ts # Transactional orchestrator with backup/rollback
1173
+ │ └── context.ts # Builds rich context for post-upgrade planning
969
1174
  ├── workflow/ # Workflow engine
970
1175
  │ ├── consensus.ts # Consensus loop
971
- │ ├── plan-mode.ts # Planning phase
1176
+ │ ├── plan-mode.ts # Planning phase (monorepo-aware context scanning)
972
1177
  │ ├── execution-mode.ts # Execution phase
973
1178
  │ ├── milestone-workflow.ts
974
- │ ├── task-workflow.ts
1179
+ │ ├── task-workflow.ts # Uses isWorkspace() for multi-app checks
975
1180
  │ ├── test-runner.ts # Test execution
976
1181
  │ ├── workflow-logger.ts # Persistent logging
1182
+ │ ├── plan-storage.ts # Consensus docs storage (per-app feedback)
1183
+ │ ├── workspace-manager.ts # Multi-app workspace management
977
1184
  │ ├── ui-designer.ts # AI-powered UI design generation
978
1185
  │ ├── ui-setup.ts # Tailwind/shadcn setup automation
979
1186
  │ ├── ui-verification.ts # UI setup verification
980
1187
  │ ├── project-verification.ts # Project quality checks
981
1188
  │ └── auto-fix.ts # Automatic error fixing
982
1189
  └── types/ # TypeScript types
983
- ├── project.ts
984
- ├── workflow.ts
985
- └── consensus.ts
1190
+ ├── project.ts # OutputLanguage, isWorkspace(), flexible OpenAIModelSchema
1191
+ ├── workflow.ts # ProjectStateSchema (uses OutputLanguageSchema)
1192
+ └── consensus.ts # GeminiModelSchema, GrokModelSchema, KNOWN_GEMINI_MODELS
986
1193
  ```
987
1194
 
988
1195
  ## Development
@@ -3,6 +3,7 @@
3
3
  * Wraps the Claude Agent SDK for code execution and generation
4
4
  */
5
5
  import { type SDKMessage } from '@anthropic-ai/claude-agent-sdk';
6
+ import type { OutputLanguage } from '../types/project.js';
6
7
  /**
7
8
  * Options for executing a prompt through Claude
8
9
  */
@@ -106,7 +107,7 @@ export declare function analyzeCodebase(cwd: string, onProgress?: (message: stri
106
107
  * @param language - Target programming language (default: 'python')
107
108
  * @param onProgress - Progress callback
108
109
  */
109
- export declare function createPlan(specification: string, context?: string, language?: 'python' | 'typescript' | 'fullstack', onProgress?: (message: string) => void): Promise<ClaudeExecuteResult>;
110
+ export declare function createPlan(specification: string, context?: string, language?: OutputLanguage, onProgress?: (message: string) => void): Promise<ClaudeExecuteResult>;
110
111
  /**
111
112
  * Revise a plan based on feedback
112
113
  *
@@ -116,5 +117,5 @@ export declare function createPlan(specification: string, context?: string, lang
116
117
  * @param language - Target programming language (default: 'python')
117
118
  * @param onProgress - Progress callback
118
119
  */
119
- export declare function revisePlan(originalPlan: string, feedback: string, concerns: string[], language?: 'python' | 'typescript' | 'fullstack', onProgress?: (message: string) => void): Promise<ClaudeExecuteResult>;
120
+ export declare function revisePlan(originalPlan: string, feedback: string, concerns: string[], language?: OutputLanguage, onProgress?: (message: string) => void): Promise<ClaudeExecuteResult>;
120
121
  //# sourceMappingURL=claude.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/adapters/claude.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/adapters/claude.ts"],"names":[],"mappings":"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"}