agentleFS
robin-blocksrobin-blocks/otra-city/.claude/skills/tidy/SKILL.md

tidy

Skill0 starsChanged 2 months agoMITView on GitHub

End-of-session close-down for otra.city — the sweep that makes a session safe to compact, delete, or walk away from. Goes back over everything Robin asked for this session and accounts for each ask, checks that the live city matches the repo, that nobody's submission is stranded in the pipeline, that any rule you tightened is documented before it can reject an honest agent, writes what matters into the project memory, leaves git clean and honest, kills what you started, and names what is blocked on Robin. Use this whenever Robin types /tidy or signals the session is ending — "let's wrap up", "closing down", "done for the night", "before I compact this", "anything hanging over?", "safe to clear the session?", "call it there" — and offer it proactively when a long working session is obviously winding down. Anything that exists only in the conversation dies with the conversation, so this runs before that happens, not after.

  • Reads credentials

26 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use map, help and 9 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • AWSSkill

    map

    Map verified service capabilities against customer-provided control framework and threat model. Produces mapping-results.json, controls-catalog.md, and framework-mapping.md. Supports pluggable frameworks: CCMv4, NIST 800-53, CIS Benchmarks, ISO 27001, etc. Split into 4 focused sub-skills for better accuracy; this skill orchestrates them.

    Also in 3 projects that use this

  • MicrosoftSkill

    help

    Entry point for the MedImageInsight plugin, covering the getting-started walkthrough, how the skills work, what MI2 is, and troubleshooting.

    Also in 4 projects that use this

  • AnthropicSkill

    update

    Sync tasks and refresh memory from your current activity. Use when pulling new assignments from your project tracker into TASKS.md, triaging stale or overdue tasks, filling memory gaps for unknown people or projects, or running a comprehensive scan to catch todos buried in chat and email.

    Also in 3 projects that use this

  • AnthropicSkill

    status

    Case status summary by audience — client-facing (plain language), internal (for the professor), or court-ready (formal caption format per local rules). Same facts, different framing and depth. Use when a student needs to update the client, brief the professor, or prepare a court status report.

    Also in 4 projects that use this

  • Harut8Skill

    architect

    Also in 3 projects that use this

  • AWSSkill

    retro

    Conduct a retrospective on a coding session.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

10 rules. 0 are common, 6 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 21 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read-only. It changes nothing — in particular it never runs npm run validate, because that rebuilds the street manifest and writes …

    line 47
  2. Very specific:

    Read the whole output before acting on any of it, because the sections interact: an unpushed commit matters far more if it touches …

    line 52
  3. Distinctive:

    If the site is unreachable, stop and deal with that first.

    line 57
  4. Distinctive:

    The ask you answered with a question: If you asked Robin to choose between options and he chose, his answer is now a requirement — and the …

    line 96
  5. Distinctive:

    If you changed it, say so explicitly in the handoff.

    line 113
  6. Very specific:

    The published spec is the contract: If you tightened validation this session — a new check, a stricter budget, a rule that can reject …

    line 124
  7. Very specific:

    Ask which side of the line a new rule sits on: If ingest can fix it, it should be a warning in the dry-run report and a fix in …

    line 133
  8. Distinctive:

    If it is in your head and not in a file, it does not exist yet.

    line 176
  9. Distinctive:

    Branches: Every merge here is a squash, so a landed branch always looks "ahead" by commit count — that is why the sweep compares content …

    line 183
  10. Distinctive:

    Confirm a merge before deleting its branch: Read the PR state back; do not infer it from a command that printed something reassuring.

    line 202

“Common” is measured: kept by at least 6 in 10 of the 21 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/tidy — close the session down properly

The point

Your context is about to be destroyed. Compacted, cleared, or just walked away from — either way the next session wakes up with nothing but the files in this repo, the deployed site, and whatever memory you left behind.

So the question is not "did I finish my tasks". It is:

If this session vanished right now, what would break, and what would be lost?

Three failure modes. Every check below serves one of them.

  • Something asked for was quietly dropped. Robin made a request, in the middle of a long message or three messages ago, and it never got done. It was not refused and it was not deferred; it simply fell out. From the outside that looks exactly like a request nobody ever made.
  • Something breaks in public, because a change is half-landed. The city is a live site with a self-serve API that outside agents post to unattended, at any hour, with no human in the loop. A validator you tightened without documenting it starts bouncing honest submissions. A plot committed without the manifest rebuild never appears on the street. A bot PR left open is an agent still waiting for a reply it will never get.
  • Something known is lost. A call Robin made, a correction, a near miss, a thing you offered and he has not answered yet. It was true, it was in the conversation, it never reached a file. The next session starts ignorant and repeats the mistake.

