popeye-cli 1.6.0 → 1.8.0

package/README.md

@@ -22,10 +22,11 @@ Popeye is an autonomous software development agent that takes a simple project i
 5. **Plans** a complete development roadmap with milestones and tasks
 6. **Validates** the plan through AI consensus (multiple AI systems must agree)
 7. **Implements** each task autonomously, writing production-quality code
-8. **Scans** generated website files for placeholder fingerprints (TODO comments, lorem ipsum, default tiers) and reports quality warnings
-9. **Styles** the application with a professional design system and component library
-10. **Tests** the implementation and fixes issues automatically
-11. **Delivers** a complete, working project with polished UI
+8. **QA Gates** each task through an independent Tester that plans tests, reviews results, and issues PASS/FAIL verdicts
+9. **Scans** generated website files for placeholder fingerprints (TODO comments, lorem ipsum, default tiers) and reports quality warnings
+10. **Styles** the application with a professional design system and component library
+11. **Tests** the implementation and fixes issues automatically with Tester-driven fix plans
+12. **Delivers** a complete, working project with polished UI
 
 ## How It Works
 
@@ -61,12 +62,16 @@ Popeye is an autonomous software development agent that takes a simple project i
 │                                                           │              │
 │                                                           ▼              │
 │                  ┌────────────────────────────────────────────┐          │
-│                  │      EXECUTION MODE                        │          │
+│                  │      EXECUTION MODE (7-Phase Task Workflow) │          │
 │                  │  For each task:                             │          │
-│                  │    1. Claude implements                     │          │
-│                  │    2. Tests run automatically               │          │
-│                  │    3. Fix issues (up to 3 retries)          │          │
-│                  │    4. Mark complete                         │          │
+│                  │    1. Coder creates implementation plan     │          │
+│                  │    2. Code plan consensus (95%+)            │          │
+│                  │    3. Tester creates test plan (QA)         │          │
+│                  │    4. Test plan consensus (90%+)            │          │
+│                  │    5. Claude implements code                │          │
+│                  │    6. Tests run automatically               │          │
+│                  │    7. Tester reviews results (QA verdict)   │          │
+│                  │    Fix issues via Tester fix plans          │          │
 │                  └────────────────────────────────────────────┘          │
 │                                                           │              │
 │                                                           ▼              │
@@ -107,7 +112,7 @@ Popeye uses multiple AI systems that must agree before implementation begins:
 - **Google Gemini** (optional): Can be configured as reviewer or arbitrator when consensus gets stuck
 - **xAI Grok** (optional): Can be configured as reviewer or arbitrator as an alternative to Gemini
 
-Plans are iteratively refined until systems reach **95%+ consensus**, ensuring well-thought-out implementations. When consensus cannot be reached, an arbitrator (configurable) makes the final decision.
+Plans are iteratively refined until systems reach **95%+ consensus**, ensuring well-thought-out implementations. Test plans go through a separate consensus round at a configurable threshold (default **90%+**). When consensus cannot be reached, an arbitrator (configurable) makes the final decision.
 
 ---
 
@@ -121,7 +126,7 @@ Instead of a single "genius" model, Popeye operates as a **virtual AI developmen
 
 Every decision is recorded. Every disagreement is traceable. Nothing happens silently.
 
-### The Three Roles
+### The Four Roles
 
 #### 1. Planner & Builder (The Implementer)
 
@@ -162,16 +167,38 @@ The Arbitrator:
 Think of this role as:
 > *A tech lead making the call after a heated design review.*
 
