codex-genesis-harness 0.1.0 → 0.1.4

package/.codex/skills/genesis-harness/checklists/requirements-validation.md

@@ -0,0 +1,211 @@
+# Requirements Validation Checklist
+
+**Purpose**: Validate that all requirements are clear, complete, and aligned before implementation starts.
+
+**Status**: MANDATORY - Use after Q&A, before creating contracts and tests.
+
+## Completeness Check
+
+- [ ] **All Q&A items answered**:
+  - No "TBD" fields remaining?
+  - No "Unknown" fields that can be resolved?
+  - All dependencies documented?
+
+- [ ] **Requirements are Specific**:
+  - "User can upload file" → ✅ "User can upload JPEG/PNG < 5MB to profile"
+  - Vague requirements identified and clarified?
+  - Units and formats specified (MB, seconds, JSON)?
+
+- [ ] **Requirements are Measurable**:
+  - Success can be verified objectively?
+  - Metrics and thresholds defined?
+  - Acceptance criteria quantified where possible?
+
+- [ ] **Requirements are Achievable**:
+  - Technical team believes it's feasible?
+  - Skills and knowledge present?
+  - Resource constraints acknowledged?
+  - Timeline realistic?
+
+- [ ] **Requirements are Relevant**:
+  - Aligned with product roadmap?
+  - Business value clear?
+  - Won't be made obsolete by other work?
+
+## Scope Validation
+
+- [ ] **Scope is bounded**:
+  - Clear IN/OUT distinction?
+  - Related features NOT in scope documented?
+  - Phase 2/future work identified?
+
+- [ ] **No scope creep identified**:
+  - Requirements are focused?
+  - "Nice to have" separated from "must have"?
+  - Dependencies on other features noted?
+
+- [ ] **Edge cases included in scope**:
+  - Error cases considered?
+  - Boundary conditions documented?
+  - Performance edge cases noted?
+
+## Technical Feasibility
+
+- [ ] **Technical approach approved**:
+  - Architect reviewed proposed solution?
+  - Major technical decisions documented?
+  - No unknowns that are blockers?
+
+- [ ] **API/Contract defined**:
+  - Input schema clear?
+  - Output schema clear?
+  - Error responses defined?
+  - Breaking changes identified?
+
+- [ ] **Data Model defined**:
+  - Database schema changes clear?
+  - Backward compatibility strategy defined?
+  - Data migration plan if needed?
+
+- [ ] **Dependencies external/internal identified**:
+  - External APIs or services needed?
+  - Libraries or tools required?
+  - Existing modules to integrate with?
+  - Build/deployment requirements?
+
+## Acceptance Criteria Validation
+
+- [ ] **Acceptance Criteria are testable**:
+  - Each criterion can be verified?
+  - Test cases can be written?
+  - No subjective criteria ("looks good")?
+
+- [ ] **Acceptance Criteria are complete**:
+  - Happy path covered?
+  - Error paths included?
+  - Edge cases represented?
+  - Performance criteria included?
+
+- [ ] **Acceptance Criteria are prioritized**:
+  - Must-have criteria clear?
+  - Nice-to-have criteria separate?
+  - Dependencies between criteria noted?
+
+## Stakeholder Alignment
+
+- [ ] **Product owner approved**:
+  - Requirements match product vision?
+  - Business value documented?
+  - Conflicts with other priorities resolved?
+
+- [ ] **Tech lead/architect approved**:
+  - Technical feasibility confirmed?
+  - Approach aligns with architecture?
+  - Technical risks identified?
+
+- [ ] **No conflicting requirements**:
+  - Performance vs. complexity tradeoffs addressed?
+  - Security vs. usability resolved?
+  - Team capacity confirmed?
+
+## Documentation & Communication
+
+- [ ] **Requirements documented clearly**:
+  - User stories well-formed?
+  - Acceptance criteria listed?
+  - Related documents linked?
+
+- [ ] **Ambiguities resolved**:
+  - Team discussed unclear points?
+  - Assumptions documented?
+  - Glossary for domain terms created?
+
+- [ ] **Team has common understanding**:
+  - Walkthrough with key people done?
+  - Q&A items captured in writing?
+  - No silent disagreements about scope?
+
+## Risk Assessment
+
+- [ ] **Technical risks identified**:
+  - Unknown technologies or patterns?
+  - Performance risks documented?
+  - Integration risks noted?
+
+- [ ] **Business risks identified**:
+  - Dependencies on external parties?
+  - Market timing risks?
+  - Competitive concerns?
+
+- [ ] **Mitigation strategies defined**:
+  - Risk reduction tactics identified?
+  - Contingency plans for critical risks?
+  - Escalation criteria defined?
+
+## Testing & Quality
+
+- [ ] **Test Strategy defined**:
+  - Unit test scope?
+  - Integration test scenarios?
+  - E2E test critical paths?
+  - Performance test requirements?
+
+- [ ] **Test Data & Fixtures planned**:
+  - What data needed for testing?
+  - Edge case datasets created?
+  - Load test scenarios defined?
+
+- [ ] **Quality Standards aligned**:
+  - Code review criteria?
+  - Test coverage target (80%+)?
+  - Performance benchmarks?
+  - Security standards?
+
+## Sign-Off
+
+- [ ] **Product Owner**: _Name_ ☐ Approved
+- [ ] **Tech Lead**: _Name_ ☐ Approved  
+- [ ] **Team Lead**: _Name_ ☐ Approved
+- [ ] **Any additional stakeholders**: ☐ Approved
+
+## Implementation Readiness
+
+### Ready to Proceed:
+- [ ] All Q&A complete
+- [ ] All validations passed
+- [ ] All stakeholders approved
+- [ ] No blockers identified
+- [ ] Team ready to start
+
+### If NOT ready:
+- [ ] List items preventing readiness
+- [ ] Owner assigned for each blocker
+- [ ] Timeline to resolve each blocker
+
+---
+
+## Usage
+
+```
+After completing feature/bug/refactor Q&A:
+
+1. Run through this validation checklist
+2. Address any gaps or concerns
+3. Get sign-offs from stakeholders
+4. Only then proceed to:
+   - Contract definition
+   - Test creation
+   - Implementation planning
+```
+
+## Validation Result
+
+**Status**: ☐ Ready / ☐ Needs Work
+
+**Blockers** (if any):
+- _item_
+- _item_
+
+**Owner**: _Name_  
+**Date**: _YYYY-MM-DD_  
+**Next Steps**: _Action items_