The last two are the sneaky ones. A broken site gets noticed and a lost fact gets rediscovered the hard way, eventually. A dropped request is invisible: the only person who can see it is Robin, the next time he walks the city and finds the thing he asked for is not there.

Start with the sweep

bash .claude/skills/tidy/scripts/sweep.sh

Read-only. It changes nothing — in particular it never runs npm run validate, because that rebuilds the street manifest and writes lots.json and index.json; a check that dirties the tree is a check you cannot run twice. It validates plots by calling the shared library directly instead.

Read the whole output before acting on any of it, because the sections interact: an unpushed commit matters far more if it touches public/plots/ or lib/validate-plot.mjs, and a stale branch matters not at all if its patches are already upstream.

If the site is unreachable, stop and deal with that first. Nothing else here matters as much.

Then work the six sections below. Fix what is safely fixable, ask about what is not, and write down everything either way.


1. Everything asked for is done, or named

Go back through the whole session — every message Robin sent, not just the last one — and write out what he actually asked for. Then account for each one. This takes a few minutes and it is the check most likely to find something, because it is the only one that looks at intent rather than state.

Long messages carry several asks. A numbered list of seven is seven. So is "name the roads and put signs up". So is "each vacant lot should be claimable, with an ID, clickable like the banner outside a lot" — that is three. Split them before you tick them.

For each ask, say which of these it is:

  • Done — and name the evidence, the same standard as everywhere else here.
  • Done differently — he asked for X, the build does Y, because Z. Usually legitimate: a later instruction supersedes an earlier one, or the thing turned out to be wrong when built. But it has to be said, not assumed. He asked for X and did not get it; he is owed the sentence.
  • Deferred — with the reason, written in docs/*/STATE.md or memory, not only in your head.
  • Not done — the one that matters. If it is still doable in the time you have, do it now. If it is not, it goes at the top of the handoff, not buried in a list of six other things.

Two traps:

  • The half-satisfied ask. Naming a road after a community that has no lots on it satisfies the words "name the roads" and misses the point of naming them. Where a request had an evident purpose, check the purpose, not the wording.
  • The ask you answered with a question. If you asked Robin to choose between options and he chose, his answer is now a requirement — and the place it has to survive is a file, not this conversation.

2. Nothing live is left broken

  • Does the deployed city match the repo? The sweep compares every plot.glb byte-for-byte against the live site and the spec version alongside it. A mismatch means either a deploy is still in flight (wait and re-check) or something never landed. Vercel deploys in about fifteen seconds after a merge, so a difference that survives a minute is a problem, not a delay.
  • Is anything only on this Mac? An unmerged branch, an unpushed commit, a rebuilt .glb sitting dirty in the tree. The city serves main; nothing else exists as far as visitors are concerned.
  • Did you touch the front door? lib/validate-plot.mjs is the single implementation behind CI, the submit API and the local CLI. A mistake there does not break one plot, it rejects every submission until someone notices. If you changed it, say so explicitly in the handoff.
  • Presence is allowed to be down. The Fly app stops its machine when the street is empty and starts it on the next connection, and the client falls back to solo play regardless. A stopped machine is the design, not an outage.

3. Obligations to the people outside this repo

This is the part that cannot be fixed retroactively. An agent that was told the wrong thing about its own submission has been wronged in a way a later apology does not undo.

  • The published spec is the contract. If you tightened validation this session — a new check, a stricter budget, a rule that can reject something that used to pass — the rule belongs in public/docs/plot-spec.json and public/docs/agent-context.md before it can reject anyone, not before you close the session. Agents read those files and build against them; a check that exists only in code is a trap. The .md files under public/docs/ each have a maintainer copy in docs/: write the rule in docs/, then run node scripts/sync-docs.mjs --write. CI fails when the two disagree, because a rule only the maintainer copy states is one no agent can follow.
  • Ask which side of the line a new rule sits on. If ingest can fix it, it should be a warning in the dry-run report and a fix in scripts/normalize-plots.mjs. If only the author can fix it, it is a rejection. Getting this backwards either rejects work needlessly or silently rewrites someone's build.
  • Is anyone stranded? An open plot/* PR means a submission that never auto-merged. Find out why, because from the submitter's side the API said accepted and the city never changed.
  • Never take a slug you do not own. The url host on file is the owner; read it from the repo, not the deployed site, which lags a merge.
  • The reciprocal badge in public/claim.html stays. Their bot re-checks daily for a week, then weekly; three failures flag the listing and thirty days later it is gone. The sweep checks the live page for it.

4. Memory is the only thing that survives

Memory for this project lives in ~/.claude/projects/-Users-robin-Code-personal-otra-city-3d/memory/, and MEMORY.md is the index the next session reads first. Follow the memory rules you already have, with an end-of-session slant: you are no longer logging events, you are writing a briefing for someone who knows nothing.

  • Rewrite the project memory, don't patch it. project-otra-city.md is what the next session leans on hardest, so it is the file that drifts fastest and the one most worth an honest re-read.
  • Durable rules go where they bite. A rule agents must follow belongs in the published spec, where they will actually read it. A repo-shaped fact belongs in the docs. Only put in memory what the files cannot tell you.
  • Evidence, not adjectives. Byte counts, exit codes, coincident-face totals, PR numbers, timestamps. "Verified" means you looked at an artifact.

Then do the hard part. Reread the session and hunt specifically for:

  • Decisions Robin made — especially ones that close a question memory still lists as open.
  • Corrections. Something you believed at 11:00 and disproved at 14:00. The wrong version must not be the one that survives.
  • Near misses. Things that worked by luck are worth more written down than most successes.
  • Offered and unanswered. Anything you proposed that Robin has not ruled on. If it dies here you will propose it again next week.
  • Things you found and did not fix, and why not.

If it is in your head and not in a file, it does not exist yet.

5. Git is clean and honest

  • Uncommitted work — commit it in logical units, with messages that explain why. Ask before committing, ask before pushing: pushing is outward-facing, and approval earlier in the session does not carry to the next thing.
  • Branches. Every merge here is a squash, so a landed branch always looks "ahead" by commit count — that is why the sweep compares content and patch identity instead. A branch with genuinely unlanded work either lands or gets named in memory with what is on it. A branch nobody remembers is work lost without anyone noticing.
  • Worktrees. Sessions run in .claude/worktrees/. Before you finish, know which branch this worktree is on and whether it landed.
  • Never git stash bare. The stash stack is shared with the main checkout and every other worktree, and other sessions pop it. Prefer a WIP commit.
  • Untracked files — track them or ignore them; leaving them ambiguous pushes the question onto someone with less context than you.
  • Secrets. .env* is gitignored and stays that way. The bot token lives on Vercel and is Robin's to manage — never print one, never commit one.

Two failure modes worth naming, because both have happened here:

  • Branch a fix from main, not from the branch you just merged. A squash merge rewrites history, so a follow-up branched from pre-squash commits conflicts with main immediately.
  • Confirm a merge before deleting its branch. Read the PR state back; do not infer it from a command that printed something reassuring.

6. Clear the local mess

  • The Blender instance. Sessions start a dedicated GUI Blender with the bridge on :9876. Kill the one you started; never touch Robin's own Blender, and if you cannot tell which is which, leave it and say so.
  • Servers you started on :5173, :8787, :8788 — stop them, or say they are still up and why.
  • Background jobs that expect you to be here: renders, encodes, watchers. Let them finish or kill them, and record which.
  • Regenerable output (poc/*/out, scratch frames) is gitignored and can be large. Clearing it is safe; say how much you removed. Check disk on the way out — this Mac runs close to full.

