EvoZeus-Development
Development work must keep EvoZeus small, reviewable, and evidence-backed. One PR should have one primary purpose, one primary layer, and one validation story.
The EvoZeus main repo is Protocol-only. Runtime implementation, scanner execution, CLI/TUI, companion, ~/.evozeus local state, lockfile, SQLite ledger, and report execution belong in evozeus-runtime, not this repo. The old main-repo runtime prototype has been removed from this repo; use the runtime repo for implementation work and the main repo only for protocol, governance, registry pointer, or routing changes.
Branch Rule
Use this branch format:
codex/<type>/<yyyymmdd>-<component>-<summary>
Allowed type:
| Type |
Use for |
dev |
New protocol-supporting script or product behavior in this repo; runtime implementation belongs in evozeus-runtime |
bug |
Defect fix with reproduction or evidence |
refactor |
Behavior-preserving restructuring tied to an issue or maintainer request |
docs |
Documentation, templates, governance text, or skill docs |
test |
Test coverage tied to a behavior, Case, or bug |
chore |
Maintenance that does not change user-visible behavior |
Allowed component should match the touched surface where possible: factor, verdict-card, docs, governance, skill, registry, or template. Use runtime, doctor, tui, companion, workspace, or infra only for migration coordination or protocol/trust-policy text; implementation PRs go to evozeus-runtime.
Examples:
codex/docs/20260616-skill-scenario-routing
codex/docs/20260616-runtime-routing-boundary
codex/bug/20260616-runtime-report-id
Scope Rule
Pick one primary layer:
| Layer |
Typical files |
| Semantic |
docs/reference/, terminology, ontology, evidence grading |
| Execution |
Runtime implementation belongs in evozeus-runtime; this repo should only contain protocol-supporting scripts or migration notes |
| Governance |
SKILL.md, skills/, .github/, CONTRIBUTING.md, docs/governance/, PR checks |
Do not mix Candidate content, runtime code, and governance changes in one PR unless it is a maintainer-approved migration and the PR states why a cross-layer change is necessary. New runtime code should be opened against evozeus-runtime.
Naming Rule
- User-facing local scenario skill names must start with
EvoZeus-; keep frontmatter name and folder paths lowercase evozeus-* to pass skill validation.
- Reuse project terms from
../../../docs/governance/terminology-glossary.md and ../../../docs/reference/ontology.md.
- Prefer canonical names such as
Session, Evidence, Case, Verdict, Artifact, Candidate, Factor, Pattern, Rejected Pattern, and Environment Rule.
- New variables, filenames, headings, schemas, and CLI flags should make the layer and artifact kind obvious.
- Do not introduce synonyms for established project terms unless the terminology glossary is updated in the same governance PR.
High-Risk Surfaces
These require explicit evidence and maintainer-level attention:
SKILL.md
skills/
.github/ templates or workflows
scripts/github/
SECURITY.md
schemas/
candidates/core/
candidates/reviewed/
docs/governance/privacy-and-redaction.md
docs/reference/ontology.md
docs/reference/evidence-grading.md
- future schema, redaction, upload, session ingestion, or candidate extraction code
- any change that reintroduces runtime implementation into this repo instead of using
evozeus-runtime
Pre-Submit Gate
Before staging or pushing, run the checks that match the change:
python3 scripts/check_pr_ready.py --base <base-ref>
git diff --check
For this repository, docs and governance-only work should at minimum pass:
python3 -m py_compile scripts/check_pr_ready.py
python3 scripts/check_pr_ready.py --base <base-ref>
git diff --check
If issue templates changed, also parse .github/ISSUE_TEMPLATE/*.yml with a YAML parser available in the local environment.
PR Template
Use the closest template:
| Work |
Template |
| Default or mixed docs/governance |
../../../.github/PULL_REQUEST_TEMPLATE.md |
| Candidate, Case, Pattern, Factor, or Artifact |
../../../.github/PULL_REQUEST_TEMPLATE/candidate_submission.md |
| Protocol-supporting script or behavior in this repo |
../../../.github/PULL_REQUEST_TEMPLATE/code_change.md |
| Runtime, CLI, TUI, companion, scanner execution, local state, or report execution |
Open PR in evozeus-runtime |
| Ontology, schema, protocol, compatibility |
../../../.github/PULL_REQUEST_TEMPLATE/schema_change.md |
SKILL.md, skills/, prompts, or agent instructions |
../../../.github/PULL_REQUEST_TEMPLATE/skill_instruction_change.md |
1---2name: evozeus-development3description: Use when developing EvoZeus protocol/governance itself, changing repository files, branch structure, PR templates, docs, scripts, governance, or agent-facing instructions.4metadata:5 source: https://skillmd.com/skills/metainflow/evozeus-development6---78# EvoZeus-Development910Development work must keep EvoZeus small, reviewable, and evidence-backed. One PR should have one primary purpose, one primary layer, and one validation story.1112The `EvoZeus` main repo is Protocol-only. Runtime implementation, scanner execution, CLI/TUI, companion, `~/.evozeus` local state, lockfile, SQLite ledger, and report execution belong in `evozeus-runtime`, not this repo. The old main-repo runtime prototype has been removed from this repo; use the runtime repo for implementation work and the main repo only for protocol, governance, registry pointer, or routing changes.1314## Branch Rule1516Use this branch format:1718```text19codex/<type>/<yyyymmdd>-<component>-<summary>20```2122Allowed `type`:2324| Type | Use for |25| --- | --- |26| `dev` | New protocol-supporting script or product behavior in this repo; runtime implementation belongs in `evozeus-runtime` |27| `bug` | Defect fix with reproduction or evidence |28| `refactor` | Behavior-preserving restructuring tied to an issue or maintainer request |29| `docs` | Documentation, templates, governance text, or skill docs |30| `test` | Test coverage tied to a behavior, Case, or bug |31| `chore` | Maintenance that does not change user-visible behavior |3233Allowed `component` should match the touched surface where possible: `factor`, `verdict-card`, `docs`, `governance`, `skill`, `registry`, or `template`. Use `runtime`, `doctor`, `tui`, `companion`, `workspace`, or `infra` only for migration coordination or protocol/trust-policy text; implementation PRs go to `evozeus-runtime`.3435Examples:3637```text38codex/docs/20260616-skill-scenario-routing39codex/docs/20260616-runtime-routing-boundary40codex/bug/20260616-runtime-report-id41```4243## Scope Rule4445Pick one primary layer:4647| Layer | Typical files |48| --- | --- |49| Semantic | `docs/reference/`, terminology, ontology, evidence grading |50| Execution | Runtime implementation belongs in `evozeus-runtime`; this repo should only contain protocol-supporting scripts or migration notes |51| Governance | `SKILL.md`, `skills/`, `.github/`, `CONTRIBUTING.md`, `docs/governance/`, PR checks |5253Do not mix Candidate content, runtime code, and governance changes in one PR unless it is a maintainer-approved migration and the PR states why a cross-layer change is necessary. New runtime code should be opened against `evozeus-runtime`.5455## Naming Rule5657- User-facing local scenario skill names must start with `EvoZeus-`; keep frontmatter `name` and folder paths lowercase `evozeus-*` to pass skill validation.58- Reuse project terms from `../../../docs/governance/terminology-glossary.md` and `../../../docs/reference/ontology.md`.59- Prefer canonical names such as `Session`, `Evidence`, `Case`, `Verdict`, `Artifact`, `Candidate`, `Factor`, `Pattern`, `Rejected Pattern`, and `Environment Rule`.60- New variables, filenames, headings, schemas, and CLI flags should make the layer and artifact kind obvious.61- Do not introduce synonyms for established project terms unless the terminology glossary is updated in the same governance PR.6263## High-Risk Surfaces6465These require explicit evidence and maintainer-level attention:6667- `SKILL.md`68- `skills/`69- `.github/` templates or workflows70- `scripts/github/`71- `SECURITY.md`72- `schemas/`73- `candidates/core/`74- `candidates/reviewed/`75- `docs/governance/privacy-and-redaction.md`76- `docs/reference/ontology.md`77- `docs/reference/evidence-grading.md`78- future schema, redaction, upload, session ingestion, or candidate extraction code79- any change that reintroduces runtime implementation into this repo instead of using `evozeus-runtime`8081## Pre-Submit Gate8283Before staging or pushing, run the checks that match the change:8485```bash86python3 scripts/check_pr_ready.py --base <base-ref>87git diff --check88```8990For this repository, docs and governance-only work should at minimum pass:9192```bash93python3 -m py_compile scripts/check_pr_ready.py94python3 scripts/check_pr_ready.py --base <base-ref>95git diff --check96```9798If issue templates changed, also parse `.github/ISSUE_TEMPLATE/*.yml` with a YAML parser available in the local environment.99100## PR Template101102Use the closest template:103104| Work | Template |105| --- | --- |106| Default or mixed docs/governance | `../../../.github/PULL_REQUEST_TEMPLATE.md` |107| Candidate, Case, Pattern, Factor, or Artifact | `../../../.github/PULL_REQUEST_TEMPLATE/candidate_submission.md` |108| Protocol-supporting script or behavior in this repo | `../../../.github/PULL_REQUEST_TEMPLATE/code_change.md` |109| Runtime, CLI, TUI, companion, scanner execution, local state, or report execution | Open PR in `evozeus-runtime` |110| Ontology, schema, protocol, compatibility | `../../../.github/PULL_REQUEST_TEMPLATE/schema_change.md` |111| `SKILL.md`, `skills/`, prompts, or agent instructions | `../../../.github/PULL_REQUEST_TEMPLATE/skill_instruction_change.md` |