package/.codex/skills/genesis-harness/examples/example.md

@@ -0,0 +1,4 @@
+# Example
+
+Use `$genesis-harness` to initialize planning, create a feature folder, define tests first, verify, and update `.codebase`.
+

package/.codex/skills/genesis-harness/resources/change-impact-matrix-template.md

@@ -0,0 +1,204 @@
+# Change Impact Matrix
+
+**What docs must be updated when different types of changes are made.**
+
+Use this matrix to identify all docs that need updating for your feature/bug fix.
+
+## Feature: Behavior Changed
+
+**You changed**:
+- User-facing behavior
+- Acceptance criteria
+- Requirement fulfilled
+
+**Update these docs**:
+- [ ] `.planning/REQUIREMENTS.md` - Document new requirement
+- [ ] `.planning/SPEC_CHANGELOG.md` - Record the change
+- [ ] `.planning/STATE.md` - Update current status
+- [ ] `.planning/SUMMARY.md` - Recent changes
+- [ ] `.planning/FEATURE_INDEX.md` - Feature status
+- [ ] `.planning/QUALITY_SCORE.md` - Recalculate coverage
+
+---
+
+## Feature: API Changed
+
+**You changed**:
+- New endpoints
+- Request/response schemas
+- Auth mechanism
+- Error responses
+- Breaking changes
+
+**Update these docs**:
+- [ ] `.planning/API_DOCS.md` - Document new/changed endpoints
+- [ ] `.planning/REQUIREMENTS.md` - Behavior changes
+- [ ] `.planning/INTEGRATIONS.md` - If auth/secrets changed
+- [ ] `.planning/SPEC_CHANGELOG.md` - Record API changes with migration notes
+- [ ] `.planning/STATE.md` - Current phase
+- [ ] `.planning/SUMMARY.md` - Recent changes
+- [ ] `.planning/FEATURE_INDEX.md` - Feature status
+- [ ] `.planning/QUALITY_SCORE.md` - Recalculate API coverage
+
+---
+
+## Feature: Database Changed
+
+**You changed**:
+- New tables/collections
+- Schema modifications
+- Data migrations
+- Queries/indexes
+
+**Update these docs**:
+- [ ] `.planning/ARCHITECTURE.md` - New data models/schema
+- [ ] `.planning/diagrams/database-erd.mmd` - Update ERD
+- [ ] `.planning/SPEC_CHANGELOG.md` - Record schema changes with migration steps
+- [ ] `.planning/STATE.md` - Current phase
+- [ ] `.planning/SUMMARY.md` - Recent changes
+- [ ] `.planning/QUALITY_SCORE.md` - Recalculate architecture coverage
+
+---
+
+## Feature: UI/UX Changed
+
+**You changed**:
+- New screens/pages
+- Component structure
+- User flows
+- Navigation
+- Accessibility
+
+**Update these docs**:
+- [ ] `.planning/DESIGN.md` - New screens/components/flow
+- [ ] `.planning/JOURNEYS.md` - Updated user journeys
+- [ ] `.planning/SMOKE_TESTS.md` - New verification paths
+- [ ] `.planning/diagrams/system-context.mmd` - If flows changed
+- [ ] `.planning/SPEC_CHANGELOG.md` - Record UI changes
+- [ ] `.planning/STATE.md` - Current phase
+- [ ] `.planning/SUMMARY.md` - Recent changes
+- [ ] `.planning/FEATURE_INDEX.md` - Feature status
+- [ ] `.planning/QUALITY_SCORE.md` - Recalculate design coverage
+
+---
+
+## Feature: Architecture Changed
+
+**You changed**:
+- Module boundaries
+- Service structure
+- Dependency direction
+- Data flow
+- Design patterns
+
+**Update these docs**:
+- [ ] `.planning/ARCHITECTURE.md` - New module boundaries, patterns, principles
+- [ ] `.planning/diagrams/container-architecture.mmd` - Update architecture diagram
+- [ ] `.planning/diagrams/deployment-flow.mmd` - If deployment changed
+- [ ] `.planning/CONVENTIONS.md` - New patterns to follow
+- [ ] `.planning/decisions/ADR-XXX-*.md` - Create ADR for major decision
+- [ ] `.planning/SPEC_CHANGELOG.md` - Record architecture changes
+- [ ] `.planning/STATE.md` - Current phase
+- [ ] `.planning/SUMMARY.md` - Recent changes
+- [ ] `.planning/QUALITY_SCORE.md` - Recalculate architecture score
+
+---
+
+## Feature: Integration Changed
+
+**You changed**:
+- New external services
+- API keys/secrets
+- Webhooks
+- Rate limits
+- Fallback strategies
+
+**Update these docs**:
+- [ ] `.planning/INTEGRATIONS.md` - New services, env vars, failure handling
+- [ ] `.planning/STACK.md` - New dependencies
+- [ ] `.planning/OBSERVABILITY.md` - New error handling/logs
+- [ ] `.planning/SPEC_CHANGELOG.md` - Record integration changes
+- [ ] `.planning/STATE.md` - Current phase
+- [ ] `.planning/SUMMARY.md` - Recent changes
+- [ ] `.planning/QUALITY_SCORE.md` - Recalculate integration coverage
+
+---
+
+## Feature: Configuration/Environment Changed
+
+**You changed**:
+- New env variables
+- Config files
+- Build process
+- Runtime environment
+- Deployment parameters
+
+**Update these docs**:
+- [ ] `.planning/STACK.md` - New commands, env vars, versions
+- [ ] `.planning/INTEGRATIONS.md` - New secrets/config
+- [ ] `.planning/CONVENTIONS.md` - New rules
+- [ ] `.planning/diagrams/deployment-flow.mmd` - If deployment changed
+- [ ] `.planning/SPEC_CHANGELOG.md` - Record config changes
+- [ ] `.planning/STATE.md` - Current phase
+- [ ] `.planning/SUMMARY.md` - Recent changes
+- [ ] `.planning/QUALITY_SCORE.md` - Recalculate coverage
+
+---
+
+## Bug Fix: Behavior Corrected
+
+**You fixed**:
+- Incorrect behavior
+- Edge case handling
+- Error recovery
+
+**Update these docs**:
+- [ ] `.planning/LESSONS_LEARNED.md` - Document root cause, prevention
+- [ ] `.planning/SPEC_CHANGELOG.md` - Record fix
+- [ ] `.planning/PITFALLS.md` - Add prevention rule if applicable
+- [ ] `.planning/STATE.md` - Current phase
+- [ ] `.planning/SUMMARY.md` - Recent changes
+- [ ] `.planning/QUALITY_SCORE.md` - Recalculate
+
+---
+
+## Refactor: No Behavior Change
+
+**You changed**:
+- Internal code organization
+- Performance optimization
+- Dependency updates
+- Code cleanup
+
+**Update these docs**:
+- [ ] `.planning/ARCHITECTURE.md` - If structure clarified
+- [ ] `.planning/CONVENTIONS.md` - If patterns improved
+- [ ] `.planning/LESSONS_LEARNED.md` - Document why refactor needed
+- [ ] `.planning/STATE.md` - Current phase
+- [ ] `.planning/SUMMARY.md` - Recent changes
+- [ ] `.planning/QUALITY_SCORE.md` - Recalculate maintainability
+
+---
+
+## Always Update
+
+**Regardless of change type, ALWAYS update:**
+
+- [ ] `.planning/STATE.md` - current phase, active feature, next task
+- [ ] `.planning/SUMMARY.md` - recent changes, next recommended task
+- [ ] `.planning/SPEC_CHANGELOG.md` - date, reason, impacted docs, migration notes
+- [ ] `.planning/FEATURE_INDEX.md` or `.planning/bugs/` - status update
+
+**Exception**: Internal refactor with zero behavior change can skip SPEC_CHANGELOG if justified.
+
+---
+
+## How to Use This Matrix
+
+1. **Identify change type** above (Feature: API Changed? Bug Fix? etc.)
+2. **Check all boxes** that apply
+3. **Update each doc** listed
+4. **Verify** with checklist in Definition of Done
+5. **Add to SPEC_CHANGELOG.md** as final proof
+
+**If you forget to update a doc**: Spec drift → future bugs → technical debt → expensive rewrites.

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