+#### 4. Tester (The QA Gate)
+
+This role is the **independent quality authority**. It does not implement code -- it validates it.
+
+It:
+- designs structured test plans with acceptance criteria and risk focus areas
+- discovers project test infrastructure (package.json scripts, pytest, Makefile targets)
+- reviews test execution results against the approved test plan
+- issues a verdict: PASS, PASS_WITH_NOTES, or FAIL
+- creates fix plans with root cause analysis when tests fail
+- documents all test plans and reviews in `docs/qa/`
+
+Think of this role as:
+> *A dedicated QA engineer who cannot be overridden by the developer.*
+
+The Tester is provider-agnostic and uses whichever AI provider is configured. Its test plans go through their own consensus round (default threshold: 90%). ONLY the Tester decides whether code passes quality gates -- the coder cannot bypass or override a FAIL verdict.
+
 ### How the Loop Works
 
 ```
 1. You describe your idea
-2. Planner generates a spec and implementation
-3. Reviewer audits the plan and code
-4. If the Reviewer approves → continue
-5. If the Reviewer objects → feedback is sent back
-6. If disagreement persists → Arbitrator decides
-7. Final decision is applied and logged
+2. Planner generates a spec and implementation plan
+3. Reviewer audits the code plan (95%+ consensus)
+4. If the Reviewer approves → Tester designs a test plan
+5. Reviewer audits the test plan (90%+ consensus)
+6. If the Reviewer objects → feedback is sent back for revision
+7. If disagreement persists → Arbitrator decides
+8. Planner implements the code
+9. Tests run automatically
+10. Tester reviews results and issues PASS/FAIL verdict
+11. If FAIL → Tester creates fix plan → coder fixes → retest
+12. Final decisions are applied and logged
 ```
 
 No silent overrides. No "AI magic happened here".
@@ -369,7 +396,14 @@ Popeye provides real-time feedback:
 [Consensus] Review round 2: 92% agreement
 [Consensus] Review round 3: 97% agreement - APPROVED
 [Execute] Milestone 1: Project Setup
-[Execute]   Task 1.1: Initialize project structure... DONE
+[Execute]   Task 1.1: Code plan created
+[Consensus]   Code plan consensus: 96% - APPROVED
+[QA]   Tester designing test plan...
+[Consensus]   Test plan consensus: 92% - APPROVED
+[Execute]   Task 1.1: Implementing...
+[QA]   Running tests... 12 passed, 0 failed
+[QA]   Tester verdict: PASS
+[Execute]   Task 1.1: DONE
 [Execute]   Task 1.2: Configure dependencies... DONE
 [Execute] Milestone 2: Core Implementation
 ...
