The specification, interaction layer, and operational scaffold for TML primitives. Clone this repo to create a coherence repository for your team, process, or system.
The Missing Layer — expressed as itself.
The PDK packages each TML primitive as a self-contained, self-documenting, customizable unit. It borrows the best distribution pattern from skills — progressive disclosure, folder-per-concept, readable by agents and humans alike — and applies it to something fundamentally higher-order: the governance of work itself.
A Scope is a Scope whether it governs one person's task list or a Fortune 500's global operations. The primitives are identical at every scale. What changes is the density of what's inside them.
This repo is a template. You clone it or fork it to create your own coherence repository for your own scope.
tml-pdk/
├── DECLARATION.json ← This repo's own TML declaration (self-referential)
├── CHANGELOG.md ← Spec evolution history
│
├── primitives/ ← THE CORE — one folder per primitive
│ ├── scope/ ← Governance boundaries
│ ├── domain/ ← Bounded areas of concern
│ ├── capability/ ← Atomic units of value
│ ├── archetype/ ← Role-based governance identities
│ ├── policy/ ← Enforced rules and constraints
│ ├── view/ ← Filtered projections per audience
│ ├── connector/ ← Governed read pathways
│ ├── binding/ ← Governed write pathways
│ └── provenance/ ← Audit trail
│
├── relationships/ ← How primitives connect
│ ├── RELATIONSHIPS.md ← The graph
│ ├── inheritance.md ← Parent → child property flow
│ └── composition.md ← How primitives form Declarations
│
├── starters/ ← Scale-appropriate entry points
│ ├── personal/ ← ~15 minutes, 1 person
│ ├── team/ ← ~1 hour, 3–20 people
│ ├── organization/ ← Phased over weeks
│ ├── client-engagement/ ← Child Scope for a client
│ └── fork-guide.md ← When and how to fork
│
├── patterns/ ← Reusable governance patterns
│ ├── approval-chain.md
│ ├── exception-request.md
│ ├── scope-nesting.md
│ ├── capability-delegation.md
│ ├── client-onboarding.md
│ └── audit-response.md
│
└── meta/ ← The repo governing itself
├── governance.md
├── versioning.md
└── how-to-contribute.md
Every primitive folder follows the same internal structure:
primitives/scope/
├── PRIMITIVE.md ← The specification (what Scope IS)
├── skills/ ← Agent/human interaction layer
│ ├── explain.md ← Teach what this primitive means
│ ├── assess.md ← Evaluate if a primitive is well-formed
│ ├── create.md ← Guide creation of a new instance
│ └── [specific].md ← Primitive-specific skills
├── examples/ ← Scale-specific reference instances
│ ├── personal.yaml
│ ├── team.yaml
│ └── org.yaml
├── hooks/ ← Customization points per lifecycle event
│ ├── on-create.md
│ └── [event].md
└── validation/
├── schema.yaml ← Machine-readable constraints
└── invariants.md ← Rules that must always hold
| Category | Primitive | Question It Answers |
|---|---|---|
| Context | Scope | Where does this apply? |
| Context | Domain | What are we accountable for? |
| Context | Capability | What specific work happens here? |
| Control | Archetype | Who has authority, and what kind? |
| Control | Policy | What's allowed, and under what conditions? |
| Control | View | What does this role need to see? |
| Interaction | Connector | Where does information come from? |
| Interaction | Binding | Where do outputs go? |
| Interaction | Provenance | Who changed what, when, and why? |
Agents interact with the PDK the same way they interact with skills:
| Level | What Loads | Token Cost | Purpose |
|---|---|---|---|
| 0: Catalog | Frontmatter from each PRIMITIVE.md | ~100/primitive, ~900 total | Route to the right primitive |
| 1: Spec | Full PRIMITIVE.md | ~500–800 | Understand properties, relationships, invariants |
| 2: Skill | One skill file (explain, create, assess) | ~300–500 | Interact with the primitive |
| 3: Context | Examples, hooks, validation | ~200–400 | Org-specific customization |
Total for any single interaction: 1 PRIMITIVE.md + 1 skill + 1–2 supporting files. Not the whole repo.
Seven structured operations replace ad-hoc git commands:
| Operation | Purpose |
|---|---|
| declare | Create a new primitive file and commit it |
| update | Commit a change to an existing primitive |
| connect | Shorthand for declaring a new Connector |
| checkpoint | Tag a safe state before structural changes |
| reset | Return to the last checkpoint |
| commit-file | Stage and commit one file with a plain-language description |
| commit-plan | Progressive disclosure — commit each file from a plan, one at a time |
Commit messages must be complete, human-readable sentences that explain what changed and why — written for someone arriving with no context six months from now.
Good: Add the Google Workspace connector so provenance runner behavior is visible in one place
Rejected: feat: add connector / wip / update file
Enforcement: min 24 characters, max 180, at least 5 words, no conventional commit prefixes, no placeholders. Configured via git hooks.
git clone https://github.com/CobraChickenAI/tml-pdk.git my-coherence-repo
cd my-coherence-repo
make setupThis installs git hooks and agent skills. Then pick your entry point:
- One person? Start with
starters/personal/ - Small team? Start with
starters/team/ - Organization? Start with
starters/organization/ - Client engagement? Start with
starters/client-engagement/
Or run the TML Interview: "I want to map my workflow using TML."
A GitHub Actions workflow automatically appends entries to provenance/changelog.md on every push to main that affects tracked paths. Each entry records timestamp, commit SHA, author, message, touched files, and affected primitive areas. Append-only with duplicate prevention.
This repository is governed by TML. The DECLARATION.json at the root IS a valid TML declaration describing this repo — complete with Scope, Domains, Capabilities, Archetypes, Policies, Connectors, Bindings, and Provenance. The repo practices what it specifies.
| Repository | What It Is |
|---|---|
| themissinglayer | The TML specification |
| tml-discovery-kit | Interview and extraction pipeline |
| tml-catalyst | Content intelligence pipeline |
| tml-hoc | Human Operating Context schema |
| tml-ideaflow | Reference implementation |
MIT — See LICENSE.
Created by Michael Schartung / CobraChicken AI