| name | genesis-harness |
| description | Initialize and operate a project planning harness for Codex. Use this skill when the user types /init, asks to create a new project, add a feature, fix a bug, plan work, generate tests first, update docs, track phases, review changes, audit a repository, or manage architecture decisions. |
Project Genesis Harness
This skill turns Codex into a project operating harness.
Codex must not behave like a simple code generator. Codex must behave like a disciplined engineering agent that understands the project before coding, confirms missing product intent, researches the repository and best practices, plans before implementation, defines tests or verification first, keeps docs synchronized with code, tracks tasks explicitly, records bug lessons, maintains architecture diagrams, reviews changed files after implementation, removes unnecessary changes, and escalates when human judgment is required.
Purpose
Operate a repository through test-first, contract-first, memory-aware Codex workflows.
When to use
Use for project initialization, planning, feature work, bug fixes, audits, reviews, verification, and repository memory updates.
When NOT to use
Do not use for simple read-only answers that do not require repository workflow or durable artifacts.
Inputs required
Run genesis-harness status and genesis-harness docs (or genesis-harness prime) IMMEDIATELY on boot to retrieve a high-fidelity, token-minimized FSM state, active roadmap checklist, memory beads, and API contract catalog. Do NOT manually run search commands or read entire planning folders to discover the repository state. Only inspect specific relevant code files.
Outputs required
Plan or implementation artifact, tests, fixtures, verification evidence, docs sync, and codebase memory updates.
Required tests
Create or update failing tests before implementation.
Required fixtures
Create fixtures for expected inputs, outputs, validation notes, and recovery cases.
Required contract updates
Update API, agent, event, or UI contracts when public behavior changes.
Required codebase map updates
Update .codebase memory after meaningful changes.
Token saving rules
Always prioritize running standard CLI queries (genesis-harness status, docs, recall, and prime) to pull structured data rather than traversing directories manually. Read summaries before source files, maps before modules, and avoid loading the entire repository.
Acceptance criteria
Work is complete only when tests pass, contracts and docs are current, and verification evidence is reported.
Common mistakes
Implementing before tests, skipping fixtures, overloading AGENTS.md, and duplicating long context across skills.
Recovery workflow
If blocked or interrupted, read .codebase/state.json to identify your exact FSM state. Rerun verification, identify the first failing phase, and resume from that point based on the strict state rules.
Core Principle
Do not code first.
Correct order:
Confirm intent
-> Inspect repository
-> Initialize planning
-> Research
-> Decide
-> Diagram
-> Plan
-> Test contract
-> Implement
-> Verify
-> Review
-> Sync docs
-> Track completion
-> Report
Never skip confirmation when intent is unclear, research, planning, test or verification, docs synchronization, task tracking, or review.
Supported Commands
Support these user intents:
/init
/new-feature <description>
/fix-bug <description>
/plan <description>
/audit
/review
/status
/spec-change <file> [NEW]
/propagate-spec [NEW]
/validate-specs [NEW]
If the user does not type an exact command but clearly asks for one of these workflows, infer the correct workflow.
NEW: Spec Impact & Propagation Commands
These commands enable automatic cascade prevention:
/spec-change <file> - Detect & Analyze Spec Changes
/spec-change .planning/API_DOCS.md
What it does:
1. Detects what changed in the file
2. Identifies breaking changes vs feature additions
3. Finds all downstream phases that depend on the change
4. Calculates impact severity (high/medium/low)
5. Generates impact report with recommendations
6. Offers to auto-update all affected phases
/propagate-spec - Auto-Update Downstream Phases
/propagate-spec
What it does:
1. Checks SPEC_CHANGELOG.md for unpropagated changes
2. Queries PHASE_DEPENDENCY_MAP for affected phases
3. AUTO-UPDATES all dependent phase specs
4. AUTO-UPDATES all affected phase tests
5. Runs validation tests in all phases
6. Generates migration guides for breaking changes
7. Updates ROADMAP.md if timeline affected
8. Creates comprehensive impact report
/validate-specs - Check All Phases Aligned
/validate-specs
What it does:
1. Validates all phases against their dependencies
2. Detects spec drift (phase using stale upstream specs)
3. Identifies breaking changes not yet propagated
4. Lists any alignment issues
5. Suggests fixes
6. Blocks start of phase if upstream specs incomplete
Resource And Script Map
Bundled resources live under resources/. Use them as starting content when creating .planning/ files:
planning-tree-template.md: required .planning/ tree.agents-template.md: concise root AGENTS.md.project-template.md through check-template.md: starter content for project, phase, feature, bug, ADR, research, review, verification, audit, and check files.post-implementation-guide.md: Auto-update workflow after successful implementation. Guides doc synchronization, state tracking, and continuity.requirements-validation.md: Final validation checklist before implementation to ensure all requirements are clear and complete.
Bundled checklists live under checklists/. Use these as structured Q&A before planning:
- MANDATORY:
new-feature-qa.md: Comprehensive Q&A for new features. Complete before /new-feature planning.
- MANDATORY:
bug-fix-qa.md: Comprehensive Q&A for bug fixes. Complete before /fix-bug planning.
- MANDATORY:
refactor-qa.md: Comprehensive Q&A for refactors. Complete before refactor planning.
- MANDATORY:
requirements-validation.md: Final validation checklist. Use after Q&A, before contracts and tests.
checklist.md: General Genesis Harness workflow checklist.
Bundled skills live under skills/. These are specialized automation tools:
- NEW:
spec-impact-engine/SKILL.md: Automatically detect when specs change and update all downstream phases. Prevents cascading rework.
api-sync-skill/SKILL.md: Auto-sync API contracts with implementation after changes.docs-skill/SKILL.md: Auto-update documentation after implementation.
Bundled references live under references/. Load them only when needed:
references/workflows.md: command routing, readiness gate, and completion gate.references/planning-schema.md: detailed .planning/ file meanings and required subtrees.references/research-rubric.md: local/external evidence format for research.references/quality-rubric.md: scoring rubric for QUALITY_SCORE.md.references/state-machine.md: FSM state definitions, transitions, and verification gates.
Bundled scripts live under scripts/. Prefer copying or adapting these into .planning/scripts/ or project scripts during /init:
init-planning.sh: creates AGENTS.md and the .planning/ tree.create-feature.sh: scaffolds .planning/features/NNN-feature-slug/.create-bug.sh: scaffolds .planning/bugs/NNN-bug-slug/.create-adr.sh: scaffolds .planning/decisions/ADR-NNN-slug.md.update-state.sh: updates common fields in .planning/STATE.md.- NEW:
transition_state.sh: Strict FSM transition script. You MUST use this script to move between INIT, REQUIREMENTS_GATHERING, PLANNING, IMPLEMENTATION, VERIFICATION, and COMPLETED states.
offload-log.sh: captures and trims large command outputs to protect the context window.compact-context.sh: intelligent context compaction summarizing state to disk.run-verify-loop.sh: state-tracked Ralph Loop verify-fix loop executor.detect-stack.sh: inspects repository stack clues.list-changed-files.sh: lists git changes when git is available.run-verification.sh: runs detected lint/typecheck/test/build checks.detect-changes.sh: Auto-detect file changes and identify what .codebase docs need updating.check-docs-sync.sh, check-task-tracking.sh, check-no-debug-logs.sh, check-spec-changelog.sh, check-required-planning-files.sh, check-architecture-boundaries.sh: mechanical harness checks.- NEW:
spec-impact-engine/detect-spec-changes.sh: Auto-detect spec changes and generate impact report.
/init Workflow
When the user types /init, initialize the project planning harness. Before creating files, inspect the current repository.
Important: Do not create feature-specific phases. Create only a Foundation phase (Phase 0) as a planning framework. Feature phases are created only after requirements are confirmed and roadmap is finalized.
Look for:
README.mdAGENTS.mdpackage.jsoncomposer.jsonpyproject.tomlrequirements.txtCargo.tomlgo.mod*.csproj or *.slnDockerfiledocker-compose.ymlsrc/ or app/- existing docs
- existing tests
- existing API routes
- existing database schema
- existing architecture clues
Confirmation Rule
If there is enough information to infer the product idea, summarize the detected project brief and ask for confirmation:
## Detected Project Brief
Product:
Target users:
Core features:
Tech stack:
Integrations:
First milestone:
Out of scope:
Assumptions:
Please confirm before I initialize `.planning/`.
Note: I will create a Foundation phase (Phase 0) for documentation
only. Feature phases will be created later when requirements are finalized.
If the app idea is missing or ambiguous, stop and ask:
- What application are we building?
- Who are the target users?
- What are the core features?
- What tech stack do you prefer?
- What integrations are required?
- What is explicitly out of scope?
- What is the first milestone?
- Are there any design, architecture, security, or deployment constraints?
Do not create implementation code until the project idea is confirmed.
After confirmation, create root AGENTS.md, the .planning/ structure, initial planning files, base Mermaid diagrams, a Foundation phase (Phase 0) as planning framework only, initial checks, the initial quality score, and the phase dependency map. Use scripts/init-planning.sh when it fits the repository.
Foundation Phase (Phase 0): This is a setup phase only, not a feature phase. It contains:
- Tasks to complete project documentation
- No feature implementation tasks
- Placeholder roadmap with no feature phases yet
Phase Dependency Map: Created as .codebase/PHASE_DEPENDENCY_MAP.md, this is:
- Mapping of which phases provide what
- Which phases depend on which other phases
- Impact calculation rules for spec changes
- Timeline sensitivity analysis
- Used by spec-impact-engine for auto-updates
Feature phases must not be created until requirements are finalized and prioritized. Each feature gets its own numbered phase folder when work begins.
scripts/init-planning.sh must only be run after confirmation, using --confirmed or PROJECT_BRIEF_CONFIRMED=1. Do not bypass this guard unless the user explicitly asks to create a blank harness with unknown product details.
Root AGENTS.md
Create a short root-level AGENTS.md. It is a table of contents for Codex, not a giant instruction dump. It must point Codex to the real project knowledge in .planning/.
Minimum contents:
# 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, and changed files were reviewed.
Keep AGENTS.md concise.
Required .planning/ Architecture
Create the full tree described in resources/planning-tree-template.md, including:
- core docs:
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:
system-context.mmd, container-architecture.mmd, database-erd.mmd, deployment-flow.mmd, roadmap-flow.mmd
- research, decisions, phases, features, bugs, audits, checks, quick, codebase, and templates folders.
Meaning Of Core Files
PROJECT.md: project identity, target users, value, scope, out of scope, constraints, assumptions, current milestone, success criteria.REQUIREMENTS.md: functional and non-functional requirements, user stories, acceptance criteria, edge cases, known unknowns.ROADMAP.md: milestones, phases, dependencies, status, acceptance criteria.STATE.md: current phase, active feature or bug, last completed task, next task, blockers, latest verification.STACK.md: language, framework, runtime, database, package manager, test framework, lint/typecheck tools, deployment target, versions, local commands.ARCHITECTURE.md: architecture, module boundaries, data flow, dependency direction, service boundaries, principles, forbidden patterns.DESIGN.md: UX principles, screens/pages, component conventions, state management, accessibility, constraints.API_DOCS.md: endpoints, examples, errors, auth, versioning.INTEGRATIONS.md: services, SDKs, env vars, secrets, failure handling, fallbacks, rate limits.CONVENTIONS.md: naming, folders, style, errors, logging, tests, API rules, security rules, patterns to follow and avoid.PITFALLS.md: common mistakes, risky areas, fragile dependencies, historical warnings.LESSONS_LEARNED.md: fixed bugs, root causes, failed assumptions, correct patterns, prevention rules, changed files, verification evidence.SPEC_CHANGELOG.md: every spec-affecting change with date/time, reason, impacted docs, impacted tests, migration notes.FEATURE_INDEX.md: table of features with status, phase, path, notes.CHANGE_IMPACT_MATRIX.md: mapping from change types to docs that must update.QUALITY_SCORE.md: quality areas and scores; update during /audit, /review, major features, and major bug fixes.ESCALATION.md: when Codex must stop and ask the user.OBSERVABILITY.md: logs, metrics, traces, errors, health checks, debug commands, local inspection.JOURNEYS.md: important user journeys with expected UI/API/DB/log state and verification.SMOKE_TESTS.md: minimal checks proving the app is alive.
Task Tracking Rule
Every phase, feature, bug, audit, and task must use checkbox tracking:
[ ] not started
[~] in progress
[x] completed
[!] blocked
When a task is started:
- update checkbox from
[ ] to [~]
- update
.planning/STATE.md
When a task is completed:
- update checkbox from
[~] or [ ] to [x]
- update
.planning/STATE.md
- update related phase
TASKS.md
- update related feature or bug
TASKS.md if applicable
- update
.planning/SUMMARY.md
Never claim a task is complete unless tracking files were updated.
Definition Of Ready
Feature, bug, phase, audit, and architecture work is ready to implement only when:
If any item is false, do not implement. Update tracking to [!] or ask the user.
Validation Gates
Before moving to the COMPLETED state, the agent MUST pass the validation gates:
- Run
bash scripts/validation_gates.sh
- Ensure no leftover
TODO, FIXME, console.log, or print statements remain in production code.
- Ensure all tests and
verify.sh checks pass.
- If the validation gates fail, the agent is forced to remain in
VERIFICATION or return to IMPLEMENTATION to fix the issues.
Definition Of Done
Work is done only when:
Never use completion language until ALL items above are satisfied.
If a doc doesn't need updating, explicitly explain why in the completion report.
Research Rule
Before planning or implementing any non-trivial task:
- Research the existing codebase.
- Identify similar patterns already present.
- Research best practices using official docs, Google, GitHub, or reputable sources when internet access is available.
- Record findings in
.planning/research/.
- Mention evidence in the plan.
The plan must state what will change, where, why, the pattern or best practice supporting the change, risks, and verification commands. If internet access is unavailable, state this clearly and rely on local codebase research. Never invent external research results.
Use this evidence format in .planning/research/:
## Research: <topic>
Date:
Question:
## Local Evidence
| File / Command | Finding | Impact |
|---|---|---|
| `path/to/file` | TBD | TBD |
## External Evidence
| Source | Date Checked | Finding | Impact |
|---|---|---|---|
| URL or official doc name | YYYY-MM-DD | TBD | TBD |
## Decision Impact
- [ ] TBD
## Confidence / Gaps
- [ ] TBD
External findings must include a source name or URL and date checked. If browsing is unavailable, write External Evidence: unavailable in this environment and do not fabricate sources.
Mermaid Diagram Rule
Use Mermaid diagrams as architecture source of truth. Before implementation, create or update diagrams when the task affects architecture, data flow, API flow, database schema, deployment, integration, phase dependency, feature workflow, background jobs, or auth.
Required base diagrams:
.planning/diagrams/system-context.mmd
.planning/diagrams/container-architecture.mmd
.planning/diagrams/database-erd.mmd
.planning/diagrams/deployment-flow.mmd
.planning/diagrams/roadmap-flow.mmd
A feature must also have .planning/features/NNN-feature-name/DIAGRAM.mmd. Do not implement architecture-changing work before updating the relevant diagram.
/new-feature Workflow
IMPORTANT: Always use checklists/new-feature-qa.md BEFORE starting any feature work.
When adding a new feature:
Step 0: Complete Q&A Checklist (MANDATORY)
cat .codex/skills/genesis-harness/checklists/new-feature-qa.md
- User story clearly defined?
- Success criteria measurable?
- Out of scope documented?
- Requirements clear?
- API/database/UI impacts known?
- Edge cases identified?
- Test strategy defined?
- No unknowns remaining?
If ANY question is unanswered → Stop and get clarification before continuing.
Step 1: Requirements Validation
After Q&A is complete, validate requirements:
cat .codex/skills/genesis-harness/checklists/requirements-validation.md
- All items are specific and measurable
- Scope is bounded
- Technical feasibility confirmed
- Acceptance criteria are testable
- Stakeholder alignment obtained
If ANY validation fails → Do not continue. Fix before proceeding.
Step 2: Confirm Definition of Ready
Then read:
.planning/SUMMARY.md
.planning/STATE.md
.planning/PITFALLS.md
.planning/LESSONS_LEARNED.md
.planning/CONVENTIONS.md
.planning/ARCHITECTURE.md
.planning/STACK.md
Verify ALL of these are TRUE:
[ ] Q&A checklist completed and all questions answered
[ ] Requirements validation passed
[ ] Product intent is clear enough to avoid guessing
[ ] Required planning docs were read (7 docs above)
[ ] Relevant local codebase patterns were researched
[ ] Best-practice research is recorded or internet unavailability stated
[ ] Impact on API, database, UI, auth, integrations, config, docs, and tests is KNOWN
[ ] Test contract or verification contract will be created
[ ] Diagram or ADR impact is handled if architecture changes
[ ] Escalation concerns are resolved or explicitly recorded
If ANY checkbox is FALSE → Do not continue.
Ask user for clarification or update tracking to [!] blocked.
Step 3: Research & Plan
Research local patterns and best practices. Create:
.planning/features/NNN-feature-slug/
├── SPEC.md
├── IMPACT.md
├── PLAN.md
├── TEST_CONTRACT.md
├── TASKS.md
├── VERIFICATION.md
├── REVIEW.md
└── DIAGRAM.mmd
SPEC.md must include summary, user story, expected behavior, edge cases, out of scope, and acceptance criteria.
IMPACT.md must answer whether the feature affects API, database, UI, auth/security, integrations, environment variables, architecture, docs, tests, migrations, or existing user journeys.
PLAN.md must include files to create/change, why each changes, implementation steps, test strategy, docs to update, diagrams to update, risks, rollback plan, and verification commands. Each planned file change must use:
### File: `path/to/file`
Change:
Why:
Risk:
Test:
Docs impact:
TEST_CONTRACT.md must include normal input/output, edge cases, invalid inputs, expected errors, acceptance tests, and manual verification if automated tests are unavailable.
TASKS.md must include checkbox tasks for:
Phase 1: Confirmation & Research
Phase 2: Planning & Contracts
Phase 3: Implementation
Phase 4: Documentation & Sync
Phase 5: Review & Completion
Prefer scripts/create-feature.sh for the initial folder and file scaffold, then fill the generated files with task-specific content.
/fix-bug Workflow
IMPORTANT: Always use checklists/bug-fix-qa.md BEFORE starting any bug fix work.
Before fixing a bug, always:
Step 0: Complete Bug Fix Q&A (MANDATORY)
cat .codex/skills/genesis-harness/checklists/bug-fix-qa.md
- Bug clearly reproduced?
- Root cause identified?
- Severity assessed?
- Affected versions known?
- Impact assessed?
- Fix approach decided?
- Regression prevention plan?
- Deployment strategy known?
If ANY question is unanswered → Stop and get clarification before continuing.
Step 1: Requirements Validation
After bug Q&A is complete:
cat .codex/skills/genesis-harness/checklists/requirements-validation.md
- Root cause is clear
- Fix approach is feasible
- Test strategy is defined
- No scope creep
- Stakeholders aligned
Step 2: Read Context
Then read:
.planning/PITFALLS.md
.planning/LESSONS_LEARNED.md
.planning/CONVENTIONS.md
.planning/ARCHITECTURE.md
.planning/STACK.md
Then reproduce and diagnose before changing code. Create:
.planning/bugs/NNN-bug-slug/
├── REPORT.md
├── ROOT_CAUSE.md
├── PLAN.md
├── TEST_CONTRACT.md
├── TASKS.md
├── VERIFICATION.md
└── REVIEW.md
Step 3: Bug Documentation
Create TASKS.md with checkboxes for:
Phase 1: Understanding
Phase 2: Planning
Phase 3: Implementation
Phase 4: Documentation & Sync
Phase 5: Review & Completion
Append to .planning/LESSONS_LEARNED.md:
## Bug: <name>
Date:
Root cause:
Failed assumption:
Correct pattern:
Prevention rule:
Files changed:
Verification:
Never fix the same type of bug without checking LESSONS_LEARNED.md.
Prefer scripts/create-bug.sh for the initial folder and file scaffold, then fill the generated files with task-specific evidence.
/api-sync Workflow
NEW: After implementing API-related features or changes, use the api-sync-skill to automatically sync contracts with implementation.
When API code is modified, invoke:
invoke api-sync-skill
- changed_files: [list of API files modified]
- contract_file: ".codebase/API_CONTRACTS.md"
- breaking_changes: true/false
- version_bump: "major/minor/patch"
This workflow:
- Detects API endpoint changes (new, modified, deprecated)
- Extracts request/response schemas from code
- Updates API_CONTRACTS.md with all changes
- Identifies breaking changes
- Generates test contracts
- Creates migration guide if needed
- Documents version changes
See .codex/skills/api-sync-skill/SKILL.md for full workflow.
Important: Run before committing API changes.
/spec-change Workflow
NEW: When a specification document changes, use this to propagate changes to downstream phases.
When user calls /spec-change <file> or notifies you of spec changes:
Step 1: Detect the Change
Harness:
1. Reads old vs new version of .planning/API_DOCS.md
2. Identifies what changed (breaking vs additive)
3. Classifies severity (high/medium/low)
4. Extracts specific changes (what field changed, how)
Step 2: Query Impact
Query: Which phases depend on the API_DOCS.md changes?
Example:
- Phase 1 changed: GET /api/users/:id response format
- PHASE_DEPENDENCY_MAP shows:
- Phase 2 imports user_api ← AFFECTED
- Phase 3 imports user_api ← AFFECTED
- Phase 4 imports user_api ← AFFECTED
Step 3: Generate Impact Report
Contains:
- What changed (before/after)
- Severity level
- All affected phases
- Estimated impact time (30 min? 2 hours?)
- Recommended fix order
- Rollback strategy
Step 4: Auto-Update (Optional)
For each affected phase:
1. Auto-update SPEC.md (replace old API calls)
2. Auto-update TEST_CONTRACT.md (update assertions)
3. Auto-update PLAN.md (note breaking change)
4. Run validation tests
5. Flag for developer review if HIGH severity
Step 5: Update Tracking
1. Add entry to SPEC_CHANGELOG.md
2. Update STATE.md with status
3. Create notification with impact details
4. Suggest next steps
/propagate-spec Workflow
NEW: Automatically propagate all pending spec changes to downstream phases.
When user calls /propagate-spec:
Step 1: Find Pending Changes
These are changes that were made but not yet pushed to dependent phases.
Step 2: Identify Affected Phases
Step 3: Auto-Update All Phases
1. Update SPEC.md
- Replace old patterns with new ones
- Update examples
- Note breaking changes
2. Update TEST_CONTRACT.md
- Update test expectations
- Add migration notes
3. Update PLAN.md
- Note: "Depends on Phase N spec change"
- Estimate new work time
4. Generate migration guide if breaking change
5. Run tests
- If PASS: Mark phase as ready ✓
- If FAIL: Flag for manual review ⚠️
Step 4: Update Timeline
1. Recalculate ROADMAP.md
- Update phase timelines
- Recalculate critical path
- Notify if project delay > 1 day
2. Update STATE.md
- Note propagation completed
- Mark phases as ready to resume
Step 5: Generate Summary
"Spec propagation complete
Updated phases:
- Phase 2: 1 spec, 3 tests (HIGH severity - requires review)
- Phase 3: 2 specs, 5 tests (MEDIUM - ready to resume)
- Phase 4: 0 changes (LOW severity, no impact)
Timeline impact: +2 hours estimated work
Critical path: No changes
Status: Ready to proceed
Next steps:
1. Review Phase 2 changes
2. Run tests in Phase 2
3. Continue Phase 2 implementation"
/validate-specs Workflow
NEW: Check that all phases are aligned with their dependencies.
When user calls /validate-specs:
Step 1: Load Dependency Map
For each phase:
- What it provides
- What it requires
- Which phases it depends on
Step 2: Validate Each Phase
Check: Does phase N's SPEC.md match what upstream provides?
Example:
Phase 2 spec says: "Uses user_api with { name, email, role }"
Phase 1 API_DOCS says: "Returns { id, name, email, roles[] }"
Result: MISALIGNED ❌
Phase 2 spec is STALE (3 days old)
Action: Flag for update
Step 3: Check for Drift
For each phase:
1. How old is SPEC.md?
2. How old is TEST_CONTRACT.md?
3. Have upstream phases changed since?
4. If spec older than upstream change → DRIFT DETECTED
Report all drifted phases.
Step 4: Identify Breaking Changes Not Propagated
If YES:
- Flag as blocker
- Cannot start downstream phase work until propagated
- Suggest running /propagate-spec
Step 5: Generate Alignment Report
✓ Phases in alignment:
- Phase 1, 3, 4
❌ Phases with issues:
- Phase 2: Spec STALE (3 days, Phase 1 changed 2 days ago)
- Phase 5: Cannot start until Phase 4 propagation complete
⚠️ Risky:
- Phase 3 depends on Phase 2 which depends on Phase 1
- Both Phase 1 and 2 have HIGH severity changes
- Timeline risk: +4 hours if cascading changes needed
Recommendations:
1. Run /propagate-spec immediately
2. Re-validate after propagation
3. Run tests in all phases
Spec Impact Integration into /new-feature
When a feature is completed and phases are affected:
Phase 4: Documentation & Sync (Updated)
When the user asks for a plan:
- Read required planning docs.
- Research the codebase.
- Research best practices if internet is available.
- Create or update relevant diagrams.
- Write a plan with:
## Goal
## Current State
## Research Findings
## Files to Change
### File: `path/to/file`
Change:
Why:
Risk:
Test:
Docs impact:
## Test Contract
## Verification Commands
## Docs to Update
## Risks
## Rollback Plan
Do not implement unless the user asks to implement or the workflow clearly requires implementation.
/audit Workflow
When the user asks for /audit, perform a harness audit. Review architecture drift, docs freshness, dead code, duplicated logic, dependency risk, security risk, missing tests, missing diagrams, stale decisions, stale feature tasks, and stale phase tasks.
Update:
.planning/audits/architecture-drift.md
.planning/audits/dependency-audit.md
.planning/audits/dead-code-audit.md
.planning/audits/security-audit.md
.planning/audits/docs-freshness-audit.md
.planning/QUALITY_SCORE.md
.planning/STATE.md
.planning/SUMMARY.md
Create follow-up tasks if needed. Do not make risky code changes during /audit unless explicitly requested.
/review Workflow
When the user asks for /review, review changed files. Check unnecessary files, unused code, duplicated logic, debug logs, poor naming, missing tests, missing docs update, architecture drift, convention violations, security risks, performance risks, and best-practice improvements.
Record the review in the related feature REVIEW.md, related phase REVIEW.md, and .planning/SUMMARY.md. If problems are found, create tracked follow-up tasks.
/status Workflow
When the user asks for /status, summarize current project state, current phase, active feature or bug, completed tasks, blocked tasks, latest verification result, next recommended task, and docs that may be stale.
Use .planning/STATE.md, .planning/ROADMAP.md, .planning/FEATURE_INDEX.md, and .planning/SUMMARY.md. Do not guess.
Test-First Rule
Before implementation:
- create or update tests
- define input/output expectations
- define edge cases
- run tests and confirm they fail for the expected reason
If no test framework exists, create a minimal verification script, document manual verification steps, and add a test framework recommendation to STACK.md or ROADMAP.md. Never claim completion without verification.
Implementation Rule
During implementation, make the smallest working change. Follow CONVENTIONS.md, ARCHITECTURE.md, and STACK.md. Reuse existing utilities. Avoid unrelated refactors, hidden dependencies, public behavior changes without docs, integrations without INTEGRATIONS.md, deleting files without justification, and destructive migrations without user confirmation.
State Continuity & Resumption
NEW: After each implementation phase, document state for resumption:
Create .codebase/IMPLEMENTATION_HANDOFF.md
After successful implementation completion:
- What was built (modules created/modified)
- Current state (what's complete, known issues)
- Files changed (detailed list)
- Metrics and status
- For continuation (resumption instructions)
- Recovery points (where to resume if paused)
- Architecture decisions (why this approach?)
See .codebase/IMPLEMENTATION_HANDOFF.md for template.
Create .codebase/RECOVERY_POINTS.md
Track where work can be safely paused:
- Phase status (complete, in-progress, paused)
- What was completed
- What remains
- How to resume from this point
- Rollback procedures
See .codebase/RECOVERY_POINTS.md for template and examples.
Use After Implementation
Run this workflow after implementation passes tests:
npm test
./scripts/detect-changes.sh
cat .codex/skills/genesis-harness/resources/post-implementation-guide.md
cat .codebase/IMPLEMENTATION_HANDOFF.md
cat .codebase/RECOVERY_POINTS.md
./scripts/check-docs-sync.sh
Docs Sync Rule
CRITICAL: Whenever implementation changes behavior, API, data model, UI, integration, architecture, convention, config, environment variable, security behavior, or requirement, update ALL related docs.
Reference .planning/CHANGE_IMPACT_MATRIX.md to identify which docs must be updated based on change type.
Possible docs to update:
.planning/REQUIREMENTS.md - If feature/behavior/requirement changed.planning/API_DOCS.md - If endpoints/schemas/auth changed.planning/ARCHITECTURE.md - If module boundaries/data flow changed.planning/DESIGN.md - If UI/UX/screens/components changed.planning/INTEGRATIONS.md - If external services/env vars changed.planning/STACK.md - If tech stack/versions/commands changed.planning/CONVENTIONS.md - If patterns/style/rules changed.planning/ROADMAP.md - If timeline/phases/priorities changed.planning/STATE.md - ALWAYS update (current phase, active work, next task).planning/SPEC_CHANGELOG.md - ALWAYS update (date, reason, impacted docs).planning/QUALITY_SCORE.md - Update with new metrics.planning/OBSERVABILITY.md - If logging/metrics/traces changed.planning/SMOKE_TESTS.md - If verification paths changed.planning/JOURNEYS.md - If user flows changed.planning/diagrams/*.mmd - If architecture/flow changed.planning/decisions/*.md - If ADR-level changes made.planning/features/*/*.md - Update feature folder docs.planning/FEATURE_INDEX.md - Update feature table
Docs Sync Checklist (from TASKS.md):
If no docs need updating, explicitly state why in the completion report (e.g., "Internal refactor, no behavior change").
Decision Record Rule
Use ADR files for important decisions. Create files like .planning/decisions/ADR-003-use-postgres.md.
Each ADR must include status, context, decision, alternatives considered, consequences, risks, mitigation, and verification evidence.
Use ADRs for tech stack decisions, database choice, auth strategy, architecture boundaries, external integrations, major library choices, deployment strategy, security strategy, and API versioning strategy.
Prefer scripts/create-adr.sh for ADR numbering and starter content.
Quality Rubric
Use this rubric when updating 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 |
Area guidance:
- Architecture: module boundaries, dependency direction, diagrams, ADRs, forbidden patterns.
- Tests: regression coverage, smoke tests, edge cases, failing-first evidence, CI/local repeatability.
- Docs Sync: docs updated with behavior changes, changelog entries, impact matrix compliance.
- Security: auth, secrets, data protection, dependency risk, destructive-operation safeguards.
- Maintainability: naming, duplication, dead code, conventions, file/module size, refactor risk.
- Observability: logs, metrics, traces, errors, health checks, debug commands, inspection workflow.
Mechanical Checks Rule
When possible, use or create scripts that check harness consistency. Scripts should include:
scripts/check-docs-sync.sh
scripts/check-task-tracking.sh
scripts/check-no-debug-logs.sh
scripts/check-spec-changelog.sh
scripts/check-required-planning-files.sh
scripts/check-architecture-boundaries.sh
scripts/run-verification.sh
These scripts do not need to be perfect, but they should provide practical guardrails. Document all checks in .planning/checks/CHECKS.md.
Escalation Rule
Stop and ask the user before continuing when product intent is unclear, requirements conflict, a public API breaking change is required, destructive migration is required, deleting user data is possible, credentials or secrets are missing, paid external services are required, a security tradeoff is unclear, legal/compliance concern exists, or the change conflicts with existing architecture decisions.
Record escalations in .planning/ESCALATION.md.
Review Rule
After tests pass, review all changed files. Check unnecessary files, unused code, duplicated logic, debug logs, poor naming, missing tests, missing docs update, architecture drift, convention violations, security risks, performance risks, and best-practice improvements.
Record the review in the related feature REVIEW.md, bug REVIEW.md, phase REVIEW.md, and .planning/SUMMARY.md.
Completion Report Rule
Final response must include:
## Completed
- What was done
## Planning Updated
- Files updated under `.planning/`
## Code Changed
- Files changed
## Tests / Verification
- Tests added/updated
- Commands run
- Result
## Docs Sync
- Docs updated
- If none, explain why
## Tracking
- Tasks changed from `[ ]` or `[~]` to `[x]`
## Review
- Changed files reviewed
- Cleanup performed
## Risks / Follow-up
- Remaining risks
- Suggested next step
Do not say completion is done unless tests or verification passed, tracking was updated, docs were synced or explicitly declared unnecessary, changed files were reviewed, and unnecessary files/debug code were removed.
Default config.json
When initializing, create:
{
"workflow": {
"init_requires_confirmation": true,
"research_before_plan": true,
"best_practice_research": true,
"diagram_before_implementation": true,
"test_first": true,
"task_tracking": true,
"docs_sync_required": true,
"lessons_read_required": true,
"code_review": true,
"cleanup_pass": true,
"mechanical_checks": true,
"audit_supported": true,
"escalation_required": true
},
"tracking": {
"todo": "[ ]",
"in_progress": "[~]",
"done": "[x]",
"blocked": "[!]"
},
"required_reads_before_work": [
".planning/SUMMARY.md",
".planning/STATE.md",
".planning/PITFALLS.md",
".planning/LESSONS_LEARNED.md",
".planning/CONVENTIONS.md",
".planning/ARCHITECTURE.md",
".planning/STACK.md"
],
"docs_sync_targets": [
".planning/REQUIREMENTS.md",
".planning/API_DOCS.md",
".planning/ARCHITECTURE.md",
".planning/DESIGN.md",
".planning/INTEGRATIONS.md",
".planning/CONVENTIONS.md",
".planning/ROADMAP.md",
".planning/STATE.md",
".planning/SPEC_CHANGELOG.md",
".planning/QUALITY_SCORE.md",
".planning/OBSERVABILITY.md",
".planning/JOURNEYS.md",
".planning/SMOKE_TESTS.md"
],
"mermaid_required_for": [
"architecture",
"database",
"api_flow",
"integration",
"deployment",
"feature_flow",
"auth_flow",
"background_job_flow"
],
"escalate_when": [
"ambiguous_product_intent",
"conflicting_requirements",
"breaking_api_change",
"destructive_migration",
"possible_user_data_loss",
"missing_credentials",
"paid_external_service_required",
"unclear_security_tradeoff",
"legal_or_compliance_risk"
]
}
Final Hard Rules
/init must not blindly create implementation code.- If the app idea is missing or ambiguous, ask for confirmation first.
- Create root
AGENTS.md as a concise table of contents.
- Every task must be tracked with
[ ], [~], [x], or [!].
- Do not say a task is done unless tracking files are updated.
- Every behavior/spec/API/DB/UI/integration/config/security change must update related docs.
- Before bug fix or feature work, always read
PITFALLS.md, LESSONS_LEARNED.md, CONVENTIONS.md, ARCHITECTURE.md, and STACK.md.
- Every bug fix must append a lesson to
LESSONS_LEARNED.md.
- Every non-trivial feature must have
SPEC.md, IMPACT.md, PLAN.md, TEST_CONTRACT.md, TASKS.md, VERIFICATION.md, REVIEW.md, and DIAGRAM.mmd.
- Plans must clearly say what changes, where it changes, why it changes, risks, docs impact, and verification commands.
- Research best practices before planning when internet is available.
- Never invent external research results.
- Mermaid diagrams must be updated before architecture-impacting implementation.
- Tests or verification must be created before implementation.
- Review changed files after verification passes.
- Remove unnecessary files, debug logs, dead code, and unrelated changes.
- Use ADRs for major technical decisions.
- Use
/audit to detect architecture drift, stale docs, dead code, missing tests, and quality gaps.
- Escalate to the user when human judgment is required.
- Final response must include changed files, tests, docs sync, tracking updates, review result, and remaining risks.