@@ -382,17 +416,18 @@ Popeye provides real-time feedback:
 [Complete] Project built successfully!
 ```
 
-**Note:** The `[Website Strategy]`, `[Validation]`, and `[Content Scan]` steps appear only for `website` and `all` project types. The marketing strategist persona for consensus review is also specific to website projects. Validation warnings are informational and do not block generation (except in direct `website.ts` generation, where blocking issues cause an error).
+**Note:** The `[Website Strategy]`, `[Validation]`, and `[Content Scan]` steps appear only for `website` and `all` project types. The marketing strategist persona for consensus review is also specific to website projects. Validation warnings are informational and do not block generation (except in direct `website.ts` generation, where blocking issues cause an error). The `[QA]` steps appear when QA is enabled (`qaEnabled: true`, the default for new projects). Existing projects without `qaEnabled` skip QA phases automatically.
 
 ## Features
 
 ### Core Features
 
 - **Fully Autonomous**: Runs from idea to complete project without manual intervention
-- **Dual-AI Consensus**: Plans validated by multiple AI systems before execution
+- **Dual-AI Consensus**: Both code plans and test plans validated by multiple AI systems before execution
 - **Multi-Language Support**: Generate projects in Python, TypeScript, Fullstack (React + FastAPI), Website, or ALL (React + FastAPI + Website)
-- **Automatic Testing**: Tests are generated and run for each implementation
-- **Error Recovery**: Failed tests trigger automatic fix attempts (up to 3 retries)
+- **Independent QA Tester**: A dedicated Tester persona plans tests, reviews results, and issues PASS/FAIL verdicts that the coder cannot override
+- **Automatic Testing**: Tests are generated and run for each implementation, gated by QA review
+- **Error Recovery**: Failed tests trigger Tester-authored fix plans with root cause analysis (up to 3 retries)
 - **Auto-Generated README**: At project completion, generates a comprehensive README with:
   - Project description and features
   - Prerequisites and installation instructions
@@ -607,6 +642,137 @@ The consensus system tracks approval separately for each app target:
   - 15-minute timeout with automatic arbitration
   - Per-iteration timing logs for debugging
 
+### QA Tester Skill
+
+Popeye includes a dedicated **Tester (QA) persona** that operates independently from the coder. The Tester is responsible for test quality and cannot be bypassed or overridden.
+
+#### 7-Phase Task Workflow
+
+When QA is enabled, each task goes through an expanded workflow:
+
+```
+1. Coder Plan       - AI creates a detailed implementation plan
+2. Code Consensus   - Reviewer validates the code plan (95%+ threshold)
+3. Test Plan        - Tester designs a structured test plan with acceptance criteria
+4. Test Consensus   - Reviewer validates the test plan (90%+ threshold, configurable)
+5. Implement        - Claude implements the code according to the approved plan
+6. Run Tests        - Test commands execute automatically
+7. QA Review        - Tester reviews results and issues PASS/FAIL/PASS_WITH_NOTES verdict
+```
+
+If the Tester issues a **FAIL** verdict, it creates a fix plan with root cause analysis that guides the coder's fix implementation. The cycle repeats until the Tester approves.
+
+#### Test Plan Structure
+
+The Tester produces structured test plans containing:
+
+| Field | Description |
+|-------|-------------|
+| **summary** | What risks the test plan targets |
+| **scope** | Components covered (frontend, backend, db, infra) |
+| **testMatrix** | Test cases with ID, category, acceptance criteria, priority |
+| **commands** | Exact shell commands with cwd, purpose, and required flag |
+| **riskFocus** | Top 3-7 risks being tested |
+| **minimumVerification** | Always includes build check, lint check, and smoke test |
+
+#### Test Infrastructure Discovery
+
+The Tester automatically discovers available test commands by inspecting:
+- `package.json` scripts (test, lint, build, typecheck)
+- `pyproject.toml` (pytest, ruff, mypy)
+- `Makefile` targets (test, lint, build)
+
+Language-specific defaults are used as fallbacks when no configuration is found.
+
+#### QA Documentation
+
+All QA artifacts are persisted for auditability:
+- **Test Plans**: `docs/qa/test-plans/milestone_N_task_N.md`
+- **Test Reviews**: `docs/qa/test-runs/milestone_N_task_N.md`
+
+Each document includes metadata (consensus score, iterations, timestamps) and the full plan or review content.
+
+#### QA Opt-in Behavior
+
+| Project Type | qaEnabled |
+|-------------|-----------|
+| New projects | `true` (default) |
+| Existing projects (pre-QA) | `undefined` (QA phases skipped) |
+| Manually disabled | `false` (QA phases skipped) |
+
+The `qaEnabled` field in `ProjectState` controls whether the 7-phase workflow is used. When QA is disabled, tasks use the original 4-phase flow (Plan -> Consensus -> Implement -> Test).
+
+#### Configurable Thresholds
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `consensus.threshold` | 95 | Code plan consensus threshold |
+| `consensus.testPlanThreshold` | 90 | Test plan consensus threshold (lower to avoid over-engineering test plans) |
+
+### Deferred Database Integration
+
+Fullstack and ALL projects include a 3-phase deferred database integration system. Instead of requiring a running database at project creation time, Popeye generates all the necessary database scaffolding and provides tools to configure and apply it later.
+
+#### Phase 1: Types and Templates
+
+The database layer generates production-ready templates for:
+
+| Template Set | Contents |
+|-------------|----------|
+| **SQLAlchemy** | Connection module, startup hook, health route, conftest, Alembic config, initial migration |
+| **Alembic** | `alembic.ini`, `env.py`, initial migration script |
+| **pgvector** | Vector extension setup for AI/ML workloads |
+| **Docker** | `docker-compose.yml` with PostgreSQL service, health checks, volumes |
+| **Environment** | `.env.example` with `DATABASE_URL`, `ADMIN_SETUP_TOKEN` |
+
+Database configuration is tracked in `ProjectState.dbConfig` with the following status lifecycle:
+
+```
+none -> configured -> migrating -> ready
+                  \-> error
+```
+
+#### Phase 2: State Machine and CLI Commands
+
+The database lifecycle is managed by a state machine (`db-state-machine.ts`) that enforces valid transitions between statuses. Two CLI commands provide management:
+
+**`/db [action]`** -- Database management:
+- `/db status` -- Show current database configuration and status
+- `/db configure` -- Interactively set DATABASE_URL and write to `.env`
+- `/db apply` -- Run the setup pipeline (create tables, run migrations)
+
+**`/doctor`** -- Readiness checks (8 checks):
+- `.env` file exists with `DATABASE_URL`
+- Backend directory structure is valid
+- `requirements.txt` includes database dependencies
+- Alembic configuration is present
+- Docker Compose includes postgres service
+- Database connection is reachable
+- Migrations are up to date
+- Health endpoint returns OK
+
+#### Phase 3: Admin Wizard UI
+
+The admin wizard generates a complete database setup experience with both backend and frontend components:
+
+**Backend (FastAPI):**
+- `admin_auth.py` middleware -- Validates `X-Admin-Token` header against `ADMIN_SETUP_TOKEN` env var
+- `admin_db.py` routes -- RESTful endpoints under `/api/admin/db`:
+  - `GET /status` -- Current DB status, migration count, connection info
+  - `POST /configure` -- Save database URL to `.env`
+  - `POST /test` -- Test database connectivity
+  - `POST /apply` -- Run Alembic migrations
+  - `POST /rollback` -- Roll back the last migration
+
+**Frontend (React):**
+- `useAdminApi` hook -- Authenticated API calls with `X-Admin-Token` header
+- `DbStatusBanner` -- Displays current database status with color-coded indicators
+- `ConnectionForm` -- Database URL input with connection test button
+- `MigrationProgress` -- Real-time migration progress display
+- `DbSetupStepper` -- Step-by-step wizard guiding the full setup flow
+
+Both the `fullstack.ts` and `all.ts` generators wire the admin wizard layer automatically. The admin wizard files are included in `getFullstackProjectFiles()` and `getAllProjectFiles()` for validation.
+
 ### Observability Features
 
 - **Workflow Logging**: Detailed logs written to `docs/WORKFLOW_LOG.md`
@@ -753,6 +919,9 @@ popeye
 /model [provider] [model]  Show/set AI model (openai/gemini/grok)
 /model <provider> list     Show known models for a provider
 /upgrade [target]          Upgrade project type (e.g., fullstack -> all)
+/overview [fix]            Project review with analysis; fix to auto-discover docs
+/db [action]               Database management (status/configure/apply)
+/doctor                    Run database and project readiness checks
 /info                      Show system info (Claude CLI status, API keys, etc.)
 /clear                     Clear screen
 /exit                      Exit interactive mode
@@ -899,7 +1068,8 @@ Create `popeye.config.yaml` in your project or `~/.popeye/config.yaml` globally:
 ```yaml
 # Consensus settings
 consensus:
-  threshold: 95              # Minimum agreement percentage
+  threshold: 95              # Minimum agreement percentage (code plans)
+  test_plan_threshold: 90    # Minimum agreement percentage (test plans, lower to avoid over-engineering)
   max_iterations: 10         # Max revision rounds
   reviewer: openai           # Primary reviewer (openai, gemini, or grok)
   arbitrator: gemini         # Arbitrator when stuck (openai, gemini, grok, or off)
@@ -983,7 +1153,10 @@ my-project/
 │   └── conftest.py
 ├── docs/
 │   ├── PLAN.md              # Development plan
-│   └── WORKFLOW_LOG.md      # Execution log
+│   ├── WORKFLOW_LOG.md      # Execution log
+│   └── qa/                  # QA documentation (when qaEnabled)
+│       ├── test-plans/      # Approved test plans per task
+│       └── test-runs/       # Test review verdicts per task
 ├── pyproject.toml
 ├── requirements.txt
 ├── README.md
@@ -1044,6 +1217,13 @@ my-project/
 │   │   ├── src/
 │   │   │   ├── components/
 │   │   │   │   └── ui/        # shadcn/ui components
+│   │   │   ├── admin/              # Admin wizard components
+│   │   │   │   ├── useAdminApi.ts      # Authenticated API hook
+│   │   │   │   ├── DbStatusBanner.tsx  # DB status indicator
+│   │   │   │   ├── ConnectionForm.tsx  # DB URL input + test
+│   │   │   │   ├── MigrationProgress.tsx # Migration progress
+│   │   │   │   ├── DbSetupStepper.tsx  # Setup wizard stepper
+│   │   │   │   └── index.ts           # Admin component exports
 │   │   │   ├── pages/
 │   │   │   ├── hooks/
 │   │   │   ├── lib/
