preflight
Skill18 starsChanged 52 days agoApache-2.0View on GitHub
Pre-work ritual — spec, search, and (when needed) a 1-page implementation design doc before touching code
50 other projects use a version of this.
Adopted by
Most recently taken up by
- urvijain02/ticket-to-prtheir own version, first seen Nov 16, 2026
- timursafiullin/aodtheir own version, first seen Nov 15, 2026
- nazmirket/skillstheir own version, first seen Nov 15, 2026
- mazze93/claude-code-skillstheir own version, first seen Nov 10, 2026
- sohaibt/product-modetheir own version, first seen Nov 8, 2026
- KadirHarmanc/nazar-skilltheir own version, first seen Nov 8, 2026
Used with
Projects with it also use adr, ship and 10 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.
asterkinSkilladr
Create Architecture Decision Records (ADRs) following project standards. Guides template usage, process, and best practices for documenting architecturally significant decisions.
Also in 3 projects that use this
AWSSkillship
Finalize dev work on an issue branch — update docs, push, and open a PR.
Also in 5 projects that use this
MicrosoftSkillreport
Turn an exploration (threads, findings, charts) into a single Markdown report — note, blog post, executive summary, KPI dashboard, slide brief, or multi-section analytical report, with embedded charts.
Also in 3 projects that use this
Google CloudSkilltriage
Gather context on a change or bug and plan the implementation.
Also in 4 projects that use this
AnthropicSkillstatus
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 3 projects that use this
GitHubSkillrefactor
Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements.
Also in 3 projects that use this
Other versions50 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 50
- webiny/webiny-js★ 8.1ksame name
- CrowdDotDev/crowd.dev★ 3.4ksame name
- tphakala/birdnet-go★ 2.5ksame name
- openfootmanager/openfootmanager★ 1.2ksame name
- mohebifar/tooscut★ 717same name
- me2resh/apexyard★ 542same name
- linuxfoundation/insights★ 292same name
- sohaibt/product-mode★ 171same name
- unlearndev/skills★ 106same name
- ogulcancelik/agent-skills★ 81same name
40 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- review-loopSkill
- review-replySkill
- signoffSkill
- signonSkill
- postmergeSkill
- prepushSkill
- review-loopSkill
- review-replySkill
- signoffSkill
- signonSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. 0 are common, 13 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 45 edited versions we read keep these.
13
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 6
Before starting work on issue $ARGUMENTS, execute these phases in order.
- Distinctive: line 7
Do NOT write code until all gates are cleared.
- Very specific: line 11
Run pnpm exec totem spec $ARGUMENTS to generate the implementation spec from the issue body.
- Very specific: line 13
Call mcp__totem-dev__search_knowledge with a query describing the changes you're about to make.
- Very specific: line 21
If totem spec fails, report the error and stop — do not proceed to Phase 2.
- Distinctive: line 28
No new types or required fields on existing types
- Distinctive: line 29
No new state containers (maps, sets, module-level variables, singletons)
- Distinctive: line 30
No new failure modes or classes of error
- Distinctive: line 31
No new cross-cutting concerns (logging, telemetry, caching, auth)
- Distinctive: line 57
When in doubt, draft the doc.
- Distinctive: line 75
Tactical path — no approval gate: If tactical, proceed directly to implementation after Phase 2 (triage) completes.
- Distinctive: line 115
Lifetime: when created, when mutated, when cleared, when destroyed
- Distinctive: line 118
Call out any state that crosses lifecycle boundaries (e.g., a session-level flag consumed by a per-request operation).
- Distinctive: line 138
NOT test names. The guarantees you're testing.
- Distinctive: line 160
After drafting Phase 3, STOP and output:
- Distinctive: line 166
Do NOT write code until the user explicitly approves the design.
“Common” is measured: kept by at least 6 in 10 of the 45 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.
Files
Before starting work on issue $ARGUMENTS, execute these phases in order. Do NOT write code until all gates are cleared.
Phase 1 — Mechanical context gathering
- Run
pnpm exec totem spec $ARGUMENTSto generate the implementation spec from the issue body. Output lands in.totem/specs/<issue>.md. - Call
mcp__totem-dev__search_knowledgewith a query describing the changes you're about to make. If the issue touches a specific system (hooks, orchestrator, compiler, extract pipeline, store layer, MCP server), ALSO querymcp__totem-strategy__search_knowledgefor relevant ADRs and proposals. - Summarize in 3-5 bullets: what the spec says, which lessons are relevant, and any constraints or traps surfaced by the knowledge queries.
If totem spec fails, report the error and stop — do not proceed to Phase 2.
Phase 2 — Scope triage (decide if Phase 3 is needed)
Skip Phase 3 if this is a tactical change. Tactical means ALL of:
- Pure bug fix, wording change, or existing-test tightening
- No new types or required fields on existing types
- No new state containers (maps, sets, module-level variables, singletons)
- No new failure modes or classes of error
- No new cross-cutting concerns (logging, telemetry, caching, auth)
- Touches ≤3 files in a single architectural layer
- Leaves the branch-vs-base diff (three-dot against the base, so main
moving does not grow it) under the review window (
totem reviewnames the cut; 50000 characters of code today, not configurable)
Draft the design doc (Phase 3) if ANY of:
- Adds a new type, interface, or required field
- Adds a new state container or changes state ownership/lifecycle
- Introduces a new failure mode or changes existing error surface (hard error → warning, sync → async, blocking → non-blocking)
- Crosses architectural boundaries (core → cli, cli → mcp, etc.)
- Touches >3 files OR introduces a new cross-cutting concern
- Documents a new config field, new public API method, or new agent-facing tool surface (regardless of whether the doc is in the same PR as the implementation, and regardless of whether the implementation is yours or someone else's)
- Pushes the branch's diff past the review window, or a fold during the build does: a diff past the window is architectural on SIZE alone, because every reviewer, local and external, reads it in slices and review rounds scale with it. Re-triage when a fold crosses this line, and put the ride-or-split question to the operator WITH its price in rounds (mmnto-ai/totem#3114: a 26-file diff, re-triaged after two reads, took eight external rounds)
When in doubt, draft the doc. The cost of 10 minutes of design writing is always lower than the cost of a multi-round bot review cycle.
Why docs-that-describe-features count as architectural. A wiki page that describes a new config field has the same data-model verification requirement as the code that implements it — you can write incorrect documentation about a real feature surface just as easily as you can write incorrect code. If you're authoring docs for a feature you didn't just build (or built more than a session ago), READ THE SCHEMA before the prose. The Phase 3 data-model section will force you to enumerate the config fields, which is exactly the work that catches "I remember this feature as automatic but the schema says opt-in" errors before they ship to users. The mmnto-ai/totem#1297 docs PR cycle is the load-bearing example.
State your triage decision explicitly: "Tactical — skipping Phase 3" or "Architectural — drafting design doc."
Tactical path — no approval gate. If tactical, proceed directly to implementation after Phase 2 (triage) completes. The Phase 4 approval gate below only applies when Phase 3 was drafted, because the gate exists to catch architectural mistakes before code is written — there's nothing architectural to review for a tactical change. The user's normal PR-approval and merge-approval rules still apply to the finished code.
Architectural path — continue to Phase 3. Draft the design doc, then stop at the Phase 4 approval gate before writing any code.
Phase 3 — Implementation design doc (REQUIRED for architectural changes before code; skipped for tactical)
Append a new ## Implementation Design section to the spec file at
.totem/specs/<issue>.md. The section MUST cover all six subsections
below. Keep it tight — the whole design section should fit in ~1 page.
Scope (2 sentences)
What this implementation will do, and what it explicitly will NOT do. Negative scope is load-bearing — it prevents scope creep during review.
Data model deltas
List every new type, new field on an existing type, and every new state container (map/set/module variable). For each:
- What it holds
- Who writes it
- Who reads it
- What invariants hold (required vs optional, bounded vs unbounded, who guarantees the invariant)
Explicitly call out any "reserved keys" or sentinel values — those are collision hazards. Prefer separate fields over reserved keys.
State lifecycle
For each new piece of state, identify:
- Scope: per-request / per-session / server-lifetime / persistent
- Lifetime: when created, when mutated, when cleared, when destroyed
- Ownership: which function/module owns mutation
Call out any state that crosses lifecycle boundaries (e.g., a session-level flag consumed by a per-request operation). Those are the most common source of "one-shot flag consumed before its work succeeded" bugs.
Failure modes
A table. For each failure point:
| Failure | Category | Agent-facing surface | Recovery |
<description> | init / runtime / transient / permanent | hard error / isError / warning / silent degradation | how state returns to healthy |
Be exhaustive. Every place the code can throw, return null, return an empty result, or silently succeed with degraded output is a row. If a row has "silent degradation" in the surface column, justify it against Tenet 4 (Fail Loud, Never Drift) or change the design.
Invariants to lock in via tests
NOT test names. The guarantees you're testing. Example:
- "linked store named 'primary' must not collide with primary failure slot"
- "init-time warnings survive any reconnect cycle untouched"
- "one-shot first-query flags are consumed only after successful work"
These become the test assertions. If you can't articulate the invariant in English, you probably don't understand what you're testing yet.
Open questions
Anything that needs user judgment before coding starts. Format:
- Question:
<one sentence> - Options:
<bulleted list of viable answers with tradeoffs> - Recommendation:
<your best guess>
Phase 4 — Approval gate (architectural path only)
This phase applies ONLY when Phase 3 was drafted. For tactical changes that skipped Phase 3, there is no gate — see Phase 2.
After drafting Phase 3, STOP and output:
Design doc drafted at
.totem/specs/<issue>.md. Please review the Implementation Design section and approve before I start coding. Open questions:<count>.
Do NOT write code until the user explicitly approves the design. If the user wants changes, update the doc and re-stop for approval.
Controller-not-implementer (ADR-063): protect your own decision-making by surfacing architectural questions BEFORE they become bot review findings. A 10-minute design review with the user is strictly cheaper than a 7-round bot review cycle on the PR.
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
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.