@@ -0,0 +1,131 @@
+# Foundation Phase (Phase 0)
+
+## Overview
+
+Phase 0 is a setup phase only. Its purpose is to complete project documentation and establish the planning framework.
+
+**This phase contains NO feature implementation tasks.**
+
+Feature phases (Phase 1, 2, 3...) are created later only after:
+- Requirements are finalized
+- Product roadmap is confirmed
+- Prioritization is decided
+
+## Goal
+
+Establish complete project documentation, confirm product intent, and prepare for feature development.
+
+## Scope
+
+- [x] Detect and extract project information
+- [ ] Complete PROJECT.md with confirmed details
+- [ ] Document all REQUIREMENTS.md
+- [ ] Define ARCHITECTURE.md based on codebase inspection
+- [ ] Document STACK.md (languages, frameworks, tools)
+- [ ] Define CONVENTIONS.md (coding patterns, style)
+- [ ] Document INTEGRATIONS.md (if any)
+- [ ] Create API_DOCS.md structure
+- [ ] Establish PITFALLS.md warnings
+- [ ] Create base Mermaid diagrams
+- [ ] Create initial QUALITY_SCORE.md
+- [ ] Verify harness is functional
+
+## Tasks
+
+### Read & Confirm
+
+- [ ] Read `.planning/PROJECT.md`
+- [ ] Confirm product intent is clear
+- [ ] Identify any missing requirements
+
+### Document & Refine
+
+- [ ] Complete `.planning/REQUIREMENTS.md` with functional & non-functional reqs
+- [ ] Document `.planning/ARCHITECTURE.md` from codebase inspection
+- [ ] Complete `.planning/STACK.md` with full tech details
+- [ ] Document `.planning/CONVENTIONS.md` from existing code patterns
+- [ ] Identify pitfalls and document in `.planning/PITFALLS.md`
+
+### Diagrams & References
+
+- [ ] Create `.planning/diagrams/system-context.mmd`
+- [ ] Create `.planning/diagrams/container-architecture.mmd`
+- [ ] Create `.planning/diagrams/database-erd.mmd` (if applicable)
+- [ ] Create `.planning/diagrams/deployment-flow.mmd`
+
+### Quality & Verification
+
+- [ ] Initial QUALITY_SCORE.md (document current state)
+- [ ] Verify `.planning/` structure is complete
+- [ ] Verify all core docs have content (not just TBD)
+- [ ] Run any existing tests/builds to verify health
+
+## Dependencies
+
+None. Phase 0 is the foundation.
+
+## Acceptance Criteria
+
+- [x] `.planning/` structure created
+- [ ] PROJECT.md completed with confirmed product brief
+- [ ] REQUIREMENTS.md lists all known requirements
+- [ ] STACK.md documents all tech details
+- [ ] ARCHITECTURE.md describes system design
+- [ ] Diagrams are created and reasonably accurate
+- [ ] CONVENTIONS.md documents local patterns
+- [ ] No "TBD" remains in critical docs (PROJECT, REQUIREMENTS, STACK, ARCHITECTURE)
+- [ ] Team/user confirms they understand the roadmap and agree with scope
+- [ ] All verification checks pass
+
+## Verification
+
+```sh
+# Check structure exists
+ls -la .planning/phases/00-foundation/
+ls -la .planning/*.md
+ls -la .planning/diagrams/*.mmd
+
+# Verify no critical TBDs remain
+grep -l "TBD" .planning/PROJECT.md .planning/REQUIREMENTS.md .planning/STACK.md .planning/ARCHITECTURE.md || echo "✓ No TBDs in critical docs"
+
+# Run any project-specific verification
+# npm test
+# yarn lint
+# python -m pytest
+```
+
+## Next Phase
+
+After Foundation phase completes:
+
+1. Create Phase 1 for first priority feature/milestone
+2. Each phase gets its own numbered folder (01-feature-name, 02-feature-name, etc.)
+3. Create feature-specific plans in `.planning/features/` as work begins
+
+---
+
+## Phase 0 vs Feature Phases
+
+**Phase 0 (Foundation):**
+- Documentation & setup
+- No feature work
+- Establishes framework
+- All docs defined but empty
+
+**Phase 1+ (Features):**
+- Implement specific features
+- Contain implementation tasks
+- Follow Foundation as blueprint
+- Created when requirements are clear
+
+---
+
+## Why No Feature Phases Initially?
+
+We don't know what users need until we:
+1. Complete requirements
+2. Research existing patterns
+3. Validate assumptions
+4. Prioritize work
+
+Phase 0 ensures we document existing state before planning future features.

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