@@ -1059,11 +1239,22 @@ my-project/
 │   │
 │   └── backend/               # FastAPI backend
 │       ├── src/
-│       │   ├── api/
-│       │   │   └── routes/
+│       │   ├── {package}/
+│       │   │   ├── routes/
+│       │   │   │   ├── health_db.py    # DB health endpoint
+│       │   │   │   └── admin_db.py     # Admin wizard routes
+│       │   │   ├── middleware/
+│       │   │   │   ├── __init__.py
+│       │   │   │   └── admin_auth.py   # X-Admin-Token validation
+│       │   │   ├── db.py               # SQLAlchemy connection module
+│       │   │   └── main.py
 │       │   ├── models/
 │       │   ├── services/
 │       │   └── main.py
+│       ├── alembic/                    # Database migrations
+│       │   ├── env.py
+│       │   └── versions/
+│       ├── alembic.ini
 │       ├── tests/
 │       │   └── conftest.py
 │       ├── pyproject.toml
@@ -1072,6 +1263,9 @@ my-project/
 ├── docs/
 │   ├── PLAN.md                # Development plan with [FE], [BE], [INT] tags
 │   ├── WORKFLOW_LOG.md
+│   ├── qa/                    # QA documentation (when qaEnabled)
+│   │   ├── test-plans/        # Approved test plans per task
+│   │   └── test-runs/         # Test review verdicts per task
 │   └── plans/                 # Consensus documentation (fullstack/all projects)
 │       ├── master/
 │       │   ├── plan.md
@@ -1106,7 +1300,7 @@ my-project/
 ├── README.md
 ├── .gitignore
 ├── .env.example
-├── docker-compose.yml         # Full stack orchestration
+├── docker-compose.yml         # Full stack orchestration (includes PostgreSQL service)
 ├── popeye.md                  # Project configuration
 └── .popeye/
     ├── state.json
@@ -1325,8 +1519,10 @@ src/
 ├── cli/                  # CLI interface
 │   ├── index.ts          # Command setup
 │   ├── output.ts         # Output formatting
-│   ├── interactive.ts    # REPL mode (with /model, /upgrade, /overview commands)
+│   ├── interactive.ts    # REPL mode (with /model, /upgrade, /overview, /db, /doctor commands)
 │   └── commands/         # Individual commands
+│       ├── db.ts         # Database management CLI (status/configure/apply)
+│       └── doctor.ts     # Readiness checks (8 checks for DB and project health)
 ├── adapters/             # AI service adapters
 │   ├── claude.ts         # Claude Agent SDK (with rate limiting)
 │   ├── openai.ts         # OpenAI API (default reviewer, marketing persona for websites)
