codex-genesis-harness 0.1.4 → 0.1.6

package/.codex/skills/genesis-harness/resources/project-template.md

@@ -1,38 +1,38 @@
-# Project
-
-## What This Project Is
-
-TBD
-
-## Target Users
-
-TBD
-
-## Core Value
-
-TBD
-
-## Product Scope
-
-- [ ] TBD
-
-## Out Of Scope
-
-- [ ] TBD
-
-## Constraints
-
-- [ ] TBD
-
-## Assumptions
-
-- [ ] TBD
-
-## Current Milestone
-
-TBD
-
-## Success Criteria
-
-- [ ] TBD
-
+# Project
+
+## What This Project Is
+
+TBD
+
+## Target Users
+
+TBD
+
+## Core Value
+
+TBD
+
+## Product Scope
+
+- [ ] TBD
+
+## Out Of Scope
+
+- [ ] TBD
+
+## Constraints
+
+- [ ] TBD
+
+## Assumptions
+
+- [ ] TBD
+
+## Current Milestone
+
+TBD
+
+## Success Criteria
+
+- [ ] TBD
+

package/.codex/skills/genesis-harness/resources/quality-score-template.md

@@ -1,11 +1,11 @@
-# Quality Score
-
-| Area | Score | Issues | Next Action |
-|---|---:|---|---|
-| Architecture | 0/10 | TBD | TBD |
-| Tests | 0/10 | TBD | TBD |
-| Docs Sync | 0/10 | TBD | TBD |
-| Security | 0/10 | TBD | TBD |
-| Maintainability | 0/10 | TBD | TBD |
-| Observability | 0/10 | TBD | TBD |
-
+# Quality Score
+
+| Area | Score | Issues | Next Action |
+|---|---:|---|---|
+| Architecture | 0/10 | TBD | TBD |
+| Tests | 0/10 | TBD | TBD |
+| Docs Sync | 0/10 | TBD | TBD |
+| Security | 0/10 | TBD | TBD |
+| Maintainability | 0/10 | TBD | TBD |
+| Observability | 0/10 | TBD | TBD |
+

package/.codex/skills/genesis-harness/resources/requirements-template.md

@@ -1,26 +1,26 @@
-# Requirements
-
-## Functional Requirements
-
-- [ ] TBD
-
-## Non-Functional Requirements
-
-- [ ] TBD
-
-## User Stories
-
-- [ ] As a user, I want TBD so that TBD.
-
-## Acceptance Criteria
-
-- [ ] TBD
-
-## Edge Cases
-
-- [ ] TBD
-
-## Known Unknowns
-
-- [ ] TBD
-
+# Requirements
+
+## Functional Requirements
+
+- [ ] TBD
+
+## Non-Functional Requirements
+
+- [ ] TBD
+
+## User Stories
+
+- [ ] As a user, I want TBD so that TBD.
+
+## Acceptance Criteria
+
+- [ ] TBD
+
+## Edge Cases
+
+- [ ] TBD
+
+## Known Unknowns
+
+- [ ] TBD
+

package/.codex/skills/genesis-harness/resources/research-template.md

@@ -1,26 +1,26 @@
-# Research
-
-## Question
-
-TBD
-
-## Local Codebase Findings
-
-- [ ] TBD
-
-## External Findings
-
-- [ ] TBD
-
-## Sources
-
-- TBD
-
-## Decision Impact
-
-TBD
-
-## Risks
-
-- [ ] TBD
-
+# Research
+
+## Question
+
+TBD
+
+## Local Codebase Findings
+
+- [ ] TBD
+
+## External Findings
+
+- [ ] TBD
+
+## Sources
+
+- TBD
+
+## Decision Impact
+
+TBD
+
+## Risks
+
+- [ ] TBD
+

package/.codex/skills/genesis-harness/resources/review-template.md

@@ -1,22 +1,22 @@
-# Review
-
-## Changed Files Reviewed
-
-- [ ] TBD
-
-## Findings
-
-| Severity | File | Issue | Required Action |
-|---|---|---|---|
-| TBD | TBD | TBD | TBD |
-
-## Cleanup Performed
-
-- [ ] Removed unnecessary files/code
-- [ ] Removed debug logs
-- [ ] Removed unrelated changes
-
-## Residual Risks
-
-- [ ] TBD
-
+# Review
+
+## Changed Files Reviewed
+
+- [ ] TBD
+
+## Findings
+
+| Severity | File | Issue | Required Action |
+|---|---|---|---|
+| TBD | TBD | TBD | TBD |
+
+## Cleanup Performed
+
+- [ ] Removed unnecessary files/code
+- [ ] Removed debug logs
+- [ ] Removed unrelated changes
+
+## Residual Risks
+
+- [ ] TBD
+

