Knowledge-as-Code (KaC)

Treat validated organizational knowledge as infrastructure — structured in plaintext, version-controlled, and composed on demand by AI into bespoke outputs.

Formula: Foundations + Techniques + Context → Output

Type	What it is	Where it lives
Foundations	Declarative claims about reality. What is true about your business.	knowledge/foundations/
Techniques	Imperative reasoning instructions. How to approach a type of situation.	knowledge/techniques/
Context	The specific situation at hand. This person, this moment.	Provided at generation time. Never stored.

You invest in foundations and techniques once. Context is gathered in the moment. After that, outputs are free.

New to KaC? Read the paper for the full rationale — why templates broke, why AI made it worse, and what this replaces. Then follow the guide to create your first foundation, technique, and output.

Quick start

1. Initialize

knowledge/
├── foundations/       # What is true
├── techniques/        # How to approach situations
└── README.md          # Index of available modules

2. Author foundations

Start with the knowledge referenced by most outputs. Typical first foundations:

• foundation-icp-[segment].md — Who you sell to
• foundation-messaging-core.md — How you position
• foundation-product-[name].md — What you offer
• foundation-brand-voice.md — How you sound
• foundation-competitor-[name].md — Who you compete with

3. Author techniques

Techniques encode how experienced practitioners approach a type of situation. They reference foundations and require context at generation time. A good first technique:

• technique-buyer-persuasion.md — How to structure buyer-facing communications

4. Generate outputs

Provide context + specify which technique and foundations to use:

"Generate a one-pager for the Head of Procurement. The prospect is a €500M industrial company post-merger with 4 ERPs. Early stage. Use technique-buyer-persuasion with all relevant foundations."

The AI follows the technique, pulls from foundations, and produces a grounded, persona-adapted output.

Core rules

1. Never generate outputs without foundations. If no foundation files exist, help the user create them first. Do not substitute general AI knowledge for organizational knowledge.

2. Never leak between types. Foundations = what is true. Techniques = how to approach. Context = this instance. If you're putting "when writing an email, lead with..." in a foundation file, stop — that's a technique.

3. Never fill gaps with assumptions. If a foundation is missing information, flag it. If context is incomplete, ask for it. Outputs are grounded in validated knowledge, not AI assumptions.

4. Separation test. When unsure where something belongs:

   • "Would this be true regardless of what output I'm producing?" → Foundation
   • "Is this guidance for a type of situation?" → Technique
   • "Is this specific to this person, account, or moment?" → Context

5. Date everything. Every foundation file needs a "Last validated" date. Stale knowledge produces stale outputs.

6. Be honest. Foundations must reflect reality, not aspirations. If a competitor is stronger in an area, say so. Honest foundations produce credible outputs.

Using with AI tools

KaC works with any AI system that can follow instructions and reference files:

• Claude Code / Claude: Use skill.md as a custom skill. Invoke workflows with natural language.
• ChatGPT / Other LLMs: Attach system-instructions.md as system context, then provide foundation and technique files with your prompt.
• Custom applications: Parse foundation and technique files programmatically, inject them as context alongside the system instructions.

The system-instructions.md file contains the complete specification an AI needs to work within the KaC system — how to read foundations, follow techniques, handle missing information, and generate grounded outputs.

Repository structure

knowledge-as-code/
├── README.md                          # This file
├── paper.md                           # The rationale — why KaC exists
├── guide.md                           # How-to guide for foundations, techniques, and outputs
├── system-instructions.md             # File specification for AI systems
├── skill.md                           # AI skill definition with workflow triggers
├── workflows/
│   ├── workflow-init.md               # Set up a new knowledge base
│   ├── workflow-author-foundation.md  # Create/improve foundation files
│   ├── workflow-author-technique.md   # Create/improve technique files
│   ├── workflow-generate.md           # Produce outputs from existing files
│   ├── workflow-audit.md              # Review quality/freshness
│   ├── workflow-convert.md            # Transform existing docs into KaC files
│   └── workflow-propagate.md          # Trace impact of foundation updates
└── examples/
    ├── foundations/                    # Example foundation files (fictional company)
    └── techniques/                    # Example technique files (fictional company)

Workflows

Workflow	When to use
Initialize	Setting up a new knowledge base
Author Foundation	Creating or improving a foundation file
Author Technique	Creating or improving a technique file
Generate	Producing an output from existing files
Audit	Reviewing quality, freshness, or consistency
Convert	Transforming existing documents into KaC files
Propagate	Tracing impact when a foundation changes

Examples

The examples/ directory contains foundation and technique files for a fictional company called Meridian Analytics — an enterprise data platform. These demonstrate the structure, separation, and level of detail expected in KaC files. They are not templates — the content is fictional but the structure is real.

Contributing

Contributions welcome. Areas where help is most useful:

• Additional workflow definitions for new use cases
• Example files for different domains (HR, product, customer success, engineering)
• Integrations with specific AI tools and platforms
• Improvements to the file specification

License

MIT — see LICENSE.