codex-genesis-harness 0.1.0

package/.codex/skills/project-genesis-harness/agents/openai.yaml

@@ -0,0 +1,9 @@
+interface:
+  display_name: "Project Genesis Harness"
+  short_description: "Plan, track, verify, and review projects"
+  brand_color: "#2563EB"
+  default_prompt: "Use $project-genesis-harness to initialize planning and operate this repository with test-first workflows."
+
+policy:
+  allow_implicit_invocation: true
+

package/.codex/skills/project-genesis-harness/references/planning-schema.md

@@ -0,0 +1,35 @@
+# Planning Schema Reference
+
+Use this file when creating or auditing `.planning/`.
+
+## Core Files
+
+- `PROJECT.md`: product identity, users, value, scope, out of scope, constraints, assumptions, milestone, success criteria.
+- `REQUIREMENTS.md`: functional requirements, non-functional requirements, user stories, acceptance criteria, edge cases, unknowns.
+- `ROADMAP.md`: milestones, phases, dependencies, status, phase acceptance criteria.
+- `STATE.md`: current phase, active feature or bug, last task, next task, blockers, latest verification.
+- `STACK.md`: language, framework, runtime, database, package manager, tests, lint/typecheck, deployment, local commands.
+- `ARCHITECTURE.md`: architecture, boundaries, data flow, dependency direction, service boundaries, principles, forbidden patterns.
+- `DESIGN.md`: UX principles, screens, components, state management, accessibility, constraints.
+- `API_DOCS.md`: endpoints, examples, errors, auth, versioning.
+- `INTEGRATIONS.md`: services, SDKs, environment variables, secrets, failure handling, fallback behavior, limits.
+- `CONVENTIONS.md`: naming, folders, style, errors, logging, testing, API, security, patterns to follow and avoid.
+- `PITFALLS.md`: common mistakes, risky areas, fragile dependencies, warnings.
+- `LESSONS_LEARNED.md`: bug lessons with root cause, failed assumption, correct pattern, prevention, changed files, verification.
+- `SPEC_CHANGELOG.md`: every spec-affecting change.
+- `QUALITY_SCORE.md`: quality rubric scores and next actions.
+
+## Required Subtrees
+
+- `diagrams/`
+- `research/`
+- `decisions/`
+- `phases/`
+- `features/`
+- `bugs/`
+- `audits/`
+- `checks/`
+- `quick/`
+- `codebase/`
+- `templates/`
+

package/.codex/skills/project-genesis-harness/references/quality-rubric.md

@@ -0,0 +1,21 @@
+# Quality Rubric
+
+Use this file when updating `.planning/QUALITY_SCORE.md`.
+
+| Score | Meaning |
+|---:|---|
+| 0 | Unknown, absent, or not evaluated |
+| 2 | Known major gaps with no mitigation |
+| 4 | Basic structure exists but is inconsistent or mostly manual |
+| 6 | Working baseline with known gaps and follow-up tasks |
+| 8 | Strong, verified, documented, and mostly automated |
+| 10 | Mature, automated, documented, reviewed, and low-risk |
+
+## Areas
+
+- Architecture: module boundaries, dependency direction, diagrams, ADRs, forbidden patterns.
+- Tests: regression coverage, smoke tests, edge cases, failing-first evidence, repeatability.
+- Docs Sync: behavior docs, changelog entries, impact matrix compliance.
+- Security: auth, secrets, data protection, dependency risk, destructive-operation safeguards.
+- Maintainability: naming, duplication, dead code, conventions, module size, refactor risk.
+- Observability: logs, metrics, traces, errors, health checks, debug commands, inspection workflow.

package/.codex/skills/project-genesis-harness/references/research-rubric.md

