DEV Community

VANSH ARORA
VANSH ARORA

Posted on

Team Rules for AI Agents, Stored as Append-Only Files in Git

#ai #devtools #vscode #productivity

Shared project knowledge usually needs a shared place to live. For TokenCap v3.0 we wanted that place to be the repository itself, with no server, no account and no sync service. The result is tokencap analyze team, and its storage format is the interesting part.

The layout

Everything lives under .tokencap/team/:

.tokencap/team/
  team.json
  rules/rule-<id>.json
  decisions/decision-<id>.json
  approvals/approval-<id>.json
  profiles/<hash>.json
  adrs/adr-<hash>.json
Enter fullscreen mode Exit fullscreen mode

team.json holds the team name and a schema version. Every rule, decision and approval is its own file, named by a random UUID. A record holds its text, author and creation time. Nothing else is stored.

The commands 

tokencap analyze team init --name "Platform"
tokencap analyze team rule --author "Ava" --text "Changes to auth require review."
tokencap analyze team approve-rule --id <rule-id> --author "Ben"
tokencap analyze team decision --author "Ava" --text "Use local Git records."
tokencap analyze team profile --author "Ava" --text "Owns authentication."
tokencap analyze team sync-adrs
tokencap analyze team status --json
Enter fullscreen mode Exit fullscreen mode

Each write prints the same reminder:

Team intelligence: rule complete. Commit .tokencap/team/ to share it through Git.
Enter fullscreen mode Exit fullscreen mode

TokenCap never runs that commit for you. You do it:

git add .tokencap/team .gitignore
git commit -m "chore: share TokenCap team intelligence"
Enter fullscreen mode Exit fullscreen mode

Why one file per record

The obvious design is a single rules.json with an array in it. It works until two people add a rule on two branches. Both edit the same lines of the same file, and the merge stops for a human.

With one file per record, Ava's rule and Carol's rule are different files with different names. Git merges both branches cleanly because neither branch touched a file the other changed.

Approvals follow the same idea. approve-rule does not edit the rule. It writes a new approval-<id>.json that points at the rule's ID. status reads every approval and reports each rule as proposed or accepted, with the list of approvers. A rule with two approvals has two approval files, and the Git log shows when each one arrived.

Records are never rewritten after creation. The one exception is profiles: each contributor has one profile file, and profile replaces it.

Getting Git to see the directory

Many repositories ignore .tokencap/ entirely, since most of it is generated. analyze team init and analyze team status add a managed block to .gitignore that re-includes only .tokencap/team/. In v3.0 the block re-included more than that, so git add could pick up generated artifacts. v3.1 narrowed it, and running init or status rewrites an old block in place.

What it does not do

TokenCap records evidence. It does not block a commit when a rule is unapproved, and it does not resolve a disagreement between two people. If two engineers propose contradicting rules, both files exist until the team decides what to do about them. That decision is a conversation, and then a commit.

sync-adrs copies your existing architecture decision records into adrs/, one file per ADR, keyed by a hash of its content. Running it twice adds nothing new.

The whole feature is files plus Git. Review it in a pull request like any other change.

Docs and install: tokencap.vansharora.app

Top comments (0)