prometheus-ai

One set of instructions, skills, and reference docs for coding agents, shared by
Claude Code, Codex, Gemini CLI, Cursor, and dsh (DeepSeek Harness).

Every tool keeps its own config directory, and that is where agent setups drift
apart: the same rule gets written three times, updated twice, and contradicted
once. This repo holds the canonical copy and hands it to each tool through
symlinks, so git pull updates every tool and every project. The dsh preset is
the one exception, because its installer copies files into ~/.dsh/.

The config is read-only for agents. Anything project-specific belongs in that
project's .ai/ directory; shared rules stay project-agnostic.

Supported tools

Requirements

• bash and git.
• node only for the preset YAML check inside agents/dsh/install.sh.
• dsh itself, if you want the dsh preset; the rest of the config works without it.

Install

git clone [email protected]:SrRenks/prometheus-ai.git ~/.config/agent-config
cd ~/.config/agent-config
./setup.sh                    # tool bridges and the git identity include
bash agents/dsh/install.sh    # dsh preset and shared skills (optional)

setup.sh derives every path from its own location and is safe to re-run. A real
file sitting where a symlink will go is copied to backups/<timestamp>/ first, so
nothing is lost.

Keep the clone at ~/.config/agent-config. The paths written inside AGENTS.md
and the skills name that location, and ai-init / ai-context point every project
they touch at it, so a clone somewhere else leaves agent instructions referencing
files that are not there. setup.sh warns when it runs from another path, and
ai-init / ai-context accept AGENT_CONFIG_DIR if you relocate the config on
purpose.

The bridges should resolve back into the clone:

for b in ~/.claude/CLAUDE.md ~/.codex/AGENTS.md ~/.gemini/GEMINI.md ~/.cursor/rules ~/.agents/AGENTS.md ~/.local/bin/ai-init; do
  [ -L "$b" ] && echo "ok       $b -> $(readlink "$b")" || echo "MISSING  $b"
done

The .ai/ directory

Every project gets its own .ai/: the agent's working memory for that project,
local to the machine and never committed. This is the other half of the
read-only model. The shared config holds what is true for all projects, and
.ai/ holds what is true for one of them.

cd ~/Projects/my-app
ai-init      # creates .ai/, links ./AGENTS.md, adds the .gitignore entry
ai-context   # writes context topic files and the project README, once the project has content

How it behaves:

• The shared rules arrive by symlink. Editing AGENTS.md here updates
  .ai/agents.md in every project at once, and no project keeps a copy to drift.
• ai-init also links ./AGENTS.md in the project root, which is the path Codex,
  Cursor, Windsurf, Amp, Jules, and Claude Code look for.
• .ai/ stays out of git. ai-init writes the entry into the project's
  .gitignore, so project knowledge never enters the repository's history and
  never reaches a teammate who does not need it.
• ai-init records project maturity. It reads git history and build files and
  stamps the result (NEW or EXISTING) into context/index.md, which decides
  whether the agent onboards first or starts building.
• Nothing is generated from a blank template. ai-context writes only the files
  that apply, so a project with no database gets no database.md and no storage
  row in the README.
• Files already written are left alone. --force refreshes only index.md and
  README.md, which keeps hand-written knowledge safe from a re-run.
• Topic files open with detected facts and explicit open questions. Answers
  replace the questions as they are confirmed, so the knowledge base grows out of
  real sessions instead of placeholders.
• Project rules win. When a project needs different behavior, the rule goes in
  .ai/project.md; shared rules never bend to fit one project.
• .ai/ holds the agent's working memory for one project. Technical
  documentation that humans read, such as architecture and design decisions,
  belongs in the repository's committed docs/ under the
  core/docs/project-docs.md standard. .ai/docs/ holds only genuine deviations
  from the shared config; when the shared config already covers a convention,
  reference it instead of copying it.
• The memory loop closes at the end of a task: session state goes into
  session.md, new decisions append to assumptions.md, and finished notes are
  pruned from scratchpad.md, so the next session starts oriented.

core/docs/ai-directory.md is the full standard, including when a .ai/docs/
file is worth creating instead of a line in project.md.