package/.codex/skills/genesis-harness/resources/spec-changelog-template.md

@@ -1,6 +1,6 @@
-# Spec Changelog
-
-| Date/Time | Change | Reason | Impacted Docs | Impacted Tests | Migration Notes |
-|---|---|---|---|---|---|
-| TBD | Initial harness setup | Project initialization | TBD | TBD | TBD |
-
+# Spec Changelog
+
+| Date/Time | Change | Reason | Impacted Docs | Impacted Tests | Migration Notes |
+|---|---|---|---|---|---|
+| TBD | Initial harness setup | Project initialization | TBD | TBD | TBD |
+

package/.codex/skills/genesis-harness/resources/stack-template.md

@@ -1,33 +1,33 @@
-# Stack
-
-## Detected Stack
-
-Language:
-Framework:
-Runtime:
-Database:
-Package manager:
-Test framework:
-Lint:
-Typecheck:
-Build:
-Deployment:
-
-## Version Constraints
-
-- [ ] TBD
-
-## Local Development Commands
-
-```sh
-# start
-# test
-# lint
-# typecheck
-# build
-```
-
-## Tooling Gaps
-
-- [ ] TBD
-
+# Stack
+
+## Detected Stack
+
+Language:
+Framework:
+Runtime:
+Database:
+Package manager:
+Test framework:
+Lint:
+Typecheck:
+Build:
+Deployment:
+
+## Version Constraints
+
+- [ ] TBD
+
+## Local Development Commands
+
+```sh
+# start
+# test
+# lint
+# typecheck
+# build
+```
+
+## Tooling Gaps
+
+- [ ] TBD
+

package/.codex/skills/genesis-harness/resources/verification-template.md

@@ -1,26 +1,26 @@
-# Verification
-
-## Test Contract
-
-- [ ] Normal input/output
-- [ ] Edge cases
-- [ ] Invalid inputs
-- [ ] Expected errors
-- [ ] Acceptance tests
-
-## Commands
-
-```sh
-# TBD
-```
-
-## Results
-
-| Command | Result | Evidence |
-|---|---|---|
-| TBD | TBD | TBD |
-
-## Manual Verification
-
-- [ ] TBD
-
+# Verification
+
+## Test Contract
+
+- [ ] Normal input/output
+- [ ] Edge cases
+- [ ] Invalid inputs
+- [ ] Expected errors
+- [ ] Acceptance tests
+
+## Commands
+
+```sh
+# TBD
+```
+
+## Results
+
+| Command | Result | Evidence |
+|---|---|---|
+| TBD | TBD | TBD |
+
+## Manual Verification
+
+- [ ] TBD
+

package/.codex/skills/genesis-mvp-planning/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: genesis-mvp-planning
+description: "Define, structure, and automate the creation of a standard 5-Phase MVP Roadmap right after project initialization. Guarantees a decision-complete path to production-ready launch."
+---
+
+# Genesis MVP 5-Phase Planning Skill
+
+## Purpose
+
+The `genesis-mvp-planning` skill is designed to transition a newly initialized project into a structured, decision-complete **5-Phase MVP Roadmap**. Instead of leaving the repository with only a blank generic Phase 0 (Foundation) folder, this skill maps out the entire lifecycle of a production-ready Minimum Viable Product across exactly 5 logical, sequential phases.
+
+---
+
+## When to use
+
+Use the `genesis-mvp-planning` skill when:
+- You have just run `/genesis-init` (or `/init`) and need to map out the implementation timeline.
+- You want to scope an application specifically to its MVP (Minimum Viable Product) boundaries.
+- You want to establish clear gates and milestones for each stage of the project lifecycle.
+
+---
+
+## When NOT to use
+
+Do NOT use the `genesis-mvp-planning` skill when:
+- The project is already midway through development with a pre-existing mature roadmap.
+- The task is a minor, single-file bug fix or simple refactoring that doesn't affect the project timeline.
+- The roadmap has already been fully approved and is currently active.
+
+---
+
+## Inputs required
+
+Before running this planning skill, ensure the following inputs are gathered:
+- **Project Brief / Intent**: Clear understanding of what application is being built and target users.
+- **Technology Stack**: Backend, frontend, database, auth provider, and deployment target.
+- **Core MVP Features List**: The primary business value proposition that must be delivered.
+
+---
+
+## Outputs required
+
+Executing this skill creates the following structured deliverables:
+- `.planning/ROADMAP.md`: Updated roadmap with 5 distinct phases defined.
+- `.planning/phases/PHASE_1_CORE/`: Planning directory for Phase 1 (Foundation & API Core).
+- `.planning/phases/PHASE_2_AUTH/`: Planning directory for Phase 2 (Authentication & Security).
+- `.planning/phases/PHASE_3_FEATURES/`: Planning directory for Phase 3 (Core MVP Features).
+- `.planning/phases/PHASE_4_INTEGRATIONS/`: Planning directory for Phase 4 (Third-Party Integrations).
+- `.planning/phases/PHASE_5_READINESS/`: Planning directory for Phase 5 (Production Readiness & Observability).
+
+---
+
+## Required tests
+
+The planning deliverables are validated using:
+- [ ] `test/planning/roadmap-structure.test.js`: Verifies `ROADMAP.md` contains all 5 phases with valid status checkboxes.
+- [ ] `test/planning/phase-completeness.test.js`: Verifies each phase directory contains standard `SPEC.md`, `PLAN.md`, and `TASKS.md`.
+
+---
+
+## Required fixtures
+
+- `fixtures/planning/roadmap-expected.md`: The canonical structure of a 5-Phase MVP roadmap.
+- `fixtures/planning/phase-config-expected.json`: Complete configuration template mapping out the 5 phases.
+
+---
+
+## Required contract updates
+
+Update the following files if phase boundary standards change:
+- `contracts/planning/roadmap.schema.json`: Schema validator for `ROADMAP.md` files.
+- `contracts/planning/phase.schema.json`: Schema validator for individual phase directories.
+
+---
+
+## Required codebase map updates
+
+After mapping out the 5-Phase MVP:
+- **`.codebase/CURRENT_STATE.md`**: Update current phase to Phase 1, and add the full 5-phase overview.
+- **`.codebase/MODULE_INDEX.md`**: Add references to each of the 5 phase directories.
+
+---
+
+## Token saving rules
+
+1. **Reuse templates**: Do not rewrite the basic structure of the phases. Use the provided phase templates in `templates/`.
+2. **Summarize context**: Do not read every detail of the repository. Use `SUMMARY.md` and module index.
+3. **Draft sequentially**: Plan one phase at a time to keep prompt sizes small.
+
+---
+
+## Acceptance criteria
+
+The 5-Phase MVP roadmap is ACCEPTED when:
+- [ ] `ROADMAP.md` is updated with 5 clearly defined phases, dates, and success criteria.
+- [ ] All 5 phase planning folders (`PHASE_1_CORE` to `PHASE_5_READINESS`) are created and populated.
+- [ ] No feature code is written before the 5 phase boundaries are validated.
+
+---
+
+## Common mistakes
+
+### Mistake 1: Starting Phase 3 (Core Features) before Phase 1 (API Core)
+- **Problem**: Writing UI screens without verified backend models and schemas leads to massive rework.
+- **Fix**: Complete Phase 1 and 2 to establish a solid database and API contract first.
+
+---
+
+## Recovery workflow
+
+### Recovery 1: Phase drift or timeline changes
+1. Mark the affected phase as `[!] blocked` in `ROADMAP.md`.
+2. Document the change in `SPEC_CHANGELOG.md`.
+3. Adjust downstream phase boundaries accordingly.

package/.codex/skills/genesis-mvp-planning/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Genesis MVP Planning"
+  short_description: "— Xây dựng lộ trình 5 Phase phát triển sản phẩm MVP"
+  default_prompt: "Use $genesis-mvp-planning to map out the 5 essential phases of a production-ready MVP."
+policy:
+  allow_implicit_invocation: true

package/.codex/skills/genesis-mvp-planning/checklists/mvp-readiness.md

@@ -0,0 +1,18 @@
+# MVP Phase Planning Readiness Checklist
+
+Use this checklist to ensure all 5 phases of the MVP are fully defined and ready to proceed.
+
+## Scope & Boundaries
+- [ ] Has the product target audience been clearly defined?
+- [ ] Is the absolute minimum viable feature set (and what is explicitly OUT of scope) documented?
+- [ ] Are success metrics defined for each of the 5 phases?
+
+## Technical Feasibility
+- [ ] Is the technology stack fully decided, including database models and cloud providers?
+- [ ] Are all third-party integrations identified, along with keys/credential requirements?
+- [ ] Are testing and validation tools decided and functional locally?
+
+## Phase Definition Alignment
+- [ ] Do Phase 1 (Core) database schemas align with Phase 3 (Features) functional requirements?
+- [ ] Are security and authorization scopes in Phase 2 prepared to handle Phase 3 routes?
+- [ ] Are Phase 5 deployment and observability targets fully defined?

package/.codex/skills/genesis-mvp-planning/examples/5-phase-roadmap-example.md

@@ -0,0 +1,43 @@
+# Example: 5-Phase MVP Roadmap for "TaskFlow SaaS"
+
+This is an example roadmap representing a completed planning output for a TaskFlow SaaS application.
+
+## ROADMAP Overview
+
+- [x] Phase 0: Foundation & Project Planning (Complete)
+- [ ] Phase 1: Foundation & API Core (Target: 2026-06-15)
+- [ ] Phase 2: Authentication & Security (Target: 2026-06-22)
+- [ ] Phase 3: Core MVP Features (Target: 2026-07-06)
+- [ ] Phase 4: Third-Party Integrations (Target: 2026-07-15)
+- [ ] Phase 5: Production Readiness & Observability (Target: 2026-07-22)
+
+---
+
+## Detailed Phase Definition
+
+### Phase 1: Foundation & API Core
+- **Database ERD**: Users, Tasks, Workspaces, Comments tables.
+- **API Contracts**:
+  - `POST /api/v1/workspaces`
+  - `GET /api/v1/workspaces/:id/tasks`
+- **Verification**: SQL schema migrates successfully; mock endpoints return JSON schemas.
+
+### Phase 2: Authentication & Security
+- **Auth Provider**: Firebase Auth integration.
+- **Route Guards**: All `/api/v1/workspaces` routes require a valid Bearer token.
+- **Verification**: Request without header returns HTTP 401; request with valid token returns HTTP 200.
+
+### Phase 3: Core MVP Features
+- **Functional Flow**: Create workspace, invite user, add task, comment on task.
+- **Frontend Views**: Dashboard, Workspace page, Task Details modal.
+- **Verification**: Playwright e2e test logs in user, creates task, and verifies task appears in UI list.
+
+### Phase 4: Third-Party Integrations
+- **Payment Gateway**: Stripe subscription billing.
+- **Notifications**: Sendgrid transactional email alerts.
+- **Verification**: Stripe webhook registers subscription renewal event correctly; email triggers on task assignment.
+
+### Phase 5: Production Readiness & Observability
+- **Health Checks**: `/health`, `/readiness` checks DB + Stripe connectivity.
+- **Monitoring**: Prom-client registers HTTP request latency histograms.
+- **Verification**: Grafana dashboard imports JSON config successfully; Promtool validates alert rules.

package/.codex/skills/genesis-mvp-planning/templates/phase-1-core.md

@@ -0,0 +1,17 @@
+# Phase 1: Foundation & API Core
+
+## Goal
+Establish the backend foundation, database schemas, and robust API contracts for the MVP. No UI code is written in this phase.
+
+## Tasks
+- [ ] Research and design database models/tables
+- [ ] Define initial schemas (JSON Schemas, SQL Migrations)
+- [ ] Create API contract files under `contracts/api/`
+- [ ] Implement foundational database access layer and initial repository patterns
+- [ ] Build mock API endpoints verifying request/response formats
+- [ ] Implement and verify initial API contract tests
+
+## Success Criteria
+- All database models are defined and migrated.
+- API endpoints return successfully with mock/fixture data matching contracts.
+- Verification tests pass successfully.

package/.codex/skills/genesis-mvp-planning/templates/phase-2-auth.md

@@ -0,0 +1,17 @@
+# Phase 2: Authentication & Security
+
+## Goal
+Secure the application with user authentication, role-based access control, and route guards.
+
+## Tasks
+- [ ] Research stack-specific auth mechanisms (JWT, session, Firebase Auth, etc.)
+- [ ] Configure environment variables for token secrets/keys
+- [ ] Implement Sign-Up, Sign-In, and Sign-Out endpoints and helpers
+- [ ] Implement authorization middleware / route guards
+- [ ] Write integration tests verifying authenticated vs unauthenticated access
+- [ ] Implement secure CORS and headers setup
+
+## Success Criteria
+- User registration and login flow works correctly.
+- Protected API routes return appropriate HTTP 401/403 errors when unauthenticated.
+- All auth unit and integration tests pass successfully.

package/.codex/skills/genesis-mvp-planning/templates/phase-3-features.md

@@ -0,0 +1,17 @@
+# Phase 3: Core MVP Features
+
+## Goal
+Implement the main functional value proposition of the MVP.
+
+## Tasks
+- [ ] Answer checklists/new-feature-qa.md for the core workflows
+- [ ] Plan and outline database updates for core features
+- [ ] Implement core backend business logic, validation rules, and algorithms
+- [ ] Create UI components and pages required for the MVP journeys
+- [ ] Wire up frontend components to backend API services
+- [ ] Write integration and end-to-end user journey tests
+
+## Success Criteria
+- User can successfully complete the primary business journey end-to-end.
+- Data is correctly persisted, modified, and queried from the database.
+- Core business tests pass with >80% code coverage.