@@ -0,0 +1,76 @@
+# Phase 0: Foundation
+
+## Goal
+
+Complete project documentation, validate product intent, and establish the planning framework. **No feature implementation in this phase.**
+
+## Scope
+
+Documentation only:
+- [ ] Confirm PROJECT.md details
+- [ ] Complete REQUIREMENTS.md
+- [ ] Document ARCHITECTURE.md
+- [ ] Document STACK.md
+- [ ] Define CONVENTIONS.md
+- [ ] Create base diagrams
+- [ ] Establish baseline quality score
+
+## Dependencies
+
+None. This is the foundation.
+
+## Tasks
+
+- [ ] Read `.planning/PROJECT.md` - confirm product intent
+- [ ] Read `.planning/REQUIREMENTS.md` - validate requirements
+- [ ] Complete STACK.md with all tech details and versions
+- [ ] Document ARCHITECTURE.md from codebase analysis
+- [ ] Extract CONVENTIONS.md from existing code patterns
+- [ ] Identify and document PITFALLS.md
+- [ ] Create system-context.mmd diagram
+- [ ] Create container-architecture.mmd diagram
+- [ ] Create database-erd.mmd (if applicable)
+- [ ] Create deployment-flow.mmd diagram
+- [ ] Create initial QUALITY_SCORE.md
+- [ ] Verify all `.planning/` structure exists
+- [ ] Run project verification (tests, builds, etc.)
+- [ ] Document decision: "Phase 0 complete, ready for Phase 1 planning"
+
+## Acceptance Criteria
+
+- [x] `.planning/` directory structure created
+- [ ] PROJECT.md completed with product details
+- [ ] REQUIREMENTS.md documented
+- [ ] STACK.md has all tech versions
+- [ ] ARCHITECTURE.md describes system boundaries
+- [ ] Diagrams are created
+- [ ] No critical TBDs remain in core docs
+- [ ] Team confirms understanding of project scope
+- [ ] All verification checks pass
+
+## Verification
+
+```sh
+# Verify structure
+test -d .planning/phases/00-foundation && echo "✓ Phase folder exists"
+
+# Check core docs are not just TBD
+for file in PROJECT REQUIREMENTS STACK ARCHITECTURE CONVENTIONS; do
+  if grep -q "^## " .planning/$file.md && ! grep -q "TBD$" .planning/$file.md; then
+    echo "✓ .planning/$file.md has content"
+  fi
+done
+
+# List all diagrams
+ls -la .planning/diagrams/*.mmd | wc -l
+```
+
+## Risk & Rollback
+
+**Risk**: Documentation may be incomplete or inaccurate.
+
+**Rollback**: This is a documentation phase. If docs need revision, simply edit the `.planning/*.md` files directly. No code changes to rollback.
+
+## Notes
+
+This phase is setup only. Feature phases start in Phase 1 after Foundation is complete and requirements are confirmed.