Repository layout

AGENTS.md              universal rules, no tool-specific content
setup.sh               installs every tool bridge on this machine
ai-init, ai-context    per-project tooling (linked into ~/.local/bin)
core/
  docs/                reference library, read on demand
  principles.md        universal agent principles
  templates/           .ai/ and project-docs skeletons
agents/
  claude-code/         CLAUDE.md, settings.json, hooks/, rules/, commands/
  gemini/              GEMINI.md
  dsh/                 install.sh and presets/renks/
tools/
  build-preset-recipe.mjs   regenerates the dsh preset baseline, patch and fallback
skills/                one procedure per directory, each a SKILL.md
.gitignore             keeps backups/, evals/, and a stray gitconfig out of git
README.md, LICENSE     this file and the license

core/docs/repository-map.md is the structure doc: every root file, the tool
adapters, the reference library, and the templates.

How one config reaches every tool

• skills/ is symlinked to both ~/.claude/skills and ~/.dsh/skills. Every
  skill carries name and description frontmatter following the Agent Skills
  standard, and the trigger phrasing lives in the description because that is the
  field both tools pick a skill from. Both read the same directory plus SKILL.md
  layout. The Claude slash commands in agents/claude-code/commands/ are
  symlinks into this directory.
• Files in agents/claude-code/rules/ carry description with globs for
  Cursor and paths for Claude Code, so one file serves both.
• ai-init links ./AGENTS.md into each project, which is the path Codex,
  Cursor, Windsurf, Amp, Jules, and Claude Code look for.
• Editing a rule and pulling updates every tool and every project, because the
  bridges are symlinks. Only the dsh preset needs its installer re-run.

dsh and the renks preset

dsh (DeepSeek Harness) is the harness this config is tuned against. It runs the
agent loop locally, loads the shared rules from the ~/.dsh/AGENTS.md symlink,
and discovers procedures from ~/.dsh/skills, which points at skills/. It is
also the one tool here whose prompt composition can be patched, which is why the
leaner delivery lives in a dsh preset instead of in the shared rules.

