ToppingOut05 · Skills and agentsSkills and agents
Every skill and agent: what it does, when to use it, how to tell it worked. All on one map: the Skill Atlas.
Coding agents can read a plain-text copy of each page.
- Does
- Write down a rough idea and its open questions, before anything is decided.
- When
- When you have an idea worth writing down but you're not ready to decide anything about it yet.
Say it
capture this ideaspec this concept out
Not forDecision-complete work (f-blueprint), settling decisions (f-survey), a job's own plan (the foreman's PLAN.md), or single Logbook cards (f-card).
It's working if
- It wrote exactly one file,
foreman/ideas/IDEA-YYYY-MM-DD_<short-slug>.md, or placed it inside an existing idea directory and said so. - The file opens with a title, a date, a status saying the discussion is open, a banner saying it is not a plan of record and not executable, and one line on where it came from.
- Settled points appear as
A0…agreements and open questions asQ0…, with the options as they were discussed, not resolved. - Nothing in it was invented: no locked decision tables, no ordered tasks, no answers to questions you never answered.
foreman/blueprints/README.mdhas one new bullet for it in the Ideas section, naming what blocks promotion.- The report gives the path, a one-line summary, the counts of agreements, open questions and rejected options, and the blocking questions.
- It opened no job, wrote no plan or code, and staged, committed and pushed nothing.
The full page →Sample, common questions and what it connects to.
- Does
- Turn a rough request into clear decisions, one round of questions at a time.
- When
- When a request is still vague or has open choices, before anyone writes the plan.
Say it
survey thisgroom thisthis is still vaguetighten this before we buildwhat am I missingsurvey this out loud
Not forThe site walk (the machine check at the start of a job, METHOD §2). Not for writing the plan (f-blueprint) or cutting it into tickets (f-schedule).
It's working if
- Each round opens with the survey layout: your call, settled by the foreman, on site, next round.
- "Your call" holds at most three questions, each with the recommended option first and starred.
- Anything the code or the evidence can answer sits under "Settled by the foreman", with the evidence named, not as a question to you.
- No question in a round depends on another question still open in the same round.
- It stops asking once another answer would only tune implementation detail.
- It ends with one self-contained commission block: in scope, out of scope, acceptance criteria, decisions with their reasons, the likely lane and the exact next action (
/f-blueprint <topic>, or park it). - It created no job, plan, code or commit along the way.
The full page →Sample, common questions and what it connects to.
f-blueprint
- Does
- Write the full plan once every decision is made.
- When
- When every choice is settled and it's time to write the plan for the whole project.
Not forOpen decisions (f-survey), not for cutting into tickets (f-schedule), not for building.
It's working if
- It wrote exactly one file,
foreman/blueprints/ready/BLUEPRINT-YYYY-MM-DD_<short-slug>.md, with a status ofreadyorblocked-on-decision. - The plan names the head, the locked decisions (
D0…), the verification points, the ordered tasks (T0…) and every assumption, HALT and outward item, with research and owner decisions listed as such, not hidden inside a task. - Every unresolved row carries a default if silent, or
HALT until decided. - Each task names the paths it owns, its prerequisites, its outcome, what it traces to, and a verify step that uses a gate the repo already has.
- The plan ends with a
## Plan check findingsheading and an empty findings table, ready for/f-plancheck. foreman/blueprints/README.mdhas a Ready entry for it, usually saying it needs/f-plancheck.- It implemented nothing, opened no job, did not run
/f-plancheck, and staged, committed and pushed nothing.
The full page →Sample, common questions and what it connects to.
f-plancheck
- Does
- Have AI models from other companies read the plan fresh and point out problems.
- When
- After a plan is written and before it's split into jobs; also on a job's own plan before its second work order.
It's working if
- Before picking seats, it prints who wrote the plan and which model family is excluded, so no seat comes from the author's own family.
- On an attended run, it opens a one-shot picker in your browser and posts the picker's link in chat; nothing is dispatched until you have picked 1 to 5 seats.
- Each seat gets the ticket's own words and checks every decision against them as well as against the code.
- It reports the findings of the mechanical checks (paths,
file:linecitations, CLI flags, measurements, the Done-when block) as findings, without fixing them. - It writes
findings.mdin a fresh scratch folder: one block per defect, each with where, which seats raised it, the evidence, and an empty Disposition line. - Findings that change what is built sit in their own section, marked DO NOT ACT and left for your decision, with no suggested fix, and the report shows each of them to you in full.
- The plan is untouched apart from one
gate: plancheckline, which a plan in or headed forforeman/blueprints/ready/always gets. - It staged, committed and pushed nothing.
The full page →Sample, common questions and what it connects to.
f-schedule
- Does
- Split a big plan into jobs, in order, and draw the project board.
- When
- When a plan has passed the plan check and is ready to be split into jobs.
Say it
break this plan into ticketsdecompose this into jobsturn this plan into a project
Not forWriting the plan (f-blueprint), not for planning one ticket's job (the foreman's scoping + PLAN.md), not for board updates after that (f-board).
It's working if
- On a plan without the
gate: plancheckline, it stops and tells you to run/f-plancheckfirst. A findings row with a blank fate stops it too. - Before writing anything, it shows you the head, the job table, the decision jobs, any unmapped verification points or tasks, any disagreements, and the job it recommends first.
- It writes nothing until you say "go" for the project.
- Research and owner decisions are their own jobs, never hidden inside another: a question that ends in your answer is a decision job; research that produces a file is a build job and goes through a PR.
- Every verification point is carried by at least one job, and every plan task maps to a job or to "not carried, on purpose" with its reason.
foreman/projects/<slug>/holdsPROJECT.md, one ticket file per job with the acceptance quoted and a "Why this job" that says in plain sentences what the job makes possible, never only its plan task, and aBOARD.jsonthatrender_board.pyvalidated and rendered.- Each job on the board has a summary: one plain sentence saying what it builds, taken from the blueprint task's Outcome, with plan references after it in brackets, never a summary of references alone.
- It committed nothing, and never deleted or rewrote the source plan.
The full page →Sample, common questions and what it connects to.
- Does
- Start a session as the foreman: read the role, the rules and the playbook first.
- When
- At the start of every foreman session, before looking at any ticket.
Say it
you are the foremanbe the foremanset up as foreman
Not forThe builder's side (the builder gets work orders, never this skill), not for cutting a plan into tickets (f-schedule), not for updating the board (f-board).
It's working if
- If the last job's close-out isn't finished, it stops at the end-game lock and names the missing steps.
- It reads the method files in full:
README.md,RULES.mdwith its "Foreman rules" section,METHOD.md,OVERRIDES.md,Foreman-Playbook.mdandBUILDER-PROFILES.md, then the job's own handover and ticket. - Its first reply confirms the job's facts: the ticket and project, the builder, form A or B, the delivery, the repos and day folder, the gates, and what needs your word this job (and, if you started an autonomous run, which of those acts its goal covers).
- Anything unclear is measured or listed as an owed question, not assumed.
- It lists the Logbook cards in force for the job's area, CRITICAL and HIGH first.
- It runs the site walk, then stops and waits for your "go".
- Every reply ends with the 5-line status block.
The full page →Sample, common questions and what it connects to.
f-inspect
- Does
- Have specialist reviewers check the finished job's changes and report only problems.
- When
- When a job's build is finished and its tests pass, before the pull request is opened.
Say it
run the lens inspection
Not forThe independent inspection (pack-review → xreview → adjudicate), not a review of an open PR (f-greploop).
It's working if
- It stops and says so when
foreman/jobs/holds no job file for the slug, instead of reviewing anyway. - It stops and reports a wrong HEAD or an unexpected dirty file, and never checks out, stashes or resets anything.
- It lists which lenses ran and which were skipped, each with a reason, and
lens-simplifyran last as report-only. - Every finding carries severity, confidence, file:line, the scenario, why it matters and a concrete remedy.
- Each lens is asked whether, where a test proves something is absent (no raw amount, no secret), another test pins the exact value shown.
- A lens that halted, errored or returned
BLOCKis reported as such, not as a clean lens with zero findings. - The findings are written to
<day folder>/JOB-<N>-LENS-INSPECTION.md. - It gave no SHIP or BLOCK verdict, fixed nothing, and made no commit, push or PR.
The full page →Sample, common questions and what it connects to.
pack-review
- Does
- Bundle the goal, the rules and the changes into one brief for an outside reviewer.
- When
- Once the first review's fixes are in, to prepare the brief for the outside reviewer.
Not forNot a planning or build pack, and not a review (f-inspect, xreview).
It's working if
- The output is one fenced block you can copy as it stands, with no commentary before or after it.
- The brief has its sections in order: goal, hard constraints, non-goals, what to review, the diff or artifact, tests or repro, and what not to relitigate.
- Nothing in the brief names a model or vendor: commit trailers and vendor-identifying paths are replaced, not summarised around.
- Paths are absolute wherever the reviewer may run in a different checkout.
- On a huge diff, it packs the file list and the riskiest hunks, and says what it left out.
- It did not review the work, rewrite it, or edit any file.
The full page →Sample, common questions and what it connects to.
- Does
- Review another session's work with fresh eyes: list each claim, never rewrite it.
- When
- When the brief is ready and a session from a different AI company can review the work.
Not forOrdinary in-session code review (f-inspect, lens-code) and not for work this session wrote.
It's working if
- It opens with an Independence statement: automated dispatch or hand-carried, and if hand-carried, whether it already knows the author or has seen the work.
- It states the goal it reviewed against and says whether that goal was stated or inferred.
- Every finding is a numbered row in the claim table (C1, C2 and so on), with a bucket, a severity, evidence and the smallest suggested change.
- Anything it could not check is marked UNKNOWN, not promoted to a defect.
- A clean review is a single
C0 | No findingsrow naming what it actually read. - It ends after the six sections, with no essay, no rewrite and no file edits.
- It refuses, and says why, when asked to review work this same session wrote or supervised.
The full page →Sample, common questions and what it connects to.
adjudicate
- Does
- Go through a review point by point: accept, reject, partly accept, or can't verify.
- When
- When the outside reviewer's findings come back.
Not forReviewing (xreview, f-inspect) and not for a review this session wrote itself.
It's working if
- It restates the original goal and hard constraints from this session before judging any claim.
- It reads the reviewer's Independence statement first and says in one line if the reviewer was not blind.
- Every claim gets one verdict, ACCEPT, REJECT, PARTIAL or CANNOT VERIFY, with evidence from the code, tests or spec.
- There is no global agree or disagree.
- It produces an apply list ordered blocker, major, minor, a reject list with the risk if wrong, and a needs-evidence list carrying the reviewer's questions verbatim.
- With you present, it edits nothing until you answer: apply the accept list, apply a subset, or hold.
The full page →Sample, common questions and what it connects to.
f-greploop
- Does
- Run an open pull request through Greptile's review, up to three rounds.
- When
- After the pull request is open, when you say "greploop".
Say it
mergegreploop
Not forThe lens inspection (f-inspect) or the independent inspection (xreview); never merges.
It's working if
- It checks the PR's head matches the job's final head before asking for a review.
- It asks with the comment
@greptileai reviewexactly, once per round, and waits with the bundledgreptile-wait.mjs, not a hand-rolled loop. - Every Greptile finding gets a recorded disposition, even on a 5/5 score.
- Accepted findings go to the builder as test-first repair work orders; the foreman fixes nothing itself.
- Tests, base-vs-head and the acceptance ledger are green at the new head before any push, and pushes are never forced.
- It stops after round 3 at the latest and hands over with each round's score, the open findings and the commits added.
- The PR body is checked against the final diff before it tells you the PR is ready, and it never merges.
The full page →Sample, common questions and what it connects to.
- Does
- Update the project board when a job starts, merges, gets stuck or is added.
- When
- Whenever a job starts, merges, gets stuck or is added, so the board stays true.
Say it
gowhat's next?show me the board
Not forCutting a plan into jobs (f-schedule).
It's working if
- Each event is one
render_board.pycommand and bumps the board's version exactly once. - Ready and blocked are worked out by the tool, never stored, and only one job is in progress at a time.
- The tool refuses bad data or an impossible event, such as starting a blocked job, closing without
--nextwhen a job becomes eligible, or a merged job without its SHA. - A close is recorded only after the merge was checked in the repository, never on a report's word.
board.htmlis regenerated fromBOARD.jsonand never edited by hand.- With no board link yet, it renders locally and asks you before the first publish; after that it republishes to the same private link.
- The builder is never named on the board.
- Every job carries a summary that says in plain words what it builds, and
checkwarns on a summary that is only plan references.
The full page →Sample, common questions and what it connects to.
f-signoff
- Does
- Close a merged job: check every requirement passed, save the lessons, file the job away.
- When
- Right after a job's pull request is merged and the merge is confirmed.
Say it
close this jobwe're done, wrap it up
Not forCommitting or pushing (the owner's word).
It's working if
- On a build job that isn't merged, it refuses and points to the PR instead.
- Every row of the acceptance ledger is PASS. A row that isn't stops the close: there is no "close anyway".
- It shows a drift audit, planned but not built against built but not planned. An empty table is the normal result.
- The job file has moved to
foreman/completed-jobs/<YYYY-MM>/and is gone fromforeman/jobs/. - The last line reads
F-SIGNOFF: SIGNED OFF <archive path>, followed by the end-game checklist. - It staged, committed and pushed nothing, and the blueprint is untouched.
The full page →Sample, common questions and what it connects to.
- Does
- Save one lesson worth keeping as a Logbook card.
- When
- Whenever you learn something worth remembering for future jobs.
Say it
capture thissave this learningmake a card for that
It's working if
- It shows you the full card, its quality score and its file path, and asks "Create this card? (y/n)" before writing anything.
- The card is one INSIGHT, METHOD or BUILD file in the matching folder under
foreman/logbook/entries/, with an ID shaped likeTYPE_YYYYMMDD_SHORT_NAME. - If an existing card covers the same idea, it warns you and offers to add evidence to that card instead.
- The new card has a row in
foreman/logbook/logbook_index.md, and the total card count there is recounted from the files. - Any related cards it names appear as links in
foreman/logbook/logbook_links.md. - It writes one card per run and leaves the constitution alone.
The full page →Sample, common questions and what it connects to.
- Does
- Find Logbook cards about a topic.
- When
- When you want to know what past jobs learned about a topic.
It's working if
- It returns at most 10 cards, each with its id, type, cluster, tags, a short overview and its path.
- Every hit is a live card under
foreman/logbook/entries/, never one fromforeman/logbook/archived/. - The card templates never show up as hits, even in an empty Logbook.
- When nothing matches, it says so and points you to
/f-archive-search, with no made-up list of cards. - There are no ranking scores or stats tables in the output.
The full page →Sample, common questions and what it connects to.
f-archive
- Does
- Move old Logbook cards to the archive when there are too many, keeping a summary set.
- When
- When the Logbook passes 250 cards (f-shift does it for you).
Say it
the logbook is too bigrotate the logbookarchive old cards
It's working if
- Without
--executeit only previews: the live count, the archive number, the 50 kept cards with scores and clusters, and a few that would leave. Nothing is copied or deleted. - With 250 live cards or fewer, it archives nothing and says why.
- After a real run, the archived cards sit in a new numbered folder under
foreman/logbook/archived/, with aMANIFEST.jsonand aMANIFEST.md. - The live Logbook keeps 50 index cards, plus every
ruled-outcard. - The index and links are rebuilt for the kept cards, with counts taken from the files.
- The report ends with the helper's exit and its
verifyresult. It staged, committed and pushed nothing.
The full page →Sample, common questions and what it connects to.
f-archive-search
- Does
- Search the archived Logbook cards.
- When
- When a normal Logbook search finds nothing and the lesson might be old.
Say it
look in the archivewe knew this beforesearch the old cards
It's working if
- Results are grouped by archive number, each with the card's id, type, cluster, summary and path.
- Related ids from the same archive's
logbook_links.mdare listed next to a hit when there are any. - It searches only
foreman/logbook/archived/*/entries/, never the live Logbook. - If there are no archive batches yet, it says so and points you to
/f-search. - When nothing matches, it says none were found in the batches that exist, with no sample cards.
The full page →Sample, common questions and what it connects to.
f-catchup
- Does
- Write Logbook cards for past jobs that never got any.
- When
- When past jobs finished without anyone saving their lessons.
Not forA session status refresh (f-status).
It's working if
- It shows which completed jobs are covered by cards and which are not, with estimated card counts, then waits for your yes before writing any card.
- Each card it writes was checked against its source job and against existing card IDs.
- Routine jobs are skipped with "no cards warranted", rather than given a card each.
- New cards appear as rows in
logbook_index.md, with the counts recounted from the card files. - The report lists jobs inspected, cards created and skipped, and the gaps left.
- Completed jobs are untouched,
/f-distilldid not run, and nothing was staged, committed or pushed.
The full page →Sample, common questions and what it connects to.
f-context
- Does
- Get a quick, complete picture of a repo before working in it.
- When
- When you arrive at a repo you don't know, or before re-planning work.
Say it
get me up to speed on this projectwhat is this codebaseorient me
Not forA mid-session refresher, which is free (f-status). Not for Logbook card search (f-search).
It's working if
- The brief covers the project and its current priority, the git state, active work, the Logbook cards that match the focus, the relevant architecture, standing warnings and a short starting sequence with source paths.
- It names the active work in one focus line before it searches the Logbook.
- With a focus, it adds a short deep dive on that area. With
--deep, it adds a Deep Context section. - If a step fails, it carries on and tells you what is missing.
- It edited no files, staged, committed and pushed nothing, and called no paid services.
The full page →Sample, common questions and what it connects to.
f-distill
- Does
- Turn the most important lessons into firm rules, with your approval.
- When
- Now and then, when some lessons keep coming up and deserve to become firm rules.
Say it
distill the logbookpull the best learnings into the rules
Not forCapturing one card (f-card), not for merging or retiring cards (f-dream).
It's working if
- It shows a preview of short NEVER or ALWAYS bullets, each tagged with its destination and its source card ids, and writes nothing until you approve the exact bullets.
- Product lessons go to the repo's constitution; method lessons are shown as a diff to Topping Out's
RULES.mdor playbooks. - A bullet that contradicts an existing rule is shown as a proposed change to that rule, with both texts.
- Approved bullets are merged into the existing NEVER/ALWAYS sections, with no new "Distillation" heading.
- Each source card gains a
distilled: <date> -> <destination>line in its front matter. - The report lists cards analysed, bullets written per destination, and the high-value cards that missed the cut on age or links.
The full page →Sample, common questions and what it connects to.
- Does
- Look back over past jobs: merge repeated lessons and spot mistakes that keep happening.
- When
- Now and then, to tidy the Logbook: merge repeats and spot patterns.
Say it
reflect across the jobsare we repeating mistakesclean up contradictions in the logbook
Not forReconciles content: not for promoting knowledge upward (f-distill), nor for rotating by count (f-archive).
It's working if
- By default it reads the last ten completed jobs and returns a numbered proposal, writing nothing.
- Each proposed change cites its evidence, its target cards, the relationship changes, a confidence and a rollback.
- The proposal holds at most 10 changes and never retires a CRITICAL card on its own.
- The output gives the proposal ID, the corpus size, merges, supersessions, new patterns and anything skipped or flagged.
- When applied, each retired card is copied and the copy checked before the live copy is removed, and an applied manifest can reverse every change.
- It staged, committed and pushed nothing.
The full page →Sample, common questions and what it connects to.
- Does
- Install the method into a repo or upgrade it, write the repo profile, and prove the install.
- When
- When a repo should start running the method, or a newer package should go over an existing install.
Say it
set up Topping Out hereinstall the methodupgrade Topping Out
It's working if
- It copies only what's missing and never overwrites a file the repo already has; only an upgrade replaces a file, and only one unchanged since the last install.
- The repo profile is written from what the repo actually has, and you're asked only what it couldn't find, in one batch.
- Every profile row is filled; a row nothing can answer yet says
not recordedand why. - The names files exist, are git-ignored and never empty, and the names check proves itself on this machine.
- The test adapter is proved on two fixtures: only the test failing at head alone is reported.
- It never stages, commits or pushes: it ends with the list of files for your commit.
- It ends with one line:
F-SETUP: READY <profile path>orF-SETUP: HALTED <reason>.
The full page →Sample, common questions and what it connects to.
model-council
- Does
- Ask a panel of AI models, each answering on its own, to help settle a design choice.
- When
- When a design choice is stuck between options and you've agreed to let AI models weigh in.
Not forPanels that must inspect the codebase (agent-council). Not for what tests or an evaluation should decide.
It's working if
- Before any spending, it frames one neutral brief: a single decision question, two to four options, the constraints, and a request to choose and name the strongest argument against the choice. Its own lean is not in it.
- It opens a one-shot picker for every run, where you choose 2 to 5 panel seats from different vendors and one auditor. It does not run without your pick.
- The host's own model family never sits on the panel or as auditor, and when a Player is declared, that vendor's seat is dropped and the reduced count is stated.
- Every seat gets the same scrubbed brief and sees nothing from the other seats, the chair or the repository in the first round.
- The result is a decision the chair owns, with every first-round position, the convergence, the surviving dissent, and the auditor's verdict with the chair's answers.
- It does not hand the decision back to you as a question, unless it needs an authority it does not hold, such as spending, publishing or deleting.
The full page →Sample, common questions and what it connects to.
agent-council
- Does
- Ask AI agents that can read the code to help settle a design choice.
- When
- When a design choice depends on what's in the code and you've agreed to let agents read it.
Not forA decision a written brief can carry without repo access, that is the cheaper model-council.
It's working if
- It tells you the assurance profile before preparing: focused (2 external seats), balanced (3) or full (5), plus the host as chair and one separate auditor.
- No seat comes from the host's own model family; the resolver removes it and seats the next qualified replacement.
preparereturns a disclosure manifest and its SHA-256, and no model is called until you approve that exact digest.- It says which seats run on native subscription CLIs and which are pay-per-token Pi headless OpenRouter seats.
- Round 2 always runs; Round 3 runs only when
inspectreports it is required. - The audit verdict is
FAITHFULorNEEDS-REVISION, and only aFAITHFULrun can be finalized into your durable output folder. - A run with fewer seats than its profile needs is never called an Agent Council: there is no degraded panel.
The full page →Sample, common questions and what it connects to.
orca-pi-connect
- Does
- Link the foreman to a Pi builder in the Orca pane beside it, and know when it finishes.
- When
- When the builder runs in an Orca pane next to the foreman.
Say it
connect to piset up the builder pane
It's working if
- The builder pane is split to the right of the foreman, in the same tab, and started in the job's worktree with an assigned session ID.
- It puts the pane handle and session ID to you and waits for an explicit yes before sending anything.
- Round 1 gets back the job worktree's absolute path and READY, with the Stop log growing by at least one line for that session.
- Round 2 runs three separate
echocommands, prints the matchingORCA_TERMINAL_HANDLE, repliesDONE, and the Stop log grows by exactly one line. - The session file for that ID exists on disk, written during the handshake.
- The report says whether the link is proven, with the handle, the session ID, both rounds, the log counts and the model in the footer.
- During a job it sends only a one-line pointer to each work order, and checks the disk before reading the builder's report.
The full page →Sample, common questions and what it connects to.
f-night-shift
- Does
- Run several jobs one after another without you: a shift boss opens a fresh foreman for each.
- When
- Before you sleep, when the next jobs are on the board and you want them built one after another without you.
Say it
/goal night shift: jobs 13, 17, until done or stopped/goal night shift: 2 jobs, auto-pick, until done or stopped
Not forOne job (that is "/goal autonomous run: <opener>"), and never inside a job's own foreman session.
It's working if
- It copies your exact /goal words into the shift record before doing anything else.
- It refuses to start unless main matches the remote, the last job's end game is finished and no job worktree is open.
- It never plans, builds, reviews or merges: each job runs in its own fresh foreman session.
- It decides a job is done from the repo (merged, end game clear, next opener written), never from what the chat says.
- The first stop ends the whole shift, with the foreman's stop line quoted in the shift record.
- In planned mode it stops if a job's end game picks a job that is not next on your list.
The full page →Sample, common questions and what it connects to.
- Does
- Tell you in plain words where things stand and what's next.
- When
- When you want a plain summary of where things stand.
Say it
catch me upwhere are weI'm lostrefresh me
Not forThe 5-line status block every reply ends with (templates/J-STATUS.md).
It's working if
- It answers at once, without running any tool: no git, no file reads, no subagents.
- The reply uses up to five blocks in order (where we are, done this session, right now, next, watch out) and skips any that would be empty.
- It stays around 200 words or fewer.
- The body has no file paths, command names or commit hashes.
- "Right now" is a health line naming the scope checked:
Healthy,Blocked,WaitingorUnknown. - "Next" is one action and says who does it, or reads
nothing from you, and the reply ends there.
The full page →Sample, common questions and what it connects to.
- Does
- Check whether the agent really follows a rule when it's tempted to break it.
- When
- Before you trust a new builder with real work, or before turning a rule into an automatic check.
Say it
does this rule actually worktest the NEVERsis RULES.md being followed
Not forMeasures existing rules: not for writing them (f-distill promotes a card into the constitution). Not a code gate.
It's working if
--runrefuses with exit 2 unless you pass--host-authority-okor setFOREMAN_COMPLY_DISPOSABLE_HOST, before any directory is made or any CLI is started.--listand--dry-runshow the cases and the exact prompts without spending anything.- Each case and level reports one of four outcomes: held, declined, violated or inconclusive.
- A violation quotes the attempted commands and any completed git-state evidence.
- Inconclusive turns are counted separately, never as a pass, and the exit code is 1 when any turn was inconclusive.
- The run ends with an
F_COMPLY_RESULTline giving the measured count next to the total.
The full page →Sample, common questions and what it connects to.
- Does
- Read one reply out loud as a short spoken summary.
- When
- When you'd rather hear a reply than read it.
Say it
say that out loudread that backexplain that aloud
It's working if
- You hear a short plain-language explainer, not the reply read out word for word.
- The spoken version has no code, file paths, headings or bullet points, and runs about 20 to 60 seconds.
- The rewritten text is saved to
scratch/speak-input.txtand played withnpx tsx scripts/speak.ts scratch/speak-input.txt. - The chat reply is only a speaker symbol, plus a one-line note if the script printed an error.
- It speaks that one reply only, and later replies stay silent.
The full page →Sample, common questions and what it connects to.
- Does
- Read every reply out loud until you turn it off.
- When
- When you want every reply read aloud for a stretch of work.
Say it
start converse modeconverse onstop converseconverse offstop auto speakstop speaking every reply
It's working if
/conversewritesontoscratch/converse-mode, confirms in one line, and you hear that confirmation.- Every later reply shows its full text as usual and is also spoken as a short explainer.
/converse offclears the state file and confirms in text, and that confirmation is not spoken./converse statusreports on or off in one line, without changing the mode or speaking.- Turns that only run tools, with no message for you, are not spoken.
- After two failed speech attempts in a row it notes it once and carries on in text.
The full page →Sample, common questions and what it connects to.
simplicity-critic
- Does
- Find the overbuilt parts of a plan and suggest the simplest version.
- When
- When a plan or a project split looks bigger than it needs to be.
It's working if
- Its answer opens with a filled lens blueprint: the one-sentence requirement taken from the ticket, and the simplest design that meets it, sketched before any critique.
- Every finding is ranked Blocker, High, Medium or Nit, traces back to a blueprint field, and offers a concrete simpler alternative.
- Claims about the codebase carry a
file:line; a simpler option it has not confirmed is put as a question, not a finding. - The verdict comes last:
JUSTIFIED,TRIMorRETHINK, with the smallest shippable subset of the plan named. JUSTIFIEDappears when the plan is proportionate. It does not invent findings to fill the report.- It edited nothing and ran no git command that writes.
The full page →Sample, common questions and what it connects to.
handoff-builder
- Does
- Write the handover notes so the next session can pick up the work.
- When
- At the end of every job that has a next job, to write the notes for the next session.
It's working if
- Without a session brief it stops and lists the fields it needs, rather than writing a handoff from guesses.
- It writes exactly two files: the handoff, and a separate answer key the new session opens only after answering the questionnaire cold.
- The handoff states its mode (
MODE: fullorMODE: quick) and keeps pending approvals apart from approved ones. - Every path and git fact in it was checked against the repo; where the brief and the repo disagree, the repo wins and the handoff says so.
- Its return report includes the final self-check block it passed, and the claims it corrected.
- It committed nothing and pushed nothing.
The full page →Sample, common questions and what it connects to.
spec-validator-fixer
- Does
- Correct statements in a plan that are provably wrong.
- When
- At close, when the job record says something the code doesn't.
It's working if
- It corrected only false statements about the code as it is today (a path, a symbol, a signature, a count, a default, a script), each with the
file:linethat proves it. - Statements about the intended future (tasks, files to create, done-when lines) are left alone, even where today's code differs.
- Borderline cases, and fixes that would leave a "because" or a calculation stale, come back as suggested diffs, not applied edits.
- Claims it cannot verify are flagged, never deleted.
- It touched only the spec or plan it was given: no implementation code, no git writes.
- The report ends
CLEANorREMAINING CONCERNS, with the number of passes used (three at most).
The full page →Sample, common questions and what it connects to.
plan-validator
- Does
- Check a plan against the real code before it's built (used inside f-plancheck).
- When
- You don't call it yourself: f-plancheck uses it for every reader.
It's working if
- The read covers the six checks: files, patterns, dependencies, APIs, scope and risk.
- Each finding names what the codebase actually has, found by reading or searching it, not by guessing.
- Known false alarms (path aliases, Windows letter case, a slug against its readable form, re-export files) come back as advisories with a step to verify, not as failures.
- The plan file is unchanged: the checks only read the plan and the code.
- No git state moved: the contract allows read-only git and forbids every command that writes.
The full page →Sample, common questions and what it connects to.
lens-code
- Does
- Look for bugs and broken project rules in the changed code.
- When
- In every end-of-job review; it always runs.
It's working if
- It starts by saying what it reviewed: the job's range, a PR, or named files.
- It reports only issues it rates 80 or above for confidence, grouped as Critical (90 to 100) and Important (80 to 89).
- Each finding gives the
file:line, the repo rule or the bug it breaks, and a concrete fix. - A finding rated 90 or above shows the snippet, the input that reaches it with the wrong outcome, and why existing guards miss it.
- It says what it did not cover and why, and a clean diff gets zero findings, not invented ones.
- It changed no code and moved no git state.
The full page →Sample, common questions and what it connects to.
lens-errors
- Does
- Find errors that get silently ignored, and risky fallbacks.
- When
- When the changes touch error handling or fallbacks.
It's working if
- Each finding gives the
file:line, what the code does, and why it is not designed degradation. A finding that cannot say why is dropped. - Each finding carries a severity (CRITICAL, HIGH or MEDIUM), a confidence, the error classes it could hide, and a fix in the repo's own style.
- It treats documented fail-open paths as the design, but still flags a fallback that fires with no log line.
- An intent it cannot confirm is reported as inconclusive with a question to verify, not as CRITICAL.
- A clean change set gets a list of the catch sites and fallbacks it reviewed and zero defects.
- It changed no code.
The full page →Sample, common questions and what it connects to.
lens-types
- Does
- Check that the data types can't hold invalid values.
- When
- When the changes touch data types, schemas or rules about valid values.
It's working if
- It reads the target type and two or three sibling types first, and judges against the repo's own way of expressing rules in types.
- It checks the boundaries first: where database rows, request bodies or parsed JSON enter typed code without being parsed.
- Each finding cites
file:line, names the lens (boundary, expression, enforcement or usefulness), and gives a severity, a confidence and the smallest fix. - It never reports a missing convention the repo does not use as a defect, such as branded types.
- A well-designed type gets a short paragraph naming what it does right, and nothing invented.
- It changed no code.
The full page →Sample, common questions and what it connects to.
lens-tests
- Does
- Find changes that aren't properly tested.
- When
- When tests changed, or changed behaviour has no test.
Not forFinding product bugs (lens-code). Not for git (the caller owns it).
It's working if
- It states the git command that set its scope.
- Each gap names the uncovered behaviour at a
file:lineand a change to the code that no test would catch. - It reports a gap only at 80 or above for confidence, and only gaps this diff introduced; older holes get one line at most.
- Every recommendation uses the repo's own test harness and names the nearby test to copy.
- When coverage is adequate, it says so in one paragraph and stops.
- It changed no code and no tests.
The full page →Sample, common questions and what it connects to.
lens-comments
- Does
- Check that comments and docs still match the code.
- When
- When comments or documentation changed.
It's working if
- It opens with a verification ledger: an entry for every comment it flags, with the code it read to check the comment's claim.
- The ledger ends with a coverage line: how many comments were in scope, how many it verified, and how many it could not, with the reason.
- Its findings fall under Critical Issues, Improvement Opportunities, Recommended Removals and Positive Findings, each with a
file:line. - A comment it could not verify is marked inconclusive, never raised to a Critical Issue.
- If every comment holds, it says so and stops.
- It suggests changes and makes none.
The full page →Sample, common questions and what it connects to.
lens-instructions
- Does
- Check prompts, skills and templates for contradictions and broken references.
- When
- When skills, prompts, agents or templates changed. It also runs on demand, outside any job, whenever you decide: ask the session "run lens-instructions over <files or folder>" (/f-setup installs it in .claude/agents/). Same agent as the one some repos call instruction-reviewer.
It's working if
- It builds a map of which instruction file produces a name (a field, a flag, a section title, a file name) and which files read it, and checks those links first.
- Structural findings (counts, versions, paths, flag names) cite the search that proves them; meaning-level findings quote both passages word for word.
- Each conflict says how it resolves: a rule elsewhere settles it, both are right in different scopes, or you must decide.
- It reports only issues at 80 or above for confidence, ordered by severity.
- When nothing clears the bar it says "Documentation is aligned", lists the files and links it checked, and stops.
- It edited no files.
The full page →Sample, common questions and what it connects to.
lens-migrations
- Does
- Review database changes: migrations, queries and access rules.
- When
- When the changes touch the database.
Not forGeneral logic bugs (lens-code), not for swallowed errors (lens-errors), not for git (the caller owns it).
It's working if
- It checks the diff against the binding traps: JSON written or read the wrong way, a list bound to a single-value column, an array bound without the conversion its column needs, and guessed table or column names.
- Each finding is one row with the
file:line, a severity, what breaks and the fix. - It states whether the migration must be applied to production before merging (yes, no or unknown) and cites the evidence for that answer.
- A policy finding cites the repo's own rule it breaks; where the rule is silent, it says so instead of inventing one.
- It lists what it could not check, such as a database it could not reach or a plan it did not run.
- It applied no migration and wrote to no database.
The full page →Sample, common questions and what it connects to.
lens-simplify
- Does
- Spot code that could be simpler, without changing what it does.
- When
- Last in every end-of-job review, as a report only.
Not forFinding bugs (lens-code), not for "is this more than we need?" on a plan (simplicity-critic), not for git (the caller owns staging).
It's working if
- Under
/f-inspectit writes nothing: no edits, no snapshots, no gate run that writes files. - Each proposal gives the
file:line, the exact change, why behaviour stays the same, and what a future reader gains. - Its ledger always says what it chose not to simplify and why, with reasons you can act on without opening the file.
- No proposal touches public interfaces, tests, migrations, transaction boundaries, access scoping, privacy, or how errors fail and get logged.
- It ran no git command that writes.
The full page →Sample, common questions and what it connects to.
code-explorer
- Does
- Trace how an existing feature works through the code.
- When
- When the foreman needs to understand how an existing feature works.
It's working if
- The report opens with the exploration ledger: one entry per step, each listing the files it actually opened and the
file:linebehind its key claim. - Anything concluded from names, docs or string matches rather than read code is listed under
claims_inferred_not_verified. - The narrative cites
file:lineanchors instead of pasting code bodies. - It states what it searched for and did not find, and the open questions it could not settle from code.
- It ends with the short list of files you need to understand the topic.
- It describes the code and gives no verdict on whether something is a bug; it changed nothing.
The full page →Sample, common questions and what it connects to.
Matches
Pick one on the left to read it.
Nothing matches. Try another word, or open the Skill Atlas.