codex-genesis-harness 0.1.0 → 0.1.4

package/.codex/skills/genesis-research/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: research-skill
+description: Run local and external research for Codex harness decisions with source attribution, repository evidence, assumptions, and reusable research notes. Use before adopting APIs, SDKs, architecture patterns, or uncertain implementation approaches.
+---
+
+# Research Skill
+
+## Purpose
+Ground decisions in repository evidence and current authoritative sources.
+
+## When to use
+Use when facts may be stale, external APIs are involved, or implementation direction is uncertain.
+
+## When NOT to use
+Do not use when local code already answers the question and no external fact is needed.
+
+## Inputs required
+Research question, decision needed, local files, external source constraints, and acceptance criteria.
+
+## Outputs required
+Research note with local evidence, external citations, recommendation, rejected options, and follow-up tests.
+
+## Required tests
+Translate research into failing tests or contract checks before implementation.
+
+## Required fixtures
+Create fixtures for researched API examples or edge cases.
+
+## Required contract updates
+Update contracts if research changes public behavior or schemas.
+
+## Required codebase map updates
+Update memory files with durable conclusions and source dates.
+
+## Token saving rules
+Search targeted files first; summarize sources and avoid pasting long excerpts.
+
+## Acceptance criteria
+Decision is supported by evidence and converted into testable work.
+
+## Common mistakes
+Researching broadly without a decision, trusting stale docs, and failing to encode findings in tests.
+
+## Recovery workflow
+If research conflicts, prefer primary sources, document uncertainty, and choose the smallest reversible test.
+

package/.codex/skills/genesis-research/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Research Skill"
+  short_description: "Ground harness decisions in evidence"
+  default_prompt: "Use $research-skill to gather evidence before choosing an implementation path."
+policy:
+  allow_implicit_invocation: true
+

package/.codex/skills/genesis-research/checklists/checklist.md

@@ -0,0 +1,7 @@
+# Research Checklist
+
+- [ ] Local evidence checked.
+- [ ] Primary sources used.
+- [ ] Recommendation testable.
+- [ ] Memory updated.
+

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

@@ -0,0 +1,4 @@
+# Example
+
+Research a provider SDK version, capture official docs, then create a contract fixture for the expected response.
+

package/.codex/skills/genesis-research/templates/research-note-template.md

@@ -0,0 +1,9 @@
+# Research Note Template
+
+## Question
+## Local Evidence
+## External Evidence
+## Recommendation
+## Rejected Options
+## Tests To Add
+