The stock dsh recipe injects the full instruction files and the whole skill
catalog into the first request of every session. That spends context before any
work happens, and it moves the model's first step: the retained anchor checks
measured 0 of 9 first requests anchored with the catalog injected and about 81
percent without (core/docs/evals.md, issue #6).

The renks preset keeps the same rules and skills while removing both
injections:

compaction-epoch.mjs backs the hint and the gate. It tracks the compaction
boundary so a promotion signal recorded before a compaction does not count after
it. The plugins import only each other, never dsh internals, so an upstream
release does not break them.

Why the gate exists

A hint is one message among many, and the rules that matter are cross-references:
AGENTS.md names complexity.md, maintainability.md and git-workflow.md in
a read-on-demand index, and a hint saying "instruction files exist" loads none of
them.

An audit over the 96 recorded sessions in ~/.dsh/sessions (tools/audit-instruction-reads.mjs) measured the result:

Of the sessions where the hint did land, the median delay before the read was two
tool calls: the first edits happened before the rules were in context. The hint
fired; nothing enforced it.

Replaying those same transcripts against the gate's own classifier is the
strongest argument for enforcing at the tool call rather than in a message: of
the 84 sessions that mutated anything, 83 (99%) made their first mutation
before reading the set, at a median of 3 tool calls in, and 51 of them mutated
within the first 5 calls. The window in which a hint could plausibly work is
routinely zero to three calls.

docs-gate.mjs observes tools/pre-execute - the waterfall dsh-tools runs
before every tool body - and denies a mutating call until the session has read
core/principles.md, core/docs/complexity.md, core/docs/maintainability.md,
core/docs/git-workflow.md, core/docs/development-workflow.md, and the
project's .ai/project.md when it exists. The denial reaches the model as the
tool result, so the corrective instruction arrives exactly where the model is
looking.

What it deliberately does not do, since a gate that blocks real work is worse
than no gate:

• It never gates a read-only call. read, grep, glob, web_search,
  todo_write, skill_load, subagent dispatch and read-only bash (git status, git diff, test runners) stay open, so the agent can explore and can
  satisfy the gate.
• It never gates a target outside the workspace: an edit at an absolute path
  elsewhere, or a bash redirection into /tmp.
• It never gates an uninitialized workspace. If no required doc exists - a fresh
  scaffold, a scratch directory, a machine without this checkout - the gate opens
  and says so.
• It never re-gates: once the set is read, the check is one Set lookup.
• A subagent inherits its root session's evidence instead of re-reading five
  files, and an unresolvable workspace fails closed rather than silently
  disabling the gate.

docs-gate.spec.mjs is the test suite, and one of its cases pins the enforced
set to the set instruction-hint.mjs advertises, so the promise and the
enforcement cannot drift apart:

node --test agents/dsh/presets/renks/docs-gate.spec.mjs

A dsh update stays a merge, not a rewrite. The repo commits no copy of the stock
recipe; agents/dsh/presets/renks/ holds three parts:

• stock-baseline.agent.cordis.yml is the merge base, kept byte-identical to the
  installed stock standard recipe.
• agent.cordis.patch is the personal delta, the swaps above.
• fallback.agent.cordis.yml is the last-known-good generated recipe.

All three are generated by tools/build-preset-recipe.mjs, which reads the stock
recipe for the dsh version actually installed and rewrites the set from it. The
baseline used to be hand-frozen, which meant an upstream persona rewrite made
every install fall through to the fallback - a change to the patch could not
reach the machine at all. Now install.sh detects that case, regenerates the
recipe and merges again, so the upgrade path is self-healing:

node tools/build-preset-recipe.mjs          # regenerate baseline + patch + fallback
node tools/build-preset-recipe.mjs --check  # verify only; non-zero on drift

agents/dsh/install.sh 3-way merges the patch onto whichever dsh version is
installed, validates the YAML and the plugin rows, and installs the fallback only
when even a regenerated patch cannot merge. It also links ~/.dsh/AGENTS.md and
~/.dsh/skills into this repo and sets agent-presets.default: renks in
~/.dsh/settings.yaml. After a dsh upgrade:

git pull && bash agents/dsh/install.sh

A dsh upgrade installs into a new pnpm directory and prunes the old one, which
leaves the links an earlier version wrote into ~/.dsh/profiles/node_modules
pointing at nothing. They are inert, and removing them is safe:

find ~/.dsh/profiles/node_modules -type l ! -exec test -e {} \; -print

On-demand search stays the default as the skill list grows. Injecting the catalog
only pays off while there are a handful of skills, so it should not come back
past roughly three to five.

What agents are told

AGENTS.md is the contract every tool receives: 95 lines covering scope and
ownership, non-negotiables, project entry, the CRISPY workflow, memory files, the
no-go list, and tool usage. Read it directly for the rules; depth lives in
core/docs/, which agents load on demand.

The workflow

The config names its workflow CRISPY, after the ZenML LLMOps Database entry cited
in core/docs/sources.md. The shape here is the earlier Research, Plan, Implement
method that entry evolved from: three phases, each ending in a gate.
core/docs/development-workflow.md has the detail.

• Analysis. Classify the project as NEW or EXISTING, survey the repository, and
  write a numbered plan with success criteria for anything multi-file or
  uncertain. Assumptions land in .ai/assumptions.md. Gate: the plan is approved
  before implementation starts.
• Implementation. One task at a time, tests written before the code, diffs that
  trace back to the request, complexity budgets checked as work proceeds, linters
  and tests clean before moving on. Gate: budgets, linters, and tests pass.
• Review. Self-review the diff, then one ruthless edit of your own diff to remove
  dead code, abstractions, and noise comments. The result goes to a fresh-context
  reviewer, a subagent or second session that does not share the conversation, to
  hunt bugs, overreach, and unintended changes. Then the validation checklist and
  the prose scan. Gate: human approval before the commit.

The separate context is the point of the review step: a reviewer working from the
same session inherits the author's assumptions.

Guardrails

Claude Code gets two hooks, wired in agents/claude-code/settings.json:

• block-danger runs before a Bash call and denies a fixed list: recursive
  deletes, sudo, git push --force, chmod 777, raw disk writes (dd,
  mkfs, > /dev/sda), and git add -A or git add ., which the shared rules
  ban for every tool.
• lint-check reports lint output after a file write or edit, for Python, Go, and
  Rust files whose linter is installed. It lowercases tool_name before comparing,
  so the Write|Edit matcher in settings.json reaches it.

session-init is the one piece that waits to be asked for. It would create .ai/
wherever a session starts, which surprised projects that chose not to initialize,
so it ships unwired, with the snippet to wire it at the top of the file.
claudeignore is wired by setup.sh as ~/.claudeignore: .env files, keys,
credentials/, secrets/, *.tfstate, *.tfvars, and build or vendor
directories are never opened.

settings.json also carries the permission lists. A set of routine commands is
pre-approved: builds, tests, git read commands, file inspection, and network
fetches. Denied outright: git push, every rm, git add -A, sudo,
chmod 777, chown, shutdown, reboot, mkfs, and dd.

The shared rules carry the git-add ban for every tool. The destructive-command
list lives only in the Claude Code hook and its settings, so other tools do not
inherit it.

Skills

Reference docs

core/docs/ is shared across projects and never copied into one. The table
below lists the docs people reach for most; AGENTS.md section 3 is the entry
point and names every shared doc with its path.

core/docs/repository-map.md describes the full layout, including the language
guides in core/docs/languages/ and the ADR template in core/docs/decisions/.

core/principles.md sits outside core/docs/ and holds the behavior rules an
agent loads before planning: Karpathy-style rigor plus operational rules such as
one task at a time and never committing without approval, complexity budgets, and
the anti-patterns list.

Git identity

Identity is per machine, never tracked:

• ~/.config/git/identity holds your user.name and user.email, mode 600.
• ~/.gitconfig includes it conditionally for ~/Projects/** and ~/.config/**,
  so personal and work directories can resolve differently.
• setup.sh creates the file from your existing global config if it is missing,
  and falls back to YOUR NAME / [email protected] on a machine that has none,
  which you edit before the first commit.

Auth stays at the SSH level and out of git config. core/docs/git-workflow.md
covers the resolution order.

Extending the config

1. Load core/docs/agent-config-authoring.md, or run the extend-config skill.
2. Write the file following its format rules: imperative bullets for rules,
   numbered steps for skills, headers and bullets for reference docs.
3. Run the wiring checklist: new docs go into AGENTS.md section 3, structure
   changes into core/docs/repository-map.md, new claims into
   core/docs/sources.md.
4. Commit with a conventional message, one logical change per commit, staging
   explicit files only.

Validation

Run before finishing any change to this config:

for f in setup.sh ai-init ai-context agents/dsh/install.sh; do bash -n "$f"; done  # shell syntax
for f in agents/dsh/presets/renks/*.mjs; do node --check "$f"; done                # plugin syntax
node --test agents/dsh/presets/renks/docs-gate.spec.mjs                            # gate behaviour
node tools/build-preset-recipe.mjs --check                                         # preset recipe in sync with installed stock
find . -type l ! -exec test -e {} \; -print                                        # broken symlinks
python3 -c "import tiktoken,pathlib; e=tiktoken.get_encoding('o200k_base'); print(sum(len(e.encode(pathlib.Path(p).read_text())) for p in ('AGENTS.md','agents/claude-code/CLAUDE.md')))"  # injection budget

Each check needs its own loop: bash -n and node --check only inspect the
first file they are given. The last check needs tiktoken (pip install tiktoken), which is not a repo dependency. It measures what a first request
carries: 2460 tokens on 2026-09-16 against the ~2.5K ceiling, so roughly 40
tokens of slack (core/docs/evals.md).

Skill frontmatter needs name and description, with name matching the
directory. Rule frontmatter needs description, globs, and
paths. Both blocks must parse as YAML: a colon inside an unquoted value ends
the scalar and the loader drops the file without an error, so quote any value
that contains one. The dsh patch flow keeps
agents/dsh/presets/renks/stock-baseline.agent.cordis.yml plus
agent.cordis.patch byte-identical to fallback.agent.cordis.yml; the three
are generated together by tools/build-preset-recipe.mjs, and --check
reports drift. See agents/dsh/presets/renks/README.md.

Prose in the README, docs, comments, and commit messages is checked against
core/docs/ai-writing.md, which lists the vocabulary and sentence patterns that
make text read as machine output. It applies to prose written into files humans
read; chat replies and .ai/ files are exempt.

Provenance is checked too: a new rule or numeric threshold needs an entry in
core/docs/sources.md with a retrieval date, and the rule doc ends with a
Sources: line naming the sections that justify it. Anything without a source is
labeled repo design or community practice.

The checklist an agent runs before declaring a task done is a separate document:
core/docs/validation-checklist.md.

Status

Used daily on this machine across Claude Code, Cursor, and dsh. The dsh preset
tracks whichever dsh version is installed through a patch instead of freezing a
copy of the upstream recipe.

Changes to the default preset or the shared rules face the retained eval set in
core/docs/evals.md first: anchor checks that always run, plus a task set for
substantive work. The gate is that success rate does not drop and cost per solved
task does not rise materially. Public benchmark scores are not treated as
evidence.

License

MIT. See LICENSE.

Sources and acknowledgements

This config is assembled from other people's work. core/docs/sources.md records
every source with its retrieval date and what it backs, split between the sources
behind specific rules and the practitioner writing that shaped the stance. The
people below are the ones it leans on most.

• Fabio Akita (akitaonrails), for the position that AI-assisted work ships under
  the same review standard as any other code, and for ai-memory, an independent
  build of the same idea behind .ai/: agent memory as versioned markdown, with
  writes gated by evaluation.
• Robert C. Martin and Justin Martin. The function rules in Clean Code (small
  functions, one thing per function, few arguments, one level of abstraction)
  state in prose what this repo enforces in numbers; Clean Architecture covers
  dependency direction. Their Clean AI: Agentic Discipline series makes the
  argument the guardrails act on: discipline an agent cannot be trusted to
  remember belongs in the tooling.
• Andrej Karpathy, for the llm-rigor principles: think before coding, surgical
  changes, minimum viable code, and pushback that scales with certainty.
• HumanLayer, for the Research-Plan-Implement to CRISPY talk, which supplied the
  CRISPY name and phase structure, and the argument that always-on prompt budget
  is scarce.
• Anthropic, for Claude's Character and the sycophancy research behind the
  non-negotiables, the context engineering guidance behind the lean injection
  policy, and the skills pattern that skill_search mirrors.
• Matt Pocock, for publishing his own agent skills, a working reference for how a
  skill directory and its frontmatter should look.
• Martin Fowler and Kent Beck, for the test pyramid and self-testing code that the
  testing rules follow, and for writing about augmented coding as it develops.
• Thomas McCabe and G. Ann Campbell, for the two complexity metrics this repo
  budgets against, and the maintainers of zj-karina/complexity-budget for the
  numeric budgets themselves.
• Google, for the developer style guide, the engineering practices on code
  review, and the SRE postmortem culture.
• Simon Willison, for documenting in public what agent tooling does in practice,
  failure modes included, and for naming the lethal trifecta behind the guardrails.
• Jesse Vincent, whose superpowers project is the working reference for shipping
  one skill set to several harnesses at once.

Papers, standards, and studies behind the rest of the rules are listed in
core/docs/sources.md: among them the Agent Skills standard that this repo's
SKILL.md format follows, the Wikipedia WikiProject AI Cleanup essay on the signs
of AI writing, the ETH Zurich study on instruction bloat and inference cost, the
METR trial on measured developer productivity, the DORA report on AI as an
amplifier, OWASP's application and LLM top tens, Jakob Nielsen on AI usability,
Diataxis, Keep a Changelog, Conventional Commits, and the work of Parnas, Yourdon
and Constantine, Feathers, Nygard, Knuth, and Chroma. If a rule here misstates
its source, or a source is missing, the fix belongs in that file.

Named after the Prometheus Circuit in Chrono Trigger, the machine that directs the
others and answers to the people who keep it.

Thank you all. Long live knowledge and open source. =)