@@ -1347,6 +1543,8 @@ src/
 │   ├── website-context.ts # Doc discovery, brand assets, content context, dual-mode validation
 │   ├── website-content-scanner.ts # Post-generation placeholder fingerprint scanner
 │   ├── doc-parser.ts     # Product doc parsing (name, tagline, features, pricing, color)
+│   ├── database.ts       # DB layer orchestration (generatePythonDatabaseLayer, getDatabaseFiles)
+│   ├── admin-wizard.ts   # Admin wizard orchestration (generateAdminWizardLayer, getAdminWizardFiles)
 │   ├── all.ts            # ALL project scaffolding (exports 5 generator functions)
 │   └── templates/        # File templates
 │       ├── python.ts
@@ -1357,6 +1555,10 @@ src/
 │       ├── website-components.ts # Header, Footer, Navigation components
 │       ├── website-seo.ts      # JSON-LD, sitemap, robots, 404, 500, manifest, meta
 │       ├── website-conversion.ts # Lead capture route, contact form, env examples
+│       ├── database-python.ts  # SQLAlchemy + Alembic + pgvector templates (12 functions)
+│       ├── database-docker.ts  # Docker Compose + postgres service templates
+│       ├── admin-wizard-python.ts  # FastAPI admin auth middleware + admin DB routes
+│       ├── admin-wizard-react.ts   # React admin wizard components (status, forms, stepper)
 │       └── index.ts            # Template module exports
 ├── state/                # State management
 │   ├── persistence.ts    # File operations
@@ -1371,9 +1573,12 @@ src/
 │   ├── plan-mode.ts      # Planning phase (strategy generation, monorepo-aware)
 │   ├── execution-mode.ts # Execution phase
 │   ├── milestone-workflow.ts
-│   ├── task-workflow.ts  # Uses isWorkspace() for multi-app checks
+│   ├── task-workflow.ts  # 7-phase task workflow with QA gate
+│   ├── tester.ts         # QA skill: test planning, review, fix plans (provider-agnostic)
+│   ├── db-state-machine.ts # DB lifecycle state transitions (canTransition, transitionDbStatus)
+│   ├── db-setup-runner.ts  # DB setup pipeline runner (env parsing, migration prereqs)
 │   ├── test-runner.ts    # Test execution
-│   ├── workflow-logger.ts # Persistent logging (website-strategy stage)
+│   ├── workflow-logger.ts # Persistent logging (test-planning, test-review stages)
 │   ├── plan-storage.ts   # Consensus docs storage (per-app feedback)
 │   ├── workspace-manager.ts # Multi-app workspace management
 │   ├── website-strategy.ts  # AI strategy generation, caching, staleness detection
@@ -1388,8 +1593,11 @@ src/
 │   └── auto-fix.ts       # Automatic error fixing (enhanced ENOENT tracking)
 └── types/                # TypeScript types
     ├── project.ts        # OutputLanguage, isWorkspace(), flexible OpenAIModelSchema
-    ├── workflow.ts       # ProjectStateSchema (websiteStrategy field)
-    ├── consensus.ts      # GeminiModelSchema, GrokModelSchema, reviewerPersona
+    ├── workflow.ts       # ProjectStateSchema (qaEnabled, dbConfig, qa* task fields)
+    ├── consensus.ts      # GeminiModelSchema, GrokModelSchema, reviewerPersona, testPlanThreshold
+    ├── tester.ts         # TestVerdict, TestPlanOutput, TestRunReview, TestFixPlan
+    ├── database.ts       # DbStatus, DbMode, DbConfig, DbSetupStep Zod schemas
+    ├── database-runtime.ts # SetupStepResult, ReadinessCheck runtime schemas
     └── website-strategy.ts # WebsiteStrategyDocument, BrandAssetsContract, DesignTokens
 ```