orizon-invariants

orizon-agent-init

A spec → generators → committed templates pipeline that gives every Orizon project the same security, productivity, and authorship rules in one command. Self-validating, drift-protected, AI-tooling-agnostic.

What it ships

Two surfaces for downstream consumers:

1. create-orizon-app — a Node CLI that scaffolds an Orizon-init project in one command. Installs AGENTS.md, a hardened .gitignore, lefthook hooks for Conventional Commits / no-AI-attribution / formatter dispatch / gitleaks, a .gitleaks.toml allowlist, a brand-aware README.md, a CI workflow, and a .orizon-init.yaml marker file. Idempotent on re-run.

2. orizon-invariants — a Claude Code plugin (skill + 2 PreToolUse hooks + 1 slash command) that loads the same invariants as agent guidance and intercepts bad commits at the agent layer.

Adopt in a new project

mkdir my-new-project && cd my-new-project
npm create orizon-app@latest

# Then, optionally, in Claude Code:
/plugin marketplace add github.com/MarcoLorenzi1969/orizon-agent-init
/plugin install orizon-invariants

The CLI prompts for: project name, brand pack (orizon | syneto | none), language (generic | node | python | go | rust), solo-maintainer mode, git init, lefthook install. Existing .gitignore is merged additively (your lines preserved verbatim); existing README.md and AGENTS.md are never overwritten (skipped silently). See spec §1.1 for the full non-invalidation contract.

Invariants enforced

§	Rule	Enforcement layer
§I1	No secrets in git, ever	gitignore + gitleaks pre-commit + skill guidance
§I2	Bootstrap admin must rotate	skill guidance
§I3	Defaults regenerated per environment	skill guidance
§I4	Deprecated code lives in deprecated/	skill guidance + /orizon-deprecate (v0.2)
§I5	Sole authorship — no AI tool brand	commit-msg hook + gitignore + skill guidance + Claude PreToolUse hook
§P1	Conventional Commits	commit-msg hook
§P2	Branch naming + PR flow (skipped if solo-mode)	pre-push hook
§P4	/orizon-review slash command	Claude Code plugin
§P6	Brand-stamped README template	scaffold
§P7	Pre-commit gitleaks scan	pre-commit hook
§P8	Per-language formatter dispatch	pre-commit hook

Repository structure

spec/                     single source of truth (YAML + JSON Schema)
generators/               pure-function emitters spec → string
templates/                committed generator outputs (regenerated by CI drift-check)
packages/
  generators/             @orizon/generators (private)
  create-orizon-app/      the CLI (npm published)
plugin/orizon-invariants/ Claude Code plugin
.claude-plugin/marketplace.json   marketplace manifest
docs/specs/2026-04-27-orizon-agent-init-design.md   the design spec
docs/plans/               implementation plans (Plan A done; Plan B = this; Plan C = v0.2 migration)

Develop

pnpm install
pnpm run schema-validate
pnpm run build
pnpm test
pnpm run drift-check

Drift-check is the guardian: it regenerates templates into a tempdir and diffs against the committed templates/. Hand-edits to generated files fail CI. The only valid editing surface is spec/*.yaml.

Roadmap

• v0.1 Foundation (done) — spec, generators, drift-check, dogfood.
• v0.1 Consumers (done) — create-orizon-app, plugin, e2e, npm publish.
• v0.2 Migration — npx orizon audit | plan | apply | upgrade for existing projects, with the additive-only contract from spec §1.1.

Releasing

create-orizon-app is published to npm by tag-based CI. Maintainer steps:

1. Bump packages/create-orizon-app/package.json version.
2. git tag v0.1.0 && git push --tags.
3. The publish.yml workflow runs prepack, build, tests, drift-check, then npm publish.

The NPM_TOKEN secret must be configured in GitHub repository settings (Settings → Secrets → Actions) before the first publish.

Authorship