reference
Bundle OKF 0.1 · 4 conceitos · CaioWF/keel
Open source Repository Open in the app JSON README (API)
About
# reference
* [Authoring keel skills](authoring-skills.md) - Guide for writing skills in keel following TDD methodology, including when to create a skill, SKILL.md structure, and how to wire new skills into the keel framework
# Subdirectories
* [design-notes/](design-notes/index.md) - 17 concept(s)
* [plans/](plans/index.md) - 5 concept(s)
* [specs/](specs/index.md) - 1 concept(s)
Details
- Kind
- OKF bundles
- Topic
- No topic detected
- Publisher
- caiowf
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 3
- Open pull requests
- 4
- Last push
- 2026-08-19T23:36:47Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-09-08 09:01:12
- Updated
- 2026-09-08 09:01:12
- Origin id
CaioWF/keel:docs/index.md
README
# Keel [](https://github.com/CaioWF/keel/actions/workflows/ci.yml) A zero-dependency **spec-driven development (SDD)** scaffolder. Run one script in any project and it installs the full SDD flow — document templates, discipline skills, active hooks, and quality gates — so an AI coding agent (Claude Code first; Codex, Cursor, Copilot, Gemini, Windsurf as generated views) builds features with spec → plan → gates → review discipline instead of jumping straight to code. No runtime dependencies. The hooks and gates are plain Node `.mjs` using only `node:` builtins — no Python, no third-party plugin, nothing that auto-updates underneath you. ## Why Agents are happy to write code before there's a spec, skip the plan, and commit without review. Keel makes the discipline **mechanical**: a phase gate refuses to edit code until a spec and plan are both approved, a pre-commit gate runs the quality checks before every commit, and a doc gate enforces that every acceptance criterion is traced to a task. The agent works around the gates by getting approval — never by disabling them. Those gates are client-side, so keel runs the server-side half on itself: CI executes the full test suite, keel's own doc gates, and a check that any change to what keel ships arrives with the reasoning that justifies it ([CI and server-side gates](docs/design-notes/ci-server-side-gates.md)). ## Install From inside the target project: ```bash bash /path/to/keel/bootstrap.sh ``` This lands (idempotently — existing files are kept unless `--force`): - `.specify/` — templates (spec, plan, tasks, constitution, architecture), quality gates - `.claude/hooks/` — SessionStart context loader, phase sensor, phase gate, pre-commit gate, secrets + destructive-command guards, prose slop-guard - `.claude/skills/` — the SDD chain + discipline skills - `.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 - `docs/` — `STATE.md` (working memory) + `architecture/adr/` (decision records) - `scripts/keel-watch.sh` — read-only view of work in flight (features, tasks dispatched, ledger, worktrees) as a tmux layout, or one terminal with `--no-tmux` ([parallel work visibility](docs/design-notes/parallel-work-visibility.md)) - `CLAUDE.md` (+ `AGENTS.md`) — keel's body plus `<!-- BEGIN:keel:… -->` blocks that hold what the project learns about itself (environment, tests, conventions) and the sections its packs contribute. `learn-session` fills them; `--force` refreshes the body and carries the blocks across ([living project docs](docs/design-notes/living-project-docs.md)) Generate views for other agents too: ```bash bash bootstrap.sh --agent=codex,cursor # or --all ``` Optional packs are never auto-installed from a stack signal alone, so install ends by naming the ones it skipped. To pick them (and agent views) from a menu instead of remembering flags: ```bash bash /path/to/keel/bootstrap.sh --configure ``` `--configure` is a separate command on purpose: install stays non-interactive so CI, the test suite and the agent can run it with stdin captured. Architecture style (Clean, Hexagonal, …) is deliberately *not* asked here — it belongs to the constitution plus an ADR, decided in-session where the repo can be read ([install configuration](docs/design-notes/install-configuration.md)). Requires Node (for the hooks/gates). No other dependency. Every install stamps `.specify/keel.json` (keel version, source commit, agents, packs, install/update timestamps). Check what a project has — and whether it's behind the keel you're running from: ```bash bash /path/to/keel/bootstrap.sh --status ``` ## The SDD flow ``` brainstorming → prd-writer → spec-writer → clarify → plan-writer → tasks-writer → analyze → implement-feature → implement-and-evaluate → review-and-simplify → finishing-a-development-branch ``` `tasks-writer` also writes `specs/<feature>/contract.md` — the feature's **verification contract**: environment setup plus, per `AC-N`, the proof, the command that runs it, the expected observable, and a status. `evaluator` follows it instead of re-deriving verification each loop, and records each verdict back in it. Code edits are blocked by the **phase gate** until the active feature's `spec.md` and `plan.md` both carry `status: approved`. Implementation follows TDD (test behavior, not implementation). `review-and-simplify` runs `code-review` + `security-review` in parallel then a behavior-preserving `simplify` pass before any commit is proposed. ## Quality gates `.specify/gates/run-gates.sh` runs on every commit (via the pre-commit hook) and includes zero-dep doc gates: - **audit-structure** — skill frontmatter, every `specs/NNN-*/` has a `spec.md`, no broken links - **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 - **validate-mermaid** — mermaid blocks parse plus the project's own `lint` / `test` / `build` when present (npm or make, auto-detected). ## Design Two notes capture the architecture: - [`docs/design-notes/gates-vs-skills.md`](docs/design-notes/gates-vs-skills.md) — the split: mechanical concerns → **gates** (deterministic, hard-blocking, zero tokens); judgment calls → **skills** (read-only lenses, discipline). - [`docs/design-notes/concepts-layer.md`](docs/design-notes/concepts-layer.md) — the language-agnostic concept layer (Clean Architecture plus the hexagonal/onion vocabulary, vertical slice, SOLID, error handling, testing strategy, DDD tactical and strategic, minimalism) lives in the `architecture` skill + constitution; *enforcement* lives in optional packs. - [`docs/design-notes/architecture-enforcement.md`](docs/design-notes/architecture-enforcement.md) — the other half of that split: the opt-in `architecture-gates` pack ships a zero-dep `dependency-rule` check that fails the build when imports point outward, wired through the `.specify/gates/pack.d/` seam any pack can use. [`docs/authoring-skills.md`](docs/authoring-skills.md) — how to add a skill (skill-as-TDD). ## Status Validated end-to-end on a real project. Test suite is plain shell (`bash tests/run.sh`), no framework. ## License MIT — see [LICENSE](LICENSE).