Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

examples/mcp: add a shared-state config for the anti-pattern 5 case (#587)

Drexd6a0f3db7b44
diff --git a/examples/mcp/README.md b/examples/mcp/README.md
index 08eabaf..f7c7844 100644
--- a/examples/mcp/README.md
+++ b/examples/mcp/README.md
@@ -30,6 +30,7 @@ The local clone/dev path still works if you want to inspect or change the server
| Linear | Read/update issues from state, create follow-up tickets | API key with project + issue write limited to specific teams | Post-Merge, Dependency Sweeper, CI Sweeper |
| Slack (read) | Ingest threads / alerts the loop should triage | Read-only on specific channels | Daily Triage |
| Safe propose flow | Any write action | Loop opens PR / draft / comment. Human merges or approves. | All L2+ patterns |
+| Knos (shared state) | Give parallel loops one state record instead of one STATE.md each | Local only; no network, no account | Anti-pattern 5, PR Babysitter, Daily Triage |
## Example Configurations
@@ -40,6 +41,10 @@ See the files in this directory:
- `github-propose.json` — read + limited write for comments and draft PRs (sign comments as the loop).
- `linear.json` — example for creating/updating issues from loop state.
- `slack-read.json` — ingest channel threads into triage.
+- `knos.mcp.json` — local shared state for parallel loops (`pip install knos`,
+ Python 3.10+). `knos-decisions.example.md` beside it shows the record shape; it
+ is plain markdown, so it reads with nothing installed and the server is only
+ needed for live claims.
- `safe-write-pattern.md` — the recommended architecture for any mutating action.
## Usage in a Loop Prompt (Grok example)
diff --git a/examples/mcp/knos-decisions.example.md b/examples/mcp/knos-decisions.example.md
new file mode 100644
index 0000000..f5df29b
--- /dev/null
+++ b/examples/mcp/knos-decisions.example.md
@@ -0,0 +1,35 @@
+<!-- Example record shape only. Not this repository's state.
+ `knos export` writes this file; live state stays untracked. -->
+
+# Decisions and current work
+
+<!-- Written by `knos export` in an adopting repo. -->
+
+<!--
+Reading this file needs nothing installed: it is plain markdown, and a fresh
+clone picks it up as-is. The live claim/withhold server is a separate, optional
+step - `pip install knos` (Python 3.10+), which the MCP entry launches as
+`python -m knos.mcp`. Without it, everything below still reads normally.
+-->
+
+
+A second clone reads this on its first question — it is one of the decision
+records knos looks for. Nothing here is private: secrets and private paths
+never reach it.
+
+
+## Decisions
+
+- **shared state without schema** — Three loops appending to one unstructured STATE.md causes state rot, conflicting actions and ghost items. One state file per pattern, or clearly separated sections with prune rules. _(docs/anti-patterns.md)_
+- **attempt cap** — No loop runs "keep trying until CI is green". Hard cap at three attempts, then escalate with full context in the state file. _(docs/anti-patterns.md)_
+- **separate verifier** — The agent that implements does not verify its own work. A separate verifier sub-agent or model checks it, and the verifier's default stance is REJECT. _(docs/anti-patterns.md)_
+- **L1 before L3** — Report-only for the first week. Measure triage accuracy before enabling anything that writes. _(docs/anti-patterns.md)_
+- **propose, never merge** — Any loop that changes external state opens a draft PR or a comment for a human gate. It never merges. _(examples/mcp/safe-write-pattern.md)_
+- **minimum privilege** — Loops get the least privilege that works. Prefer read + comment over write; use human gates and worktrees for anything that mutates state. _(examples/mcp/README.md)_
+
+## Being worked on right now
+
+_Nothing claimed._
+
+---
+<sub>knos export. Claims lapse after 30 minutes.</sub>
diff --git a/examples/mcp/knos.mcp.json b/examples/mcp/knos.mcp.json
new file mode 100644
index 0000000..4e31116
--- /dev/null
+++ b/examples/mcp/knos.mcp.json
@@ -0,0 +1,8 @@
+{
+ "mcpServers": {
+ "knos": {
+ "command": "python",
+ "args": ["-m", "knos.mcp"]
+ }
+ }
+}