Calyx is a Git-native bundle and convention for teams that use Git + Cursor + bash: constitution, specialist prompts, taxonomy, templates, capture (Git + Cursor hooks), weekly governance, a knowledge feedback loop (classify changes → require reasoning/ADR evidence in learn / guided / guardrail modes), a status report (artifact-level “is Calyx working?” without scoring people), agent role indexing and org lift prompts (calyx project level → calyx org level), and scaffold defaults (formatting, optional CI checks). This repo is not an installable product; it is the calyx core layer (ccl) you submodule at .calyx/core/. If you fork it and strip the hooks and scripts, you no longer have the maintained baseline—see CHANGELOG.md for what each manifest version added.
Latest tag: v1.1.0 (pin in .calyx/core; bundle index 1.7.7 in manifest.yaml) · CHANGELOG.md · Releases · MIT License · Philosophy (one sentence) · Hosting on GitHub
Read next: Philosophy · Why Calyx matters now · Cursor-first showcase · Experiments and future directions
For most of history, a huge share of careful thinking never became durable—debates, synthesis, and “why we didn’t do X” lived in conversations that left little trace. AI-assisted work increases how much of that thinking happens in human–agent threads, which makes the loss worse if you only keep commit messages—and makes faithful capture mandatory if anything is to compound.
Capture is still the spine: a git post-commit path to .calyx/reasoning/inbox/ and Cursor hooks to local/chat-log/ (see tooling/calyx-setup-capture.sh). Judgment still happens when you distill into reasoning logs and ADRs; without capture, there is nothing to distill.
On top of capture, this bundle adds lightweight operations you can adopt progressively: a single weekly governance pass (docs/eow-governance.md), a feedback loop that ties change impact to Calyx evidence (docs/feedback-loop.md), a status report for adoption visibility (docs/calyx-status-report.md), agent-facing indexes and prompts for org lift and taxonomy (see deliverables table), and reference material for impact-style metrics without mandatory telemetry (docs/impact-telemetry.md).
Calyx is not about vacuuming chats or harvesting private sessions. It is stewardship of reasoning: lightweight, versioned artifacts (reasoning logs, ADRs, shared vocabulary) so the thinking your organization already pays for compounds inside the project and org—where confidentiality and obligation belong. Wider contribution to shared knowledge, when it happens at all, is opt-in and sanitized—patterns and arguments, not raw transcripts.
The lasting power is local first: teams keep their “why,” reuse it, and improve it. Any benefit to the broader commons is spillover, not extraction.
Calyx core layer (ccl): this repo is the generic bundle—constitution, specialist prompts, master taxonomy, canonical templates, and minimal tooling. Each project repo mounts it as .calyx/core/ (Git submodule). Calyx org layer (col): optional second submodule .calyx/org/ for agency-wide, non-sensitive DNA. Calyx project layer (cpl): project-local reasoning, ADRs, and local-tags.yaml. Abbreviations: ccl, col, cpl — see docs/glossary.md.
| Deliverable | Location |
|---|---|
| Brain bundle (constitution, prompts, master taxonomy, ADR/reasoning templates) | constitution/, prompts/, taxonomy/, templates/ |
| New project creation (generic) | tooling/scaffold-cursor-app.sh + templates/app-scaffold/ |
| New project + GitHub push (optional SFS flow) | tooling/create-sfs-workspace.sh (wraps the scaffold; needs gh for remote create) |
| Project-creation guide | docs/new-project.md — prerequisites, flags, env vars, what gets created |
| First run / onboarding | docs/first-run.md — prerequisites + why, checklist; tooling/calyx-verify-capture.sh — guardrail checks; scaffolds add SETUP_CALYX.md + .github/workflows/calyx-verify.yml (non-blocking) |
| UX flow (Mermaid) | docs/ux-flow.md — from “incorporate Calyx” to day-to-day habits |
| Work rhythm (Mermaid) | docs/workflow.md — reasoning, ADRs, specialists, checkpoint (living doc) |
| Glossary (ccl / col / cpl) | docs/glossary.md |
| Org vs projects | docs/org-and-projects.md — studio/agency → many repos; Calyx shape independent of disk |
| Capture (v1 baseline) | tooling/calyx-setup-capture.sh — git post-commit + Cursor hooks; docs/automation.md, docs/cursor-local-chat-log.md |
| Thin EOW governance | tooling/calyx-eow-governance.sh (single weekly command), templates/eow-config.json, templates/eow-weekly-report.md, docs/eow-governance.md |
| Calyx Status report (v1) | tooling/calyx-status-report.sh — latest-status.md + JSON under .calyx/reasoning/reports/status/; docs/calyx-status-report.md |
| Cursor model routing | templates/cursor-model-routing/ — scaffold → agents/MODEL-ROUTING.md + .cursor/rules/model-routing.mdc (--no-model-routing to skip); optional Agent context on reasoning/ADR |
| Knowledge feedback loop | tooling/calyx-feedback-loop.sh (classify -> policy -> remediation), templates/feedback-config.json, docs/feedback-loop.md; scaffold adds optional .github/workflows/calyx-feedback.yml, PR/issue Calyx templates |
| ADR adoption checklist | docs/adr-adoption-checklist.md — how ADRs backflow into planning, review, CI policy, and weekly governance |
| Agent roles / org lift / taxonomy prompts | tooling/calyx-install-agent-roles.sh → .calyx/AGENT_ROLES.md; prompts/org-lift-cadence.txt, prompts/promote-cpl-to-col.txt, prompts/librarian-taxonomy-sync.txt; prompts/README.md |
| Code quality defaults (new repos) | Scaffold templates/app-scaffold/ — .editorconfig, .prettierrc.json, .prettierignore; norms in AGENTS.md / docs-GIT.md |
| Machine index | manifest.yaml |
| Cutting releases | docs/releasing.md — maintainers, tags (v1.1.0 current), pre-flight checklist |
| GitHub | docs/github-repository-setup.md — visibility, description, releases, traffic |
| Changelog | CHANGELOG.md |
| License | LICENSE (MIT) |
| Philosophy | docs/philosophy.md — stewardship vs extraction; epistemic framing |
| Why Calyx now (one page) | docs/why-calyx-now.md — org intelligence vs solo speed; capture; boundaries |
| Experiments and future directions | docs/experiments-and-future.md — design notes, status legend, scope recap; optional processes not bundled as tooling/ |
| Impact telemetry (reference) | docs/impact-telemetry.md — optional metrics, release-boundary audits, ROI estimates; no dedicated runner in this repo |
| Scope: governance vs deferred metrics | docs/decisions/ADR-0001-governance-feedback-and-deferred-telemetry.md — what ships in tooling/ vs parked continuous impact/scoring |
| Cursor-first showcase (partner brief) | docs/cursor-first-showcase.md — architecture, touchpoints, and demo flow for Cursor-native Calyx |
Start here for a new repo: docs/new-project.md, then use the commands in New app repo below.
| Path | Purpose |
|---|---|
constitution/ |
Non-negotiable principles and mandatory artifacts |
prompts/ |
Specialist agent system prompts (10th Man, Librarian, Broker) |
taxonomy/ |
Master tag vocabulary (master-tags.yaml) |
templates/ |
Canonical reasoning log and ADR shapes; import runbook (distill-external-to-calyx.md) for Slack/email → Calyx |
examples/ |
Illustrative artifacts (not production data) |
tooling/ |
Lean scripts: project creation (scaffold-cursor-app.sh, create-sfs-workspace.sh), Ollama, closeout, EOW governance (calyx-eow-governance.sh), feedback loop (calyx-feedback-loop.sh), status report (calyx-status-report.sh) |
docs/ |
philosophy.md, why-calyx-now.md, first-run.md, releasing.md, new-project.md, ux-flow.md, workflow.md, glossary.md, org-and-projects.md, automation.md, eow-governance.md, feedback-loop.md, calyx-status-report.md, adr-adoption-checklist.md, cursor-first-showcase.md, experiments-and-future.md, impact-telemetry.md, decisions/ (e.g. ADR-0001) |
manifest.yaml |
Machine-readable index for sync automation |
templates/app-scaffold/ |
Files used by tooling/scaffold-cursor-app.sh (Calyx + default app layout) |
- Submodule this repo at
.calyx/core/in each project (pinv1.1.0or a newer tag deliberately once you adopt capture). - After every clone (each machine):
bash .calyx/core/tooling/calyx-setup-capture.shfrom the project root—installs git + Cursor capture. Requirespython3onPATHfor chat logging. - Optional org layer (e.g. Scalefree): second submodule at
.calyx/org/for non-sensitive agency-wide defaults—seetemplates/dot-calyx-README.mdfor the layout. - Project-local content always lives beside those mounts:
.calyx/reasoning/,.calyx/decisions/,.calyx/taxonomy/local-tags.yaml. - Changes to generic behavior start in calyx-core; agency-only changes live in org; engagement-specific work stays in the project repo.
This repository includes .cursorrules so agents follow Calyx when working only in calyx-core.
Full detail: docs/new-project.md.
From a clone of calyx-core, or with this repo on your PATH:
bash tooling/scaffold-cursor-app.sh /path/to/new-project --name "My App"This creates .cursorrules, .calyx/ (reasoning, decisions, taxonomy), AGENTS.md (norms for AI assistants + Calyx logging), VERSION (starts at 0.1), docs/GIT.md, a starter .gitignore, git init on main, and git submodule add for .calyx/core (override URL with CALYX_CORE_URL=...). When the submodule is present, the scaffold runs calyx-setup-capture.sh so v1 capture is live. By default it also adds apps/web, apps/api, mcp/, packages/shared, infra/, and local/ (gitignored) so web + API + MCP + DB/infra work has a home from day one. Use --minimal for Calyx-only, or --no-submodule / --no-git when bootstrapping offline—then run calyx-setup-capture.sh yourself after adding .calyx/core.
For Scale Free Strategy workspaces under ~/Documents/CURSOR (override with SFS_WORKSPACE_ROOT), with an SFS badge in README.md / AGENTS.md, initial commit, and private GitHub repo + push via gh:
bash tooling/create-sfs-workspace.sh "Human Project Name" [repo-slug]Requires gh auth login for automatic gh repo create. Use --no-github if you only want a local repo; --public for a public remote.
calyx-core— generic Calyx bundle; submodule at.calyx/core/in every project.- Org repo (e.g.
calyx-scalefree-org) — optional second submodule at.calyx/org/for your studio’s shared, non-sensitive layer. - Project repos — one repo per product or client; each has its own local
.calyx/reasoning/and.calyx/decisions/. - Tag releases on calyx-core (e.g.
v1.1.0) so projects can pin a known-good bundle. Maintainer checklist: docs/releasing.md.