package/.codex/skills/genesis-research-first/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: genesis-research-first
+description: Auto-enforce research-first pattern - automatically research documentation, best practices, and GitHub before any important decision. Research output feeds directly into planning. Triggered automatically for features, bugs, architecture changes, and spec updates.
+---
+
+# Genesis Research-First (Auto-Enforce)
+
+## Purpose
+
+**Eliminate guesswork by auto-researching before planning.**
+
+This skill enforces a strict research-first pattern:
+
+```
+User Request
+  → [AUTO] Research Phase
+    → Read local documentation
+    → Search GitHub for best practices
+    → Check official package/framework docs
+    → Review existing codebase patterns
+  → [AUTO] Compile Research Note
+  → [AUTO] Generate Planning Artifact
+  → User Reviews & Confirms
+  → Planning Proceeds
+```
+
+**Not optional. Automatic.**
+
+## When Auto-Triggered
+
+Auto-trigger on these task types:
+
+- `/init` - Project initialization
+- `/new-feature` - Feature work
+- `/fix-bug` - Bug fixes
+- `/spec-change` - Architecture or API changes
+- `/architecture` - System design decisions
+- `/design` - UI/UX changes
+- `/plan` - Planning from scratch
+- `/upgrade` - Major upgrades or refactoring
+
+## Research Scope
+
+For each task, research covers:
+
+### 1. Local Documentation (5 min)
+```
+Check files:
+  - .codebase/CURRENT_STATE.md
+  - .codebase/DOMAIN_MODELS.md
+  - .codebase/MODULE_INDEX.md
+  - contracts/ (relevant)
+  - README.EN.md / README.VI.md
+  - .instructions.md
+  - CONTRIBUTING.md
+```
+
+### 2. Codebase Patterns (5 min)
+```
+Search for:
+  - Similar features already implemented
+  - Existing patterns (test fixtures, error handling, etc.)
+  - Related modules and dependencies
+  - Previous decisions (in memory files)
+```
+
+### 3. External Best Practices (5-10 min)
+```
+Research:
+  - Official docs (Node.js, React, framework, etc.)
+  - GitHub repositories (top 3 with similar feature)
+  - Stack Overflow (if question is specific)
+  - Framework/library GitHub Issues (for known issues)
+```
+
+### 4. Compile Research Note
+```
+Format:
+  - Question: What are we deciding?
+  - Local Evidence: What does codebase show?
+  - External Evidence: What do best practices say?
+  - Recommendation: Based on evidence, what's best?
+  - Risks: What could go wrong?
+  - Next Steps: What to verify?
+```
+
+## Output
+
+Each research produces:
+
+1. **Research Note** (saved to `.planning/RESEARCH_NOTES/`)
+   - Format: `RESEARCH_[TASK_ID]_[DATE].md`
+   - Required: Question, local evidence, external evidence, recommendation, risks
+
+2. **Compiled Plan** (passed to `genesis-planning` automatically)
+   - Pre-populated with research findings
+   - Pre-populated with existing patterns
+   - Pre-populated with risk/constraint list
+
+## Token Saving Rules
+
+- Read summaries before source files (use .codebase summaries)
+- Target searches: Search for specific pattern, not broad topics
+- Avoid pasting: Cite sources with line numbers, not full excerpts
+- Trust cache: If recently researched, skip re-research
+- Parallel: Run local + external research in parallel
+
+## Acceptance Criteria
+
+Research is complete when:
+
+- [ ] Local documentation reviewed
+- [ ] Codebase patterns identified
+- [ ] 3+ external sources checked
+- [ ] Research note compiled with recommendation
+- [ ] Risks and constraints documented
+- [ ] Plan passed to `genesis-planning` with research context
+
+## Common Mistakes
+
+- **Skipping local docs** - Wastes time researching what's already documented
+- **Broad searches** - "How to build features" instead of "GraphQL subscriptions in Node.js"
+- **Trusting stale docs** - Check issue date and GitHub activity
+- **Forgetting to cite** - Always include source, date, and confidence level
+- **Over-researching** - 15 min max per task (diminishing returns)
+
+## Recovery Workflow
+
+If research is inconclusive:
+
+1. Identify the **primary source of uncertainty**
+2. Research that ONE thing deeper (docs, GitHub issues, etc.)
+3. If still unclear, document assumptions and ask user
+4. Proceed with smallest reversible test
+
+## Example: Feature Research
+
+### User Request
+```
+/new-feature "Add real-time notifications with WebSocket"
+```
+
+### Auto-Research Output
+
+**RESEARCH_WEBSOCKET_2026-05-31.md**:
+```markdown
+# Research: WebSocket Implementation
+
+## Question
+What's the best way to add real-time notifications with WebSocket?
+
+## Local Evidence
+- Codebase uses Express.js (Node.js server)
+- Already uses Socket.io for chat (see: src/modules/chat/)
+- Test pattern: fixtures + integration tests
+- Error handling: try/catch + structured logging
+
+## External Evidence
+1. Socket.io docs recommend pub/sub pattern for scaling
+2. GitHub trending (express-websocket): 2k+ stars
+3. Best practice: Use Socket.io adapter for multi-server scaling
+
+## Recommendation
+Extend existing Socket.io setup (already familiar to team, reduces learning)
+Add namespace: /notifications
+Use Redis adapter for multi-server support
+
+## Risks
+- Single point of failure if Redis goes down
+- Learning curve for team on Redis adapter (mitigated by docs)
+
+## Next Steps
+1. Check existing Socket.io configuration
+2. Verify Redis availability
+3. Create test fixtures for notification flow
+```
+
+### Auto-Generated Plan
+```
+**Phase 1: Socket.io Namespace Setup**
+- Extend existing Socket.io (pattern: src/modules/chat/)
+- Create /notifications namespace
+- Add Redis adapter
+
+**Phase 2: Authentication**
+- Verify user can only receive own notifications
+- Add auth middleware
+
+**Phase 3: Notification Flow**
+- Create API endpoint to trigger notification
+- Add test fixtures
+- Integration tests
+
+**Risks from Research**:
+- Redis dependency must be available
+- Handle redis down gracefully
+```
+
+## Installation
+
+Installed with Genesis Codex Harness by default.
+
+```bash
+npm install -g codex-genesis-harness@latest
+```
+
+## Commands
+
+```bash
+# Explicitly trigger research (optional - auto-triggers for /init, /new-feature, etc.)
+/research "WebSocket real-time notifications"
+
+# View research notes
+cd .planning/RESEARCH_NOTES/
+ls *.md | sort -r | head
+```
+
+## For Developers: How It Works
+
+This skill runs as a **PreToolUse hook** in `.instructions.md`:
+
+```yaml
+PreToolUse:
+  - IF: task_type in [init, new-feature, fix-bug, spec-change, architecture, design, plan, upgrade]
+    THEN:
+      1. Load research prompt template
+      2. Run research (local docs + codebase + GitHub)
+      3. Compile research note
+      4. Generate initial plan from research
+      5. Pass to user for review
+```
+
+**No code generated until research complete.**
+
+---
+
+**Genesis Research-First** | Enforce best-practice research workflow | v1.0

