Bottling the secret sauce: how to stop cooking spaghetti in every project

Every team has a secret sauce. The problem is that nobody wrote down the recipe.

Six months into a new project the new developer asks: “why do we log errors this way?” and the answer is always some variation of “because Marco knew best, and Marco left in January”. The knowledge lives in someone’s head, in a Confluence page nobody has touched since 2021, or — most commonly — scattered across ten years of pull-request comments that you would have to be a forensic archaeologist to reconstruct.

Meanwhile, the codebase has quietly become spaghetti. Not because the engineers were bad. Because there was no shared, enforced recipe.

The spaghetti problem is not a skill problem

You can hire the best engineers in the world, point three different AI coding models at the same repository, and still end up with spaghetti. Each model has its own defaults, its own taste in error handling, its own opinion on how a CLI should behave. Each new project starts from a blank page. Every team solves the same problems slightly differently, and those slightly-different solutions accumulate into the kind of codebase where touching one corner breaks something three folders away.

The real problem is the absence of a shared, machine-readable recipe that travels with the project and survives team changes, model updates, and the passage of time.

If the rule is not written down and automatically applied, it will eventually not be followed.

The secret sauce, bottled

stdix is a small CLI tool that does one thing: it connects your project to a registry of versioned engineering standards and materialises the relevant rules into the files your AI agents already read.

No runtime. No daemon. No cloud dependency. A single static binary that compiles with CGO_ENABLED=0 and runs on Linux, macOS, and Windows — x86 or ARM.

The idea is simple:

You write the rules once, in a YAML file. You push the YAML to a registry. Every project that applies that standard gets the same rules, in the same format, in whatever agent-instruction files the team uses.

id: python.cli
title: Python CLI Standard
version: 1.0.0
language: python
tags: [cli, terminal]
applies_when:
  - building a CLI application
rules:
  - Use Typer for CLI command definitions.
  - Use Rich for terminal output.
  - Use pathlib instead of os.path.
  - Every command must support --help.
  - User-facing errors should be formatted clearly.

That is the whole ingredient list. No magic, no framework, no vendor lock-in.

What do I need to make this recipe?

• stdix binary — one download, zero runtime dependencies
• A .stdix.yaml in your project root (created by stdix init)
• A registry: either the public one at github.com/codref/stdix-registry or your own private fork
• Optionally: a STDIX_REGISTRY_TOKEN GitHub token for pushing standards back

That is it. No Node, no Python, no Docker, no special CI runner. If you can run a shell command you can run stdix.

The quick start (TL;DR)

# 0. Install stdix
curl -fsSL https://raw.githubusercontent.com/codref/stdix/main/install.sh | sh

# 1. Initialise stdix in your project
stdix init --registry-url https://github.com/codref/stdix-registry/releases/latest/download/registry.db

# 2. Pull the registry index
stdix sync

# 3. Find what applies to your work
stdix match "build a Python CLI app" --lang python

# 4. Apply a standard — writes .stdix/standards/python.cli.md
stdix apply python.cli

# 5. From now on, keep everything up to date
stdix deploy

After step 4 every AI agent that reads your project’s instruction files picks up the rule set automatically. Cursor, Copilot, Claude, Codex — it does not matter which one you or your colleagues prefer today or tomorrow.

Real use cases

Onboarding a new model

Your team has been using Cursor for a year. Someone brings in Claude for a specific refactoring task. Without stdix the new model starts from scratch and invents its own conventions. With stdix it reads .stdix/standards/ on the first prompt and immediately works within your established patterns.

Same story when OpenAI releases a new model and you want to evaluate it: the standards travel with the project, not with the model.

Multi-team monorepo

A platform team owns shared.errors and shared.logging. Product teams own python.cli, go.service, and node.api. Each team maintains its standards in the registry. Every project that applies them stays consistent — automatically — even as the standards evolve.

# Platform team applies shared conventions
stdix apply shared.errors
stdix apply shared.logging

# Product team adds their own
stdix apply python.cli

When the platform team bumps shared.errors to version 1.1.0, every product team runs stdix sync && stdix deploy and gets the update.

Contractor handoff

A contractor delivers a Go service. Before signing off they run:

stdix apply go.service
stdix apply shared.logging
stdix deploy

The next engineer who opens the project — whether human or model — finds a .stdix/standards/ folder with clean, readable rules that explain every non-obvious convention in the codebase. No archaeology required.

Private standards for proprietary patterns

Not every secret sauce belongs in a public registry. Fork codref/stdix-registry , set registry.repo in .stdix.yaml, and your company’s internal standards stay behind your own access controls. The workflow is identical; only the registry URL changes.

# .stdix.yaml
registry:
  source: remote
  url: https://github.com/myorg/standards/releases/latest/download/registry.db
  repo: myorg/standards

Extracting the secret sauce — with or without an agent

The hardest part of stdix is not the tooling. It is writing down what you already know.

A useful trick: point an AI agent at an existing codebase and ask it to extract the implicit conventions. Something like:

“Read this repository and produce a stdix-compatible YAML standard that captures the error handling, logging, and CLI patterns the team uses.”

If you use GitHub Copilot, stdix ships a purpose-built agent for exactly this step. Run it once inside your registry project:

stdix scaffold
# → installs .github/prompts/new-standard.prompt.md

After that, the /New stdix Standard Copilot agent is available in any chat session on that project. Describe the subject, attach example code or an existing YAML, and the agent drafts a well-structured standard, saves it, and runs the registry validation — all in one conversation.

The result is a draft YAML. You review it, bump the version, and push it:

# Review and edit the generated YAML
$EDITOR .stdix/local/python.cli.yaml

# Push it to your registry
stdix push .stdix/local/python.cli.yaml --message "extract CLI patterns from legacy project"

Once it is in the registry, every future project starts with those patterns already in place — instead of re-discovering them from scratch six months later.

The agent does not need to understand the why behind the patterns. It just needs to observe what the team consistently does and write it down. You bring the judgement; stdix brings the distribution.

Customising without losing your upstream

Registry standards are a starting point, not a straitjacket. If python.cli from the public registry is 80 % what you want, fork it locally:

stdix override python.cli
# → creates .stdix/local/python.cli.yaml

$EDITOR .stdix/local/python.cli.yaml
# Add a rule: "Use pytest with 80% minimum coverage."
# Bump version: 1.0.0 → 1.0.1

stdix deploy
# → uses your local version, ignores the registry copy

When you are happy with the changes, push them back:

stdix push .stdix/local/python.cli.yaml

Or push an entire folder of customised standards at once, with a confirmation recap before anything touches the registry:

stdix push .stdix/local/ --message "team python standards v1.1"

# Files to push to myorg/standards (branch: main):
#
#   .stdix/local/python.cli.yaml      →  standards/python/cli.yaml
#   .stdix/local/python.testing.yaml  →  standards/python/testing.yaml
#
# Push these files? [y/N]

The challenges

Let us be honest about where the friction is.

Writing the first standard is the hardest step. Extracting implicit knowledge into an explicit YAML is work. The good news: you only have to do it once per pattern, and an agent can do most of the drafting.

Standards drift if nobody owns them. A registry needs a maintainer, even if that maintainer is a team rather than a person. Treat standards like you treat dependencies: pin versions, review changes, deprecate old ones.

Rules that are too prescriptive become noise. A rule like “use Typer” is actionable. A rule like “write clean code” is not. Keep the list short and specific. Ten concrete rules that get followed are worth more than fifty abstract ones that get ignored.

You cannot automate judgement. stdix distributes rules; it does not enforce them at runtime. An agent that ignores its instruction files will still ignore them. The value is in making the right path the obvious path, not in making the wrong path impossible.

The opportunity: a progressively growing registry

The public registry starts small and grows as the community contributes. Fork it, add your standards, open a PR. Or keep your fork private and benefit from the public base while protecting what is proprietary.

The registry is designed to be composed:

# Shared platform conventions
stdix apply shared.errors
stdix apply shared.logging

# Language-specific patterns
stdix apply python.cli
stdix apply python.testing

# Framework-specific additions (contribute them when you have them)
stdix apply python.fastapi      # not in the public registry yet — add it

Every standard you contribute makes the starting point better for the next team. Every fork that feeds improvements back upstream makes the public base more complete. The spaghetti problem does not have a single solution; it has a thousand small solutions that compound over time.

Language agnostic, model agnostic, tool agnostic

stdix does not care what language you write in. A standard is a list of rules in a YAML file. If you can describe the rule in a sentence, you can encode it. Go, Rust, Python, TypeScript, Terraform, SQL — the format is the same.

It does not care which agent you use. The output is plain Markdown in files that Cursor, Copilot, Claude, and any future model can read. If tomorrow your team switches models, the standards stay.

It does not require a specific OS, container runtime, or package manager. Copy the binary. Run it. That is the entire installation story.

curl -fsSL https://raw.githubusercontent.com/codref/stdix/main/install.sh | sh

A word on the registry CI

The registry is not a static folder. Every push triggers stdix-build, which validates all YAML files and produces a new registry.db artifact:

# On every PR — validate
stdix-build validate --registry ./standards

# On merge — publish
stdix-build build --registry ./standards --out registry.db --version 1.2.0

registry.db is a single JSON file, pre-indexed for BM25 search. Projects download it with stdix sync and query it offline. No API, no authentication, no rate limits.

The bottom line

Spaghetti code is not inevitable. It is the natural result of knowledge that is never written down, never shared, and never enforced. stdix does not solve the problem of bad engineering — nothing does — but it solves the problem of undistributed good engineering.

Write the recipe once. Bottle it. Let every project, every model, and every new team member start with it already in the pantry.

The public registry is at github.com/codref/stdix-registry . The tool is at github.com/codref/stdix . Both are open to contributions.

The secret sauce stops being secret the moment you write it down. And that is exactly the point.