@@ -0,0 +1,41 @@
+# Research Rubric
+
+Use this file before planning or implementing non-trivial work.
+
+## Required Evidence
+
+| Evidence | Required? | Notes |
+|---|---:|---|
+| Local code paths | Yes | Include file paths or commands. |
+| Similar existing patterns | Yes | Prefer repo conventions over new abstractions. |
+| Official docs | When available | Cite URL or doc name and date checked. |
+| Reputable external examples | When useful | Do not copy architecture blindly. |
+| Unknowns | Yes | Record gaps instead of inventing facts. |
+
+## Output Format
+
+```md
+## Research: <topic>
+
+Date:
+Question:
+
+## Local Evidence
+
+| File / Command | Finding | Impact |
+|---|---|---|
+
+## External Evidence
+
+| Source | Date Checked | Finding | Impact |
+|---|---|---|---|
+
+## Decision Impact
+
+- [ ] TBD
+
+## Confidence / Gaps
+
+- [ ] TBD
+```
+

package/.codex/skills/project-genesis-harness/references/workflows.md

@@ -0,0 +1,33 @@
+# Workflow Reference
+
+Use this file when the requested work is a feature, bug fix, plan, audit, review, or status check.
+
+## Command Mapping
+
+| Intent | Workflow |
+|---|---|
+| Initialize planning | `/init` |
+| Add behavior | `/new-feature` |
+| Fix regression | `/fix-bug` |
+| Plan without implementing | `/plan` |
+| Inspect quality and drift | `/audit` |
+| Review changed files | `/review` |
+| Summarize current state | `/status` |
+
+## Readiness Gate
+
+- [ ] Intent is confirmed.
+- [ ] Required planning docs are read.
+- [ ] Local codebase evidence is recorded.
+- [ ] External research is cited or marked unavailable.
+- [ ] Impact, tests, docs, diagrams, and rollback are known.
+- [ ] Escalation risks are resolved.
+
+## Completion Gate
+
+- [ ] Verification passed.
+- [ ] Docs were synchronized or declared unnecessary.
+- [ ] Tracking files were updated.
+- [ ] Changed files were reviewed.
+- [ ] Unnecessary files, debug logs, and unrelated changes were removed.
+

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

@@ -0,0 +1,27 @@
+# AGENTS.md
+
+This repository uses the Project Genesis Harness.
+
+Before doing feature work, bug fixes, refactors, or architecture changes, read:
+
+1. `.planning/SUMMARY.md`
+2. `.planning/STATE.md`
+3. `.planning/PROJECT.md`
+4. `.planning/REQUIREMENTS.md`
+5. `.planning/STACK.md`
+6. `.planning/ARCHITECTURE.md`
+7. `.planning/CONVENTIONS.md`
+8. `.planning/PITFALLS.md`
+9. `.planning/LESSONS_LEARNED.md`
+
+For new features, create a folder under `.planning/features/`.
+For bug fixes, create a folder under `.planning/bugs/`.
+For major decisions, create an ADR under `.planning/decisions/`.
+
+Do not claim completion unless:
+
+- verification passed
+- docs were synchronized
+- task tracking was updated
+- changed files were reviewed
+

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

@@ -0,0 +1,32 @@
+# API Docs
+
+## Endpoints
+
+| Method | Path | Purpose | Auth |
+|---|---|---|---|
+| TBD | TBD | TBD | TBD |
+
+## Request Examples
+
+```json
+{}
+```
+
+## Response Examples
+
+```json
+{}
+```
+
+## Error Format
+
+TBD
+
+## Auth Requirements
+
+TBD
+
+## Versioning Rules
+
+TBD
+

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

@@ -0,0 +1,30 @@
+# Architecture
+
+## High-Level Architecture
+
+TBD
+
+## Module Boundaries
+
+- [ ] TBD
+
+## Data Flow
+
+TBD
+
+## Dependency Direction
+
+TBD
+
+## Service Boundaries
+
+TBD
+
+## System Design Principles
+
+- [ ] TBD
+
+## Forbidden Architecture Patterns
+
+- [ ] TBD
+

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

@@ -0,0 +1,26 @@
+# Audit
+
+## Scope
+
+- [ ] architecture drift
+- [ ] docs freshness
+- [ ] dead code
+- [ ] duplicated logic
+- [ ] dependency risk
+- [ ] security risk
+- [ ] missing tests
+- [ ] missing diagrams
+- [ ] stale decisions
+- [ ] stale feature tasks
+- [ ] stale phase tasks
+
+## Findings
+
+| Severity | Area | Finding | Follow-Up Task |
+|---|---|---|---|
+| TBD | TBD | TBD | TBD |
+
+## Quality Score Updates
+
+- [ ] TBD
+

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

