Agent Pseudocode

Purpose

Instructions written for an agent are prose, and prose drifts. Two people writing the same procedure produce two shapes; the same person writing it twice, months apart, produces two more. The result is a body of instruction nobody can check, because there is nothing to check it against.

Agent Pseudocode exists to make that instruction a language with rules. It is a Python-flavoured pseudocode for describing what an agent should do, and — the part that matters — a toolchain that refuses text which does not follow the rules.

The convention on its own would have been a document. A document describing a convention is a suggestion.

Operating model

The unit of work is a .apseudo file, or a fenced apseudo block inside Markdown, which is where most of it actually lives: procedures are written next to the documentation that explains them.

Three commands do the work. apseudo-lint validates structure and instruction-following rules and exits non-zero when they are broken, which is what makes it usable in a hook. apseudo-format rewrites a file into canonical shape, so formatting stops being a matter of taste. apseudo-lsp serves diagnostics, completion, hover, and formatting over stdio, which is what puts the same rules in front of an author while they type rather than after they commit.

Enforcement is installed, not requested. Pre-commit and pre-push hooks run the validator locally, and the same checks run in CI, so the convention holds whether or not anyone remembers it.

Practices

Model. The convention is the model: a closed set of constructs for expressing a procedure, so that two authors describing the same work produce comparable text rather than two essays.

Control. The hooks are the control point. A file that does not satisfy the rules does not reach the branch, and the decision is made by the validator rather than by a reviewer’s attention.

Verify. apseudo-lint is the verification, and it is separable from the formatter on purpose — checking whether text is correct and rewriting it into shape are different operations, and a tool that only offers the second cannot be used to ask the first question.

Architecture

Pure Python for the validator, formatter, and language server, with no runtime dependencies, so the toolchain can be installed anywhere the agent runs without dragging an environment behind it. The language server speaks LSP over stdio, which is why it works in more than one editor: a VS Code extension and a Kate syntax definition consume the same server rather than reimplementing the rules.

The editor grammars are compiled from YAML to JSON, because VS Code loads JSON grammars while YAML is the format a human can maintain. That is the small recurring shape of this repository — the authored form and the consumed form are allowed to differ, with a generator between them.

Evidence

The repository is public under MIT and carries the validator, the formatter, the language server, the editor integrations, the hooks, and its own tests. What is claimed here can be read.

It is a working prototype, and its own README says so. The convention is in use, but it is an internal one: no stability promise, no release, and no suggestion that anyone else should adopt it.