package/.codex/skills/genesis-research-first/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Research First Skill"
+  short_description: "Auto-enforce research-first pattern before any important technical decision"
+  default_prompt: "Use $genesis-research-first to research documentation, best practices, and existing patterns before planning this feature."
+
+policy:
+  allow_implicit_invocation: true

package/.codex/skills/genesis-research-first/examples/example.md

@@ -0,0 +1,85 @@
+# Example: Auto-Research Before Implementing WebSocket Notifications
+
+## Scenario
+
+A developer requests a new real-time notification feature using WebSocket. Before any planning begins, genesis-research-first auto-triggers to gather evidence.
+
+## Trigger (Auto)
+
+```
+/new-feature "Add real-time notifications with WebSocket"
+```
+
+genesis-research-first activates automatically as a PreToolUse hook.
+
+## Research Phase (15 min total)
+
+### Local Documentation (5 min)
+
+```
+Checked:
+  ✓ .codebase/CURRENT_STATE.md — Stack: Express.js + Node.js 20
+  ✓ .codebase/MODULE_INDEX.md  — Found: src/modules/chat/ uses Socket.io
+  ✓ .codebase/ARCHITECTURE.md  — Single-server currently, Redis available
+  ✓ contracts/api/             — No existing WebSocket contracts
+```
+
+### Codebase Patterns (5 min)
+
+```
+Found:
+  ✓ src/modules/chat/ — Existing Socket.io v4 setup
+  ✓ tests/integration/chat.test.ts — Integration test pattern
+  ✓ fixtures/agents/ — Socket.io fixture template available
+```
+
+### External Best Practices (5 min)
+
+```
+Researched:
+  ✓ Socket.io docs — Namespace pattern recommended for feature isolation
+  ✓ GitHub: socket.io-redis-adapter — 8k stars, maintained
+  ✓ Stack Overflow — Scaling Socket.io: Redis pub/sub required for multi-server
+```
+
+## Research Note Compiled
+
+**`RESEARCH_WEBSOCKET_2026-05-31.md`**:
+
+```markdown
+# Research: WebSocket Real-Time Notifications
+
+## Question
+Best implementation for real-time notifications?
+
+## Local Evidence
+- Codebase already uses Socket.io for chat (src/modules/chat/)
+- Redis is available in infrastructure
+
+## External Evidence
+1. Socket.io namespace pattern isolates features well
+2. socket.io-redis-adapter enables multi-server scaling
+
+## Recommendation
+Extend existing Socket.io setup with /notifications namespace + Redis adapter.
+
+## Risks
+- Redis single point of failure (mitigate: graceful degradation)
+- Learning curve: Redis adapter config (mitigate: docs available)
+```
+
+## Auto-Generated Plan
+
+```
+Phase 1: Socket.io /notifications namespace (pattern: src/modules/chat/)
+Phase 2: Redis adapter setup + auth middleware
+Phase 3: Notification trigger API endpoint
+Phase 4: Integration tests + fixtures
+```
+
+## Outcome
+
+- ✅ Research complete in 15 min (no guesswork)
+- ✅ Existing patterns reused (no reinvention)
+- ✅ Risks documented upfront
+- ✅ Plan passed to genesis-planning with research context