{"id":50137815,"url":"https://github.com/samuelnp/centinela","last_synced_at":"2026-05-23T23:08:49.265Z","repository":{"id":357545573,"uuid":"1177636455","full_name":"samuelnp/centinela","owner":"samuelnp","description":"Enforces plan → code → tests → validate → docs discipline for AI coding agents (Claude Code, OpenCode).","archived":false,"fork":false,"pushed_at":"2026-05-13T07:18:35.000Z","size":3335,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-13T09:23:25.737Z","etag":null,"topics":["agents","ai-coding-assistant","anthropic","bdd","claude","claude-code","cli","code-review","dev-workflow","developer-tools","gherkin","go","golang","llm-tools","opencode","prompt-engineering","quality-gates","tdd","workflow","workflow-automation"],"latest_commit_sha":null,"homepage":"https://github.com/samuelnp/centinela#readme","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samuelnp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-10T08:10:29.000Z","updated_at":"2026-05-13T07:17:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/samuelnp/centinela","commit_stats":null,"previous_names":["samuelnp/centinela"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/samuelnp/centinela","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelnp%2Fcentinela","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelnp%2Fcentinela/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelnp%2Fcentinela/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelnp%2Fcentinela/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samuelnp","download_url":"https://codeload.github.com/samuelnp/centinela/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samuelnp%2Fcentinela/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33415064,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"ssl_error","status_checked_at":"2026-05-23T22:14:43.778Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai-coding-assistant","anthropic","bdd","claude","claude-code","cli","code-review","dev-workflow","developer-tools","gherkin","go","golang","llm-tools","opencode","prompt-engineering","quality-gates","tdd","workflow","workflow-automation"],"created_at":"2026-05-23T23:08:40.051Z","updated_at":"2026-05-23T23:08:49.258Z","avatar_url":"https://github.com/samuelnp.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/logo-banner.png\" alt=\"Centinela\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n# Centinela\n\n\u003e **Plan → code → tests → validate → docs — enforced.**\n\n\u003cp align=\"left\"\u003e\n  \u003ca href=\"https://github.com/samuelnp/centinela/actions/workflows/validate.yml\"\u003e\u003cimg src=\"https://github.com/samuelnp/centinela/actions/workflows/validate.yml/badge.svg\" alt=\"validate\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/samuelnp/centinela/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/samuelnp/centinela?display_name=tag\u0026sort=semver\" alt=\"latest release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/samuelnp/centinela/blob/main/go.mod\"\u003e\u003cimg src=\"https://img.shields.io/github/go-mod/go-version/samuelnp/centinela\" alt=\"go version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/samuelnp/centinela/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/samuelnp/centinela\" alt=\"license\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/samuelnp/centinela\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/samuelnp/centinela\" alt=\"go report card\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/samuelnp/centinela/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/samuelnp/centinela?style=social\" alt=\"stars\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nA development workflow enforcer for Claude Code and OpenCode projects. Centinela turns the \"plan → code → tests → validate → docs\" discipline from a suggestion into a mechanical constraint — enforced by agent integrations that run automatically in coding sessions.\n\n### 30-second tour\n\n```bash\ngo install github.com/samuelnp/centinela@latest\n\ncentinela init                    # wire Claude/OpenCode hooks + scaffold docs/\ncentinela start my-feature        # required before any file write — opens \"plan\" step\n# write docs/plans/my-feature.md + specs/my-feature.feature, then:\ncentinela complete my-feature     # advances plan → code (blocked if artifacts missing)\n# … implement … advance through tests → validate → docs\ncentinela validate                # runs G1 file-size, i18n, your test/lint commands\n```\n\nIf an agent tries to write source code while the workflow is in the `plan` step, the prewrite hook blocks the write and tells the agent what's missing.\n\n### Contents\n\n- [Demo](#demo)\n- [Why Centinela](#why-centinela)\n- [When *not* to use Centinela](#when-not-to-use-centinela)\n- [Latest Features](#latest-features)\n- [Install](#install)\n- [Getting Started](#getting-started)\n- [The Standard Five-Step Workflow](#the-standard-five-step-workflow)\n- [How the Hooks Work](#how-the-hooks-work)\n- [Gate Checks](#gate-checks)\n- [Architecture Archetypes](#architecture-archetypes)\n- [`centinela.toml` Reference](#centinelatoml-reference)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Demo\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/demo.gif\" alt=\"Centinela workflow demo\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003e Recorded with [`vhs`](https://github.com/charmbracelet/vhs). To regenerate: `vhs assets/demo.tape`.\n\n---\n\n## Why Centinela\n\nAI coding agents are fast but undisciplined. Left to their own devices they skip planning, write tests as an afterthought, and ship without validation. Centinela fixes this by:\n\n- **Blocking file writes** in the wrong workflow step via agent integrations\n- **Requiring artifacts** before a step can advance — no plan file means no code, no tests means no validate\n- **Running gate checks** automatically at the validate step (file size limits, i18n completeness, your test suite)\n- **Injecting context** into every agent session so the model always knows which feature is active and which step it is on\n\nThe result: every feature ships with a written plan, a Gherkin spec, three test layers, and a passing gate suite — regardless of whether a human or an AI agent wrote it.\n\n---\n\n## When *not* to use Centinela\n\nCentinela trades flexibility for discipline. Skip it if any of these apply:\n\n- **Throwaway scripts / one-off experiments.** The 5-step ceremony is overhead you'll regret.\n- **Solo prototyping in the first 48 hours of an idea.** Plans, specs, and gate suites are useful *after* you've validated the idea — not while you're still figuring out what to build.\n- **You don't use an AI coding agent.** Centinela's strongest leverage is forcing structure on agent-generated code; humans typing every keystroke already have plenty of friction.\n- **Your team has a different workflow you actually follow.** Centinela is opinionated. If your team already ships clean specs, tests, and docs without enforcement, the hooks will feel like a tax.\n\nCentinela is for *production code* you intend to maintain, where an AI agent is doing meaningful work and you want the agent's output to look like it came from a disciplined human team.\n\n---\n\n## Latest Features\n\n- **Claude + OpenCode parity** with shared setup prompts, workflow context, prewrite enforcement, postwrite status updates, setup-priority handling, and migration guidance.\n- **Roadmap-first bootstrap** with automatic `PROJECT.md` setup, `ROADMAP.md` creation, `.workflow/roadmap.json`, roadmap analysis, roadmap quality artifacts, clear missing-artifact recovery, and `centinela roadmap validate`.\n- **Strict five-step delivery** with enforced `plan -\u003e code -\u003e tests -\u003e validate -\u003e docs` order, required step artifacts, explicit step confirmation modes, and no workflow bypass for normal features.\n- **Plan advisor mode** that reads current feature artifacts plus roadmap dependencies, same-phase siblings, quality notes, and prior edge-case lessons before asking a small set of high-value planning questions.\n- **Actionable specialist orchestration** where `big-thinker`, `feature-specialist`, `senior-engineer`, `qa-senior`, `documentation-specialist`, and user-facing `ux-ui-specialist` evidence must point to real project outputs.\n- **Stronger quality gates** including executable acceptance-test enforcement, validation-command coverage for acceptance tests, default 100-line source files, and audited G1 exceptions for rare 130-line cases.\n- **Managed migrations and generated docs** through `centinela migrate`, `centinela migrate docs`, `centinela migrate setup --agent claude|opencode|both`, `centinela docs validate`, and `centinela docs generate`.\n- **Cleaner workflow feedback** with compact `🛡️👁️` CLI output, status tags, and prompt-driven command mapping for roadmap, start, continue, validate, and docs flows.\n\n---\n\n## Install\n\n**Prerequisites:** Go 1.21+\n\n```bash\ngo install github.com/samuelnp/centinela@latest\n```\n\nOr download a pre-built binary from [Releases](https://github.com/samuelnp/centinela/releases).\n\nFor macOS/Linux, you can install the latest release binary directly:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/samuelnp/centinela/main/scripts/install.sh | sh\n```\n\nVerify:\n\n```bash\ncentinela --help\n```\n\n\u003e **macOS/Linux:** `go install` places the binary in `~/go/bin`. Ensure that directory is on your PATH:\n\u003e ```bash\n\u003e export PATH=\"$HOME/go/bin:$PATH\"  # add to ~/.zshrc or ~/.bashrc\n\u003e ```\n\n---\n\n## Getting Started\n\n### 1. Initialize a project\n\nRun once in your project root:\n\n```bash\ncentinela init\n```\n\nThis creates:\n\n| File / Directory | Purpose |\n|-----------------|---------|\n| `CLAUDE.md` | Framework rules — used by Claude, and by OpenCode via compatibility mode |\n| `PROJECT.md.template` | Fill in and rename to `PROJECT.md` |\n| `centinela.toml` | Configure validate commands and gate checks |\n| `docs/architecture/` | architecture reference documents + edge-case tester prompt |\n| `docs/plans/` `specs/` `tests/` | Required empty directories |\n| `.claude/settings.json` | Claude hooks wired automatically |\n| `opencode.json` + `.opencode/plugins/centinela.js` | OpenCode integration wiring |\n\nSafe to re-run — existing files are never overwritten.\n\n`init` is the bootstrap command. For ongoing upgrades to managed docs and setup\nartifacts, use `migrate` (preview by default, apply only with `--apply`).\n\nUse `--local` to write Claude hooks to `.claude/settings.local.json` (useful for personal overrides without committing to the repo):\n\n```bash\ncentinela init --local\n```\n\nChoose integration target explicitly when needed:\n\n```bash\ncentinela init --agent claude\ncentinela init --agent opencode\ncentinela init --agent both   # default\n```\n\n### 2. Fill in PROJECT.md\n\nOpen your coding agent in the project — if `PROJECT.md` is missing, Centinela will prompt Claude or OpenCode to interview you and write it. Alternatively, rename `PROJECT.md.template` to `PROJECT.md` and complete every section manually. This file tells both you and the agent what the project is, which architecture pattern it follows, and where everything lives.\n\n### 3. Configure centinela.toml\n\nAdd your stack's lint and test commands:\n\n```toml\n[validate]\ncommands = [\n  \"./scripts/check-coverage.sh\",\n]\n```\n\nDefault coverage threshold is `95.0%`. Override temporarily with:\n\n```bash\nMIN_COVERAGE=96.5 ./scripts/check-coverage.sh\n```\n\nCommands run natively via the OS. No shell scripts, no bash dependency — works on Windows, macOS, and Linux.\n\n### Example: Bootstrap a new project\n\nUse this flow when starting from scratch.\n\n```bash\ncentinela init\n```\n\nThen open your coding agent in the repo and follow setup prompts.\n\nExpected sequence:\n\n1. If `PROJECT.md` is missing, centinela asks the agent to interview you and write it.\n2. Once `PROJECT.md` exists, centinela asks the agent to define your roadmap.\n3. The agent produces:\n   `ROADMAP.md` (human-readable phased plan), `.workflow/roadmap.json` (machine-readable roadmap), `.workflow/roadmap-analysis.md`, `.workflow/roadmap-analysis.json`, `.workflow/roadmap-quality.md`, `.workflow/roadmap-quality.json`, and `docs/features/\u003cfeature-slug\u003e.md` for the initial feature set.\n\nIf the agent misses one of those files, use `docs/architecture/artifact-templates.md` for the exact setup and per-feature workflow artifact shapes.\n\nVerify roadmap status:\n\n```bash\ncentinela roadmap\ncentinela roadmap validate\n```\n\nStart implementation from the first roadmap feature:\n\n```bash\ncentinela start \u003cfirst-feature-slug\u003e\n```\n\nYou can also use natural language instead of typing commands directly. The agent\nmaps your intent to centinela commands under the hood.\n\nRoadmap and status intent examples:\n\n- `Check roadmap`\n- `Show roadmap progress`\n- `What feature should we build next?`\n- `What step are we currently in?`\n\nStart feature intent examples:\n\n- `Implement first feature`\n- `Start the next roadmap feature`\n- `Begin feature: user-auth`\n- `Kick off checkout-flow`\n\nContinue feature intent examples:\n\n- `Continue current feature`\n- `Resume work on billing-retries`\n- `Complete this step`\n- `Move to the next step for onboarding-wizard`\n\n### 4. Start building\n\n```bash\ncentinela start my-feature\n```\n\nFor standard product features, follow the same path every time:\n\n1. Write the plan artifacts in `docs/plans/` and `specs/`.\n2. Run `centinela complete \u003cfeature\u003e` to advance to `code`.\n3. Implement the change, then advance to `tests`.\n4. Add unit, integration, acceptance, and edge-case coverage, then advance to `validate`.\n5. Run `centinela validate`, resolve any gate failures, then advance to `docs`.\n6. Run `centinela docs validate` and `centinela docs generate` to publish the project-facing HTML output.\n\nFor a complete agent-collaboration example, see [`HOWTO.md`](HOWTO.md). It walks through using Centinela to generate a small landing page MVP without skipping the required workflow steps.\n\nProper use checklist:\n\n- Start or resume a named feature before editing files: `centinela start \u003cfeature\u003e` or `centinela status \u003cfeature\u003e`.\n- Keep all feature work inside the current step; if a write is blocked, create the missing artifact or advance the workflow instead of forcing the edit.\n- Treat `complete` prompts as review gates. Approve advancement only after the current step artifacts exist and match the plan.\n- Put acceptance tests in `tests/acceptance/` and ensure `[validate].commands` runs them.\n- Finish with `centinela validate`, `centinela docs validate`, and `centinela docs generate --out docs/project-docs/index.html`.\n\n### 5. Migrate managed assets\n\nPreview all managed upgrades (docs + setup):\n\n```bash\ncentinela migrate\n```\n\nPreview docs-only upgrades:\n\n```bash\ncentinela migrate docs\n```\n\nApply full sync:\n\n```bash\ncentinela migrate --apply\n```\n\nScope setup migration to one integration when needed:\n\n```bash\ncentinela migrate setup --agent claude\ncentinela migrate setup --agent opencode\ncentinela migrate setup --agent both --apply\n```\n\nRegenerate the HTML presentation explicitly when needed:\n\n```bash\ncentinela docs validate\ncentinela docs generate --out docs/project-docs/index.html --title \"Centinela Project Documentation\"\n```\n\n---\n\n## The Standard Five-Step Workflow\n\nMost delivery features follow the same five steps in order. Phase 0 bootstrap work can use a shorter roadmap-defined step order, but Centinela still enforces that order and its required artifacts.\n\n```\nplan → code → tests → validate → docs\n```\n\n| Step | What you produce | What centinela checks before advancing |\n|------|-----------------|---------------------------------------|\n| **plan** | Plan doc in `docs/plans/` + Gherkin spec in `specs/` | Both files exist on disk |\n| **code** | Implementation | Nothing — architecture rules govern this step |\n| **tests** | Unit, integration, acceptance + edge-case analysis | Test files exist + `.workflow/\u003cfeature\u003e-edge-cases.md` exists |\n| **validate** | Gatekeeper conflict report | All gate checks pass + all `centinela.toml` commands exit 0 |\n| **docs** | Human-facing project documentation | `.workflow/\u003cfeature\u003e-documentation-specialist.md` + `.workflow/\u003cfeature\u003e-documentation-specialist.json` + `docs/project-docs/index.html` |\n\nIn strict orchestration mode, specialist evidence must be actionable:\n\n- `big-thinker` and `feature-specialist` outputs must point to real `docs/plans/...` or `specs/...` artifacts.\n- `senior-engineer` outputs must include at least one real non-evidence implementation file.\n- `ux-ui-specialist` is required during `code` only for features whose brief declares `surface: user-facing`; its outputs must include at least one real UI file, `mobileFirst: true`, and the required UX review tags.\n- `qa-senior` outputs must include at least one real test file and `.workflow/\u003cfeature\u003e-edge-cases.md`.\n\nUI path enforcement is configurable:\n\n```toml\n[orchestration]\nui_paths = [\"src/ui\", \"src/components\", \"app/views\", \"web\", \"styles\"]\n```\n\nStep confirmation prompts are configurable in `centinela.toml`:\n\n```toml\n[workflow]\nstep_confirmation_mode = \"every_step\" # every_step | after_plan | auto\nplan_advisor_mode = \"missing_info\"   # missing_info | always | off\nplan_question_limit = 4               # capped at 4 questions per round\n```\n\n### Workflow commands\n\n```bash\ncentinela start \u003cfeature\u003e       # Start a feature (required before any file writes)\ncentinela status \u003cfeature\u003e      # Show current step and artifact status\ncentinela status-all            # Show all active features\ncentinela complete \u003cfeature\u003e    # Mark step done and advance\ncentinela roadmap               # Show roadmap phase and feature progress\ncentinela roadmap validate      # Validate roadmap analysis and quality artifacts\ncentinela validate              # Run gate checks manually\ncentinela migrate               # Preview full managed docs + setup migration\ncentinela migrate docs          # Preview managed docs migration only\ncentinela migrate setup         # Preview setup migration only\ncentinela docs validate         # Validate inputs for project documentation report\ncentinela docs generate         # Generate HTML docs with Mermaid diagrams\n```\n\n---\n\n## How the Hooks Work\n\n`centinela init` wires Claude and OpenCode integrations. Under the hood those integrations call `centinela hook ...` commands to keep workflow enforcement, setup guidance, and session context in sync.\n\n### PreToolUse — Write / Edit\n\nBefore Claude writes or edits any file, centinela checks whether that file belongs to the current workflow step. If you are in the `plan` step and Claude tries to write a source file, the hook blocks it and explains why.\n\n### PostToolUse — Write / Edit\n\nAfter every file write, centinela appends a compact status tag to the session:\n\n### Prompt Advisor — Plan Step\n\nDuring the `plan` step, Centinela also injects a plan-advisor directive. By default it runs in\n`missing_info` mode, inspects `docs/features/\u003cfeature\u003e.md`, `docs/plans/\u003cfeature\u003e.md`, and\n`specs/\u003cfeature\u003e.feature`, then enriches that with roadmap dependencies, same-phase sibling\nfeatures, roadmap quality notes, and related edge-case lessons. It asks up to 4 missing\nhigh-value questions through `big-thinker` and `feature-specialist` lenses. Dependency context is\npreferred before sibling context, and user-facing features receive UX/mobile-first questions only\nwhen those topics are still missing.\n\n```\n↳ my-feature · code · 2/5\n```\n\nFor Claude, Centinela can also render a compact status line so the current feature, step, and risk state stay visible outside the main response flow.\n\n### UserPromptSubmit\n\nMultiple hooks run at the start of every message:\n\n**Project setup** — if `PROJECT.md` is missing but `PROJECT.md.template` exists, centinela injects a prompt instructing the agent to interview the user and write `PROJECT.md`. Once `PROJECT.md` exists, Centinela can also require `ROADMAP.md`, roadmap analysis artifacts, roadmap quality artifacts, and production-readiness setup before feature work continues.\n\n**Managed migration** — if managed docs or setup assets are outdated, centinela\ninjects migration guidance and instructs the assistant to ask for approval before\nrunning apply commands.\n\n**Workflow context** — injects a context block showing all active workflows and their current step, so Claude always has accurate state without reading any files.\n\n**Autostart + orchestration** — when no workflow is active, Centinela can auto-start a feature from prompt intent. In strict orchestration mode it also tells the agent which specialist evidence files are required before `centinela complete` can advance the step.\n\n---\n\n## Gate Checks\n\nGates are quality checks that must pass before a feature can ship. They run during `centinela validate` and automatically when completing the `validate` step.\n\n### Built-in gates\n\n| Gate | Rule | Config |\n|------|------|--------|\n| **G1: File Size** | Default max 100 lines, with optional justified exceptions up to 130 lines | `[gates] file_size = true` |\n| **G11: i18n** | All locale files have identical keys (no missing translations) | `[gates] i18n = true` |\n\nG11 supports two formats natively:\n\n```toml\n# JSON locale files (next-intl, i18next, vue-i18n)\n[i18n]\nformat  = \"json\"\ndir     = \"src/i18n/messages\"\nlocales = [\"en\", \"es\", \"fr\"]\n\n# GNU gettext .po files (Godot, Qt)\n[i18n]\nformat  = \"gettext\"\ndir     = \"i18n\"\nlocales = [\"en\", \"es\"]\n```\n\nFor other formats (Unity CSV, Android XML, iOS `.lproj`), set `format = \"none\"` and add a custom command to `[validate] commands`.\n\n### Diff-aware mode\n\n`centinela validate` can scope the file-walking gates (G1, G11) to files changed on the current branch, so the report flags only violations introduced by your work — not pre-existing ones in untouched files.\n\nDefault behavior (`diff_mode = \"auto\"`):\n\n- **Locally** (no `CI` env var): diff-aware. Header reads `Built-in Gates (diff-aware: N files changed since main)`.\n- **In CI** (`CI=true` or `CI=1`): full scan. Header reads `Built-in Gates (full scan)`. The ship gate stays strict.\n\nConfigure via `centinela.toml`:\n\n```toml\n[validate]\ndiff_mode = \"auto\"   # \"auto\" | \"always\" | \"off\"\ndiff_base = \"main\"   # any git ref (e.g. \"master\", \"develop\")\n```\n\nOverride per invocation:\n\n```bash\ncentinela validate --changed   # force diff-aware\ncentinela validate --full      # force full scan\n```\n\nFlags beat config, config beats CI detection. `--changed` and `--full` are mutually exclusive.\n\nHow the change set is built:\n\n- `git diff --name-only --diff-filter=ACMR $(git merge-base HEAD \u003cdiff_base\u003e)` for tracked changes.\n- `git ls-files --others --exclude-standard` for untracked files (new code is gated before `git add`).\n- Renamed files appear via the new path. Deleted files are naturally skipped.\n\nG1 walks only files in the change set. G11 runs the full key-completeness comparison when any locale file is in the change set, and short-circuits with a \"no locale changes\" Pass otherwise (partial-locale comparison is not meaningful).\n\nUser `[validate] commands` are **not** scoped by the diff — they always run in full.\n\nDegrade paths: non-git directory, missing diff base, shallow clone, or any git failure prints a one-line `notice:` and falls back to full scan.\n\nCI systems that don't set `CI=true` (uncommon — GitHub Actions, GitLab CI, CircleCI, Travis, Buildkite, and Drone all do) need either `diff_mode = \"off\"` or `--full` in the pipeline.\n\n### Manual gates (code review)\n\n| Gate | Rule |\n|------|------|\n| **G2: Layer Dependencies** | No imports cross forbidden layer boundaries (archetype-specific) |\n| **G3: Type Safety** | Strictest static analysis — no `any`, no untyped variables |\n| **G5: Spec First** | Every feature has a `.feature` file before implementation starts |\n| **G6: Plan First** | Every feature has a plan document before implementation starts |\n| **G7: No Business Logic in Outer Layer** | UI components and adapters contain no domain logic |\n| **G8: Single Responsibility** | Each file exports one thing and does one thing |\n\nFull gate documentation: [`docs/architecture/gatekeepers.md`](internal/scaffold/assets/docs/architecture/gatekeepers.md)\n\n---\n\n## Architecture Archetypes\n\nCentinela supports five architecture patterns. You choose one when filling in `PROJECT.md`. The choice determines which layer rules, forbidden imports, and test expectations apply.\n\n| Archetype | Best for |\n|-----------|---------|\n| **Hexagonal** | Multiple external integrations (APIs, databases), domain logic that must be testable without infrastructure |\n| **Rails-native** | Framework-opinionated stacks (Rails, Django, Laravel) — follow the framework conventions |\n| **N-Tier** | Classic layered apps: HTTP handlers → services → repositories |\n| **ECS** | Games — entities, components, and systems |\n| **Modular** | Monorepo-style projects with clear public API contracts between modules |\n\nEach archetype has its own layer dependency rules (G2), outer-layer definition (G7), and test coverage expectations (G4).\n\nSee [`docs/architecture/architecture-overview.md`](internal/scaffold/assets/docs/architecture/architecture-overview.md) for the full comparison.\n\n---\n\n## centinela.toml Reference\n\n```toml\n# Commands centinela runs during the validate step.\n# Executed natively — no shell scripts required.\n[validate]\ncommands = [\n  # TypeScript:  \"npx tsc --noEmit\", \"npx vitest run\", \"npx cucumber-js\"\n  # Python:      \"mypy --strict src\", \"pytest\", \"behave\"\n  # Go:          \"go vet ./...\", \"go test ./...\"      # includes tests/acceptance\n  # Ruby:        \"bundle exec rubocop\", \"bundle exec rspec\", \"bundle exec cucumber\"\n  # Rust:        \"cargo check\", \"cargo test\"          # add acceptance runner if separate\n]\ndiff_mode = \"auto\"   # \"auto\" (default) | \"always\" | \"off\" — see Diff-aware mode above\ndiff_base = \"main\"   # any git ref; merge-base with this branch defines the change set\n\n# Built-in gate toggles\n[gates]\nfile_size = true   # G1: fail if any source file exceeds 100 lines by default\ni18n      = false  # G11: check translation key completeness\n\n# Optional: explicit justified G1 exceptions for rare cases\n[[gates.file_size_exceptions]]\npath = \"internal/config/generated_map.go\"\nkind = \"configuration\"  # \"configuration\" or \"domain_atomic\"\nreason = \"Large static map is clearer as one unit\"\nmax_lines = 130\n\n# i18n config (required when gates.i18n = true)\n[i18n]\nformat  = \"json\"              # \"json\" | \"gettext\" | \"none\"\ndir     = \"src/i18n/messages\"\nlocales = [\"en\"]\n```\n\n---\n\n## Generated Project Structure\n\nAfter `centinela init` and filling in `PROJECT.md`:\n\n```\nyour-project/\n  CLAUDE.md                      ← framework rules (auto-loaded by Claude)\n  PROJECT.md                     ← project definition\n  centinela.toml                 ← validate commands + gate config\n  .claude/\n    settings.json                ← centinela hooks\n  .workflow/\n    \u003cfeature\u003e.json               ← workflow state per feature\n    \u003cfeature\u003e-gatekeeper.md      ← gatekeeper conflict report\n  docs/\n    architecture/                ← 16 reference documents\n    plans/                       ← one plan doc per feature\n  specs/\n    \u003cfeature\u003e.feature            ← Gherkin acceptance criteria\n  tests/\n    unit/\n    integration/\n    acceptance/\n      \u003cfeature\u003e.steps.*          ← executable Gherkin step definitions\n```\n\n---\n\n## Included Architecture Documentation\n\n`centinela init` copies 16 reference documents into `docs/architecture/`:\n\n| Document | Contents |\n|----------|---------|\n| `architecture-overview.md` | All five archetypes compared — when to use each |\n| `artifact-templates.md` | Exact setup and per-feature workflow artifact templates |\n| `hexagonal.md` | Ports-and-adapters layers, dependency rules, forbidden imports |\n| `rails-native.md` | MVC conventions, what belongs in models vs services vs views |\n| `n-tier.md` | Controller → Service → Repository layer rules |\n| `ecs.md` | Entity-Component-System patterns for games |\n| `modular.md` | Module boundaries and public API contracts |\n| `dependency-injection.md` | DI container patterns across archetypes |\n| `testing-strategy.md` | Unit, integration, and acceptance test structure for all archetypes |\n| `gatekeepers.md` | Full gate reference (G1–G11) with per-archetype rules |\n| `gatekeeper-prompt.md` | Prompt for the Gatekeeper AI subagent conflict review |\n| `documentation-generator-prompt.md` | LLM-first prompt template for polished docs generation with CLI fallback |\n| `workflow-enforcement.md` | How the three enforcement layers work |\n| `i18n-strategy.md` | Translation key conventions by format |\n| `example-feature-walkthrough.md` | End-to-end example of the five-step workflow |\n| `new-project-guide.md` | Step-by-step setup for new projects |\n\n---\n\n## Build from Source\n\n```bash\ngit clone https://github.com/samuelnp/centinela\ncd centinela\ngo build -o centinela ./cmd/centinela/\n```\n\nCross-compile for other platforms:\n\n```bash\nGOOS=linux   GOARCH=amd64 go build -o centinela-linux-amd64  ./cmd/centinela/\nGOOS=darwin  GOARCH=arm64 go build -o centinela-darwin-arm64 ./cmd/centinela/\nGOOS=windows GOARCH=amd64 go build -o centinela-windows.exe  ./cmd/centinela/\n```\n\n---\n\n## Contributing\n\nCentinela uses its own workflow to develop itself.\n\n```bash\ncentinela start \u003cfeature-name\u003e\n# plan → code → tests → validate → docs\ncentinela complete \u003cfeature-name\u003e\n```\n\nConventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`.\nOne feature per branch. Never push failing tests.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelnp%2Fcentinela","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamuelnp%2Fcentinela","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamuelnp%2Fcentinela/lists"}