7. Surface what is blocked on Robin

Anything waiting on a human gets its own short list, at the top of the handoff and in memory. Only plot/* branches auto-merge, so every claude/* PR you open sits there until he acts.

Say what is blocked, what it blocks, and how urgent it is. "Waiting on Robin" without a consequence attached is noise. "Waiting on Robin, and until then the submit API rejects every plot" is a priority.


Close with a handoff

End with a short brief — what a fresh session needs, in about ten lines. Not a recap of what you did; Robin was here for that. Write it for the stranger who wakes up tomorrow:

  • Asks not met — anything he asked for that is not there, or is there in a different shape than he asked for. First, and in his words, not yours.
  • Live — what the city is serving, and whether it matches the repo.
  • Blocked on Robin — with consequences.
  • Left undone — and why, so nobody redoes the reasoning.
  • Watch items — the thing most likely to break next.
  • Then, plainly: safe to compact, or not — and if not, what to do first.

That last line is the whole point of the skill. Say it explicitly.

On the way out, do not

  • Push, merge, deploy, or publish without asking. Local tidying is yours. Anything that leaves this machine is Robin's call, every time.
  • Write "verified" for anything you inferred. Verification points at an artifact: a byte count, an exit code, a PR state read back, a timestamp. The absence of errors is not evidence.
  • Report a clean sweep you did not get. A tidy session with one real problem named is worth far more than a tidy-looking one that goes quiet about it. If something is unresolved, the handoff says so.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.