{
  "markdown": "# Keel\n\n[![ci](https://github.com/CaioWF/keel/actions/workflows/ci.yml/badge.svg)](https://github.com/CaioWF/keel/actions/workflows/ci.yml)\n\nA zero-dependency **spec-driven development (SDD)** scaffolder. Run one script in any\nproject and it installs the full SDD flow — document templates, discipline skills, active\nhooks, and quality gates — so an AI coding agent (Claude Code first; Codex, Cursor, Copilot,\nGemini, Windsurf as generated views) builds features with spec → plan → gates → review\ndiscipline instead of jumping straight to code.\n\nNo runtime dependencies. The hooks and gates are plain Node `.mjs` using only `node:`\nbuiltins — no Python, no third-party plugin, nothing that auto-updates underneath you.\n\n## Why\n\nAgents are happy to write code before there's a spec, skip the plan, and commit without\nreview. Keel makes the discipline **mechanical**: a phase gate refuses to edit code until a\nspec and plan are both approved, a pre-commit gate runs the quality checks before every\ncommit, and a doc gate enforces that every acceptance criterion is traced to a task. The\nagent works around the gates by getting approval — never by disabling them.\n\nThose gates are client-side, so keel runs the server-side half on itself: CI executes the\nfull test suite, keel's own doc gates, and a check that any change to what keel ships\narrives with the reasoning that justifies it\n([CI and server-side gates](docs/design-notes/ci-server-side-gates.md)).\n\n## Install\n\nFrom inside the target project:\n\n```bash\nbash /path/to/keel/bootstrap.sh\n```\n\nThis lands (idempotently — existing files are kept unless `--force`):\n\n- `.specify/` — templates (spec, plan, tasks, constitution, architecture), quality gates\n- `.claude/hooks/` — SessionStart context loader, phase sensor, phase gate, pre-commit gate, secrets + destructive-command guards, prose slop-guard\n- `.claude/skills/` — the SDD chain + discipline skills\n- `.specify/memory/` — `product.md` (product brief: user, problem, north-star) + `constitution.md` (engineering principles, code standards, SDD process) — the two once-per-project layers, injected at SessionStart\n- `docs/` — `STATE.md` (working memory) + `architecture/adr/` (decision records)\n- `scripts/keel-watch.sh` — read-only view of work in flight (features, tasks dispatched, ledger,\n  worktrees) as a tmux layout, or one terminal with `--no-tmux`\n  ([parallel work visibility](docs/design-notes/parallel-work-visibility.md))\n- `CLAUDE.md` (+ `AGENTS.md`) — keel's body plus `<!-- BEGIN:keel:… -->` blocks that hold what the\n  project learns about itself (environment, tests, conventions) and the sections its packs\n  contribute. `learn-session` fills them; `--force` refreshes the body and carries the blocks\n  across ([living project docs](docs/design-notes/living-project-docs.md))\n\nGenerate views for other agents too:\n\n```bash\nbash bootstrap.sh --agent=codex,cursor   # or --all\n```\n\nOptional packs are never auto-installed from a stack signal alone, so install ends by naming\nthe ones it skipped. To pick them (and agent views) from a menu instead of remembering flags:\n\n```bash\nbash /path/to/keel/bootstrap.sh --configure\n```\n\n`--configure` is a separate command on purpose: install stays non-interactive so CI, the test\nsuite and the agent can run it with stdin captured. Architecture style (Clean, Hexagonal, …)\nis deliberately *not* asked here — it belongs to the constitution plus an ADR, decided\nin-session where the repo can be read\n([install configuration](docs/design-notes/install-configuration.md)).\n\nRequires Node (for the hooks/gates). No other dependency.\n\nEvery install stamps `.specify/keel.json` (keel version, source commit, agents, packs,\ninstall/update timestamps). Check what a project has — and whether it's behind the keel\nyou're running from:\n\n```bash\nbash /path/to/keel/bootstrap.sh --status\n```\n\n## The SDD flow\n\n```\nbrainstorming → prd-writer → spec-writer → clarify → plan-writer → tasks-writer\n  → analyze → implement-feature → implement-and-evaluate → review-and-simplify\n  → finishing-a-development-branch\n```\n\n`tasks-writer` also writes `specs/<feature>/contract.md` — the feature's **verification\ncontract**: environment setup plus, per `AC-N`, the proof, the command that runs it, the\nexpected observable, and a status. `evaluator` follows it instead of re-deriving verification\neach loop, and records each verdict back in it.\n\nCode edits are blocked by the **phase gate** until the active feature's `spec.md` and\n`plan.md` both carry `status: approved`. Implementation follows TDD (test behavior, not\nimplementation). `review-and-simplify` runs `code-review` + `security-review` in parallel\nthen a behavior-preserving `simplify` pass before any commit is proposed.\n\n## Quality gates\n\n`.specify/gates/run-gates.sh` runs on every commit (via the pre-commit hook) and includes\nzero-dep doc gates:\n\n- **audit-structure** — skill frontmatter, every `specs/NNN-*/` has a `spec.md`, no broken links\n- **eval-spec-fidelity** — every `AC-N` in the spec is covered by a task (traceability), warns on AC with no proof declared in `contract.md`, counts `SPEC_DEVIATION` markers\n- **validate-mermaid** — mermaid blocks parse\n\nplus the project's own `lint` / `test` / `build` when present (npm or make, auto-detected).\n\n## Design\n\nTwo notes capture the architecture:\n\n- [`docs/design-notes/gates-vs-skills.md`](docs/design-notes/gates-vs-skills.md) — the split:\n  mechanical concerns → **gates** (deterministic, hard-blocking, zero tokens); judgment calls →\n  **skills** (read-only lenses, discipline).\n- [`docs/design-notes/concepts-layer.md`](docs/design-notes/concepts-layer.md) — the\n  language-agnostic concept layer (Clean Architecture plus the hexagonal/onion vocabulary,\n  vertical slice, SOLID, error handling, testing strategy, DDD tactical and strategic,\n  minimalism) lives in the `architecture` skill + constitution; *enforcement* lives in optional\n  packs.\n- [`docs/design-notes/architecture-enforcement.md`](docs/design-notes/architecture-enforcement.md)\n  — the other half of that split: the opt-in `architecture-gates` pack ships a zero-dep\n  `dependency-rule` check that fails the build when imports point outward, wired through the\n  `.specify/gates/pack.d/` seam any pack can use.\n\n[`docs/authoring-skills.md`](docs/authoring-skills.md) — how to add a skill (skill-as-TDD).\n\n## Status\n\nValidated end-to-end on a real project. Test suite is plain shell (`bash tests/run.sh`),\nno framework.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 6498,
  "sha": "4548d3183c1d589de12447aa7a5ecfd5fa7b4c31fc93e1964115fcd284a8db15",
  "repo_slug": "caiowf/keel",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_caiowf_keel_docs_index_md_6c74bd73/readme"
}