@@ -0,0 +1,34 @@
+# Bug
+
+## Report
+
+TBD
+
+## Reproduction
+
+- [ ] TBD
+
+## Root Cause
+
+TBD
+
+## Test Contract
+
+- [ ] Regression test or verification must fail before the fix.
+- [ ] Regression test or verification must pass after the fix.
+
+## Tasks
+
+- [ ] Read PITFALLS.md
+- [ ] Read LESSONS_LEARNED.md
+- [ ] Reproduce bug
+- [ ] Identify root cause
+- [ ] Write regression test or verification
+- [ ] Fix bug
+- [ ] Run verification
+- [ ] Update LESSONS_LEARNED.md
+- [ ] Update docs if behavior changed
+- [ ] Review changed files
+- [ ] Update STATE.md
+- [ ] Update SPEC_CHANGELOG.md if needed
+

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

@@ -0,0 +1,21 @@
+# Check
+
+## Purpose
+
+TBD
+
+## Command
+
+```sh
+# TBD
+```
+
+## Pass Criteria
+
+- [ ] TBD
+
+## Failure Action
+
+- [ ] Update tracking
+- [ ] Fix issue or document escalation
+- [ ] Rerun verification

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

@@ -0,0 +1,42 @@
+# Conventions
+
+## Naming
+
+- [ ] TBD
+
+## Folders
+
+- [ ] TBD
+
+## Code Style
+
+- [ ] TBD
+
+## Error Handling
+
+- [ ] TBD
+
+## Logging
+
+- [ ] TBD
+
+## Testing
+
+- [ ] TBD
+
+## API
+
+- [ ] TBD
+
+## Security
+
+- [ ] TBD
+
+## Patterns To Follow
+
+- [ ] TBD
+
+## Patterns To Avoid
+
+- [ ] TBD
+

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

@@ -0,0 +1,33 @@
+# ADR: Title
+
+Status: Proposed
+Date:
+
+## Context
+
+TBD
+
+## Decision
+
+TBD
+
+## Alternatives Considered
+
+- [ ] TBD
+
+## Consequences
+
+- [ ] TBD
+
+## Risks
+
+- [ ] TBD
+
+## Mitigation
+
+- [ ] TBD
+
+## Verification Evidence
+
+TBD
+

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

@@ -0,0 +1,26 @@
+# Design
+
+## UX Principles
+
+- [ ] TBD
+
+## Screens / Pages
+
+- [ ] TBD
+
+## Component Conventions
+
+- [ ] TBD
+
+## State Management Rules
+
+- [ ] TBD
+
+## Accessibility Notes
+
+- [ ] TBD
+
+## Design Constraints
+
+- [ ] TBD
+

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

@@ -0,0 +1,21 @@
+# Escalation
+
+Codex must stop and ask the user when:
+
+- [!] product requirement conflicts
+- [!] security decision is ambiguous
+- [!] public API breaking change is required
+- [!] destructive database migration is required
+- [!] credentials or secrets are missing
+- [!] cost/performance tradeoff is unclear
+- [!] legal/compliance concern exists
+- [!] user intent is ambiguous
+- [!] implementation would delete user data
+- [!] implementation requires paid external service setup
+
+## Escalation Log
+
+| Date/Time | Reason | Decision Needed | Resolution |
+|---|---|---|---|
+| TBD | TBD | TBD | TBD |
+

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

@@ -0,0 +1,49 @@
+# Feature
+
+## Summary
+
+TBD
+
+## User Story
+
+As a TBD, I want TBD so that TBD.
+
+## Expected Behavior
+
+- [ ] TBD
+
+## Edge Cases
+
+- [ ] TBD
+
+## Out Of Scope
+
+- [ ] TBD
+
+## Acceptance Criteria
+
+- [ ] TBD
+
+## Tasks
+
+- [ ] Read required planning docs
+- [ ] Read PITFALLS.md
+- [ ] Read LESSONS_LEARNED.md
+- [ ] Research existing codebase patterns
+- [ ] Research best practices
+- [ ] Create or update Mermaid diagram
+- [ ] Write SPEC.md
+- [ ] Write IMPACT.md
+- [ ] Write PLAN.md
+- [ ] Write TEST_CONTRACT.md
+- [ ] Add failing tests or verification
+- [ ] Implement feature
+- [ ] Run verification
+- [ ] Update docs
+- [ ] Review changed files
+- [ ] Remove unnecessary files/code
+- [ ] Update STATE.md
+- [ ] Update FEATURE_INDEX.md
+- [ ] Update SPEC_CHANGELOG.md
+- [ ] Mark completed tasks
+

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

@@ -0,0 +1,32 @@
+# Integrations
+
+## External Services
+
+- [ ] TBD
+
+## SDKs / Packages
+
+- [ ] TBD
+
+## Environment Variables
+
+| Name | Purpose | Required | Notes |
+|---|---|---:|---|
+| TBD | TBD | TBD | TBD |
+
+## Secrets Required
+
+- [ ] TBD
+
+## Failure Handling
+
+- [ ] TBD
+
+## Fallback Behavior
+
+- [ ] TBD
+
+## Rate Limits
+
+- [ ] TBD
+

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

@@ -0,0 +1,13 @@
+# Journeys
+
+## Journey: TEMPLATE
+
+Steps:
+1. TBD
+
+Expected UI:
+Expected API calls:
+Expected DB state:
+Expected logs:
+Verification command:
+

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

@@ -0,0 +1,12 @@
+# Lessons Learned
+
+## Bug: TEMPLATE
+
+Date:
+Root cause:
+Failed assumption:
+Correct pattern:
+Prevention rule:
+Files changed:
+Verification:
+

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

@@ -0,0 +1,34 @@
+# Observability
+
+## Logs
+
+- [ ] TBD
+
+## Metrics
+
+- [ ] TBD
+
+## Traces
+
+- [ ] TBD
+
+## Error Reporting
+
+- [ ] TBD
+
+## Health Checks
+
+- [ ] TBD
+
+## Debug Commands
+
+```sh
+# TBD
+```
+
+## Local Inspection Commands
+
+```sh
+# TBD
+```
+

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

@@ -0,0 +1,34 @@
+# Phase Plan
+
+## Goal
+
+TBD
+
+## Scope
+
+- [ ] TBD
+
+## Dependencies
+
+- [ ] TBD
+
+## Tasks
+
+- [ ] Read required planning docs
+- [ ] Research codebase patterns
+- [ ] Define test contract
+- [ ] Implement planned work
+- [ ] Run verification
+- [ ] Update docs
+- [ ] Review changed files
+
+## Acceptance Criteria
+
+- [ ] TBD
+
+## Verification
+
+```sh
+# TBD
+```
+

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

@@ -0,0 +1,22 @@
+# Pitfalls
+
+## Common Mistakes
+
+- [ ] TBD
+
+## Risky Areas
+
+- [ ] TBD
+
+## Things Not To Do
+
+- [ ] TBD
+
+## Fragile Dependencies
+
+- [ ] TBD
+
+## Historical Warnings
+
+- [ ] TBD
+

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

@@ -0,0 +1,39 @@
+# Planning Tree Template
+
+```txt
+.planning/
+├── PROJECT.md
+├── REQUIREMENTS.md
+├── ROADMAP.md
+├── STATE.md
+├── STACK.md
+├── ARCHITECTURE.md
+├── DESIGN.md
+├── API_DOCS.md
+├── INTEGRATIONS.md
+├── CONVENTIONS.md
+├── PITFALLS.md
+├── LESSONS_LEARNED.md
+├── SPEC_CHANGELOG.md
+├── FEATURE_INDEX.md
+├── CHANGE_IMPACT_MATRIX.md
+├── QUALITY_SCORE.md
+├── ESCALATION.md
+├── OBSERVABILITY.md
+├── SMOKE_TESTS.md
+├── JOURNEYS.md
+├── SUMMARY.md
+├── config.json
+├── diagrams/
+├── research/
+├── decisions/
+├── phases/
+├── features/
+├── bugs/
+├── audits/
+├── checks/
+├── quick/
+├── codebase/
+└── templates/
+```
+