Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

preflight

/preflight

Waliduje architekturę nowego projektu przed kodem, szuka podobnych repozytoriów na GitHubie i doradza w utrzymaniu projektu i pamięci agentów.

Repozytorium
preflight ↗
Licencja
MIT
Ostatnia zmiana repozytorium
28.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
3
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 28.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 3 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/render_blueprint.py, scripts/scout.py, scripts/state.py

Co robi i kiedy

Waliduje architekturę nowego projektu przed kodem, szuka podobnych repozytoriów na GitHubie i doradza w utrzymaniu projektu i pamięci agentów.

Oryginalny opis (EN)

Pre-implementation architecture validator, GitHub prior-art & OSS building-block scout, project maintenance tooling advisor, and memory/agent-communication architect. Use when the user wants to validate a new project idea before writing code, run `/preflight`, reset/rerun an idea from a clean state, stress-test an architecture across Problem/Scope/Memory/Bottlenecks/Differentiation, scout GitHub for Graveyard/Dormant Repos, OSS Building Blocks, and verified Pain Points from open issues, recommend project maintenance tooling (Docker, Kubernetes, lockfiles, CI) with alternatives, design agent co

Jak działa

  1. Interview & Domain Discipline (Self-Contained)
  2. Script Path Resolution
  3. Fresh Reset / Running a New Idea or Re-Running Cleanly (reset / init --reset)
  4. The 5 Grilling Dimensions & Evidence-Based Readiness Gate
  5. Execution Process
Sekcje z nagłówków SKILL.md, w oryginale · 253 linii, 2 272 słów
Podgląd SKILL.md
---
name: preflight
description: >-
  Pre-implementation architecture validator, GitHub prior-art & OSS building-block scout,
  project maintenance tooling advisor, and memory/agent-communication architect.
  Use when the user wants to validate a new project idea before writing code, run `/preflight`,
  reset/rerun an idea from a clean state, stress-test an architecture across Problem/Scope/Memory/Bottlenecks/Differentiation,
  scout GitHub for Graveyard/Dormant Repos, OSS Building Blocks, and verified Pain Points from open issues,
  recommend project maintenance tooling (Docker, Kubernetes, lockfiles, CI) with alternatives,
  design agent communication and memory workflows (Stateless vs. SQLite/Postgres vs. FTS vs. RAG vs. Vector DB),
  or generate `blueprint_report.html`, `.preflight/SPEC.md`, `.preflight/STACK.md`, and `.preflight/issues/`.
---

# PreFlight: Pre-Implementation Architecture, Tooling & Prior-Art Validator

PreFlight runs **before** code is written. Instead of acting as a "yes-man", you interrogate the user across five architectural dimensions, scout GitHub for **Active Incumbents**, **Graveyard / Dormant Repos**, **OSS Building Blocks**, and **Pain-Point Mining** from open issues and top-voted comments, recommend **Project Maintenance & Infrastructure Tooling** (with alternatives and verified vs. claimed config proofs), prescribe the right **Memory & Agent Communication Workflow** (supporting primary + secondary strategies across Stateless, Transactional DB, Lexical FTS, RAG / Vector DB, Hybrid Search, and Episodic Agent State), record locked choices in a **Decision Ledger**, and compile `blueprint_report.html`, `.preflight/SPEC.md`, `.preflight/STACK.md`, and ordered implementation tickets in `.preflight/issues/`.

## Interview & Domain Discipline (Self-Contained)

1. **Frontier Interview Rounds**:
   - Map the architecture as a **design tree** where each settled decision unblocks downstream questions.
   - Ask all currently unblocked questions in a single numbered round (`❓ **Q1** - **<Title>**: <Body> \n\n ➡️ <Recommended answer>`), worded so `"yes"` accepts your recommendation.
2. **Inline Domain Glossary (`GLOSSARY.md`)**:
   - Maintain `GLOSSARY.md` at the workspace root as domain terms crystallize (`**<Term>**: <1-2 sentence definition>\n_Avoid_: <synonyms>`).

---

## Script Path Resolution

Resolve `PREFLIGHT_SCRIPTS` to the `scripts/` folder adjacent to this `SKILL.md` file (for example `.agents/skills/preflight/scripts`, `skills/preflight/scripts`, or `~/.gemini/config/skills/preflight/scripts`):

```bash
for d in "./skills/preflight/scripts" "./.agents/skills/preflight/scripts" "$HOME/.claude/skills/preflight/scripts" "$HOME/.agents/skills/preflight/scripts" "$HOME/.gemini/config/skills/preflight/scripts"; do
  [ -d "$d" ] && PREFLIGHT_SCRIPTS="$d" && break
done
```

---

## Fresh Reset / Running a New Idea or Re-Running Cleanly (`reset` / `init --reset`)

Whenever the user wants to **run a different idea in the same folder** or **re-run the same idea from a fresh slate**:
- Run `state.py reset` (or pass `--reset` to `state.py init`):
  ```bash
  python3 "$PREFLIGHT_SCRIPTS/state.py" --workspace . reset
  ```
- **Safe ADR Handling (`--keep-adrs`)**:
  - By default, `reset` and `init --reset` delete **only** the ADR files recorded in `.preflight/decisions.json`, leaving any pre-existing repository ADRs in `docs/adr/` untouched.
  - Pass `--keep-adrs` to `state.py reset` or `state.py init --reset` if you also want to keep the ADRs recorded during the previous PreFlight session on disk.
  - Pass `--purge-cache` if you also want to delete `.preflight/cache.db` (kept by default to preserve GitHub Search API rate limits).

---

## The 5 Grilling Dimensions & Evidence-Based Readiness Gate

Every project is scored across five dimensions (`20%` each, `0%–100%` total). `state.py` enforces **strict programmatic evidence rules** — self-certifying `20/20` with a one-liner, scoring `memory` `20/20` before configuring `set-memory-arch`, or scoring `differentiation` before running `scout.py` will fail with exit code `2`:

| Key | Dimension | `0` (Untouched) | `10` (Surface) | `20` (Stress-Tested — Programmatically Enforced) |
| :--- | :--- | :--- | :--- | :--- |
| `problem` | **Problem & User Pain** | Unstated | General pitch stated | Summary $\ge 40$ chars + $\ge 2$ `--edge-case` scenarios locked |
| `scope` | **Scope & Non-Goals** | Unbounded | High-level features listed | Summary $\ge 40$ chars + $\ge 2$ explicit boundary `--edge-case` items |
| `memory` | **State, Memory & Agent Communication** | Unknown | Storage engine named | Requires `set-memory-arch` (primary strategy, communication pattern, $\ge 1$ failure mode) + summary $\ge 40$ chars + $\ge 2$ `--edge-case` items |
| `bottlenecks` | **Bottlenecks & Failure Modes** | Ignored | Happy-path assumed | Summary $\ge 40$ chars + $\ge 2$ rate-limit/latency/SPOF `--edge-case` items |
| `differentiation` | **Prior-Art Differentiation** | Unchecked | Contrasted against scouted repos | Requires `.preflight/prior-art.json` from `scout.py`, $\ge 2$ edge cases, and must explicitly cite at least one discovered `owner/repo` |

**Readiness Gate Requirements (`evaluate_gate`)**:
`render_blueprint.py` and `state.py export-tickets` refuse to unlock until **all** of the following hold:
1. Total score $\ge 80\%$ with **zero** dimensions at `0%`.
2. `.preflight/prior-art.json` exists and contains scouted repositories from `scout.py`.
3. `set-memory-arch` is configured with a primary strategy, agent/component communication pattern, and $\ge 1$ memory failure mode.
4. At least **1 Stack Explained tool entry** (`add-tool`) is recorded.
5. At least **1 Architecture Decision Record** (`add-decision`) is recorded in `.preflight/decisions.json` and `docs/adr/`.
6. At least **1 Adversarial Red-Team Critique** (`add-critique`) is recorded.
7. Both `topology_mermaid` and `sequence_mermaid` are populated via `state.py set-design`.

**Draft Override (`--force`)**:
If the user explicitly asks to preview outputs before the gate reaches 80%, passing `--force` to `render_blueprint.py` or `state.py export-tickets` bypasses the gate lock **but watermarks every output as `DRAFT`**:
- `blueprint_report.html` displays a red `DRAFT BLUEPRINT (READINESS GATE LOCKED)` banner and `DRAFT` title.
- `.preflight/SPEC.md` and `.preflight/STACK.md` headers are prefixed with `[DRAFT]` and a gate-locked warning callout.
- Every exported ticket in `.preflight/issues/` is prefixed with `[DRAFT]` and marked `**Status:** draft` (never `ready-for-agent`).

---

## Execution Process

### Step 1: Initialize Working State (or Reset) & Launch Round 1 Grilling

When the user pitches an idea or invokes `/preflight`:

1. Initialize `.preflight/state.json` (pass `--reset` if starting a new idea or re-running from scratch; add `--keep-adrs` to preserve previous session ADRs):
   ```bash
   python3 "$PREFLIGHT_SCRIPTS/state.py" --workspace . init --reset \
     --name "<Project Name>" \
     --summary "<1-2 sentence summary>" \
     --runtime "<Target Runtime>" \
     --stack "<Comma-separated stack>"
   ```
2. Seed `GLOSSARY.md` at the workspace root if it does not exist yet.
3. Ask **Round 1** of the **Grilling Session** (3–4 frontier questions covering `problem`, `scope`, initial `memory` & agent communication needs, and `bottlenecks`), each with a concrete `➡️` recommended answer.

**Completion Criterion**: `.preflight/state.json` exists and Round 1 frontier questions are presented to the user.

---

### Step 2: Run the GitHub Prior-Art, Pain-Point & OSS Building-Block Scout

As soon as the core problem is clear (after Round 1, or immediately if the user provided a detailed spec):

1. Craft 2–3 competitor queries (`-q`) + 1–2 GitHub topic qualifiers (`--topic`), **and** 2–3 open-source library/tooling queries (`-t` / `--tool-query` or `--tool-topic`) for the libraries/SDKs needed to build the project.
2. Run `scout.py`:
   ```bash
   python3 "$PREFLIGHT_SCRIPTS/scout.py" --workspace . \
     -q "<competitor query 1>" \
     -q "<competitor query 2>" \
     --topic "<github-topic>" \
     -t "<oss building block query 1>" \
     -t "<oss building block query 2>"
   ```
   `scout.py` authenticates via `gh auth token` $\to$ `GITHUB_TOKEN` $\to$ unauthenticated fallback, caches responses in `.preflight/cache.db` (SQLite3, 7-day TTL), writes `.preflight/prior-art.json` (tracking Search API and Core API quotas separately alongside `search_limits` and multi-page pagination depth), and outputs:
   - **Active Incumbents** (pushed within 365 days, with verified root config files and approximate lifetime star velocity across paginated search pages)
   - **Graveyard / Dormant Repos** (heuristic: archived by maintainer or $>365\text{d}$ without pushes — treat $>365\text{d}$ inactivity as a maintenance signal only; never claim a repo stalled due to a single design choice without issue/commit evidence)
   - **Scouted OSS Building Blocks** (actively maintained open-source libraries/tools with SPDX license & star counts)
   - **Verified Pain Points** (Pass A: top `+1` open issues; Pass B: `label:bug` open issues; includes `top_comments` from issue threads)

**Completion Criterion**: `.preflight/prior-art.json` is populated with competitors, config-file evidence, and OSS building blocks.

---

### Step 3: "Stack Explained" (Verified vs. Claimed Tooling, Now vs. Later) & Memory Architecture

For every idea, you must produce a **"Stack Explained"** breakdown **and** prescribe the Memory & Agent Communication workflow:

#### A. "Stack Explained" (`state.py add-tool`)
Produce one concise entry per tool answering four exact questions:
1. **What job it does** (`--purpose`)
2. **Why this project needs it now** (`--why`)
3. **What the alternative was** (`--alternatives`)
4. **Whether it is `now` or `later`** (`--stage now|later`) + the config file (`--config-proof`)

`state.py add-tool` validates `--config-proof` using tool-to-config signature pairing against `.preflight/prior-art.json` (`observed_stack_configs`) and existing workspace files. It verifies that the config file (e.g. `Dockerfile`, `go.sum`, `uv.lock`) genuinely associates with the recommended tool or that the tool appears in project manifests (`pyproject.toml`, `requirements.txt`, `package.json`, `docker-compose.yml`, `Makefile`). Each entry is labeled in `STACK.md` and `blueprint_report.html` as either **`✅ Verified`** (backed by matching tool-to-config evidence from `scout.py` or workspace files) or **`⚠️ Claimed / Unverified`** (recommended for the target architecture, not yet empirically proven or present on disk).

```bash
python3 "$PREFLIGHT_SCRIPTS/state.py" --workspace . add-tool \
  --category <dependency-lock|container-runtime|orchestration-deploy|ci-cd-quality|core-oss|storage-memory|observability> \
  --recommended "<Tool name, e.g. uv (uv.lock), Docker, GitHub Actions, pre-commit, Kubernetes>" \
  --stage <now|later> \
  --purpose "<What job it does>" \
  --why "<Why this project needs it now (or why deferred until later)>" \
  --alternatives "<What the alternative was and why it wasn't chosen>" \
  --config-proof "<Config file proving usage, e.g. pyproject.toml ([tool.uv]), Dockerfile, .github/workflows, .pre-commit-config.yaml>"
```

#### B. Memory, State & Agent Communication Advisor (`state.py set-memory-arch`)
Evaluate how agents or components should communicate and what memory architecture fits best. Because real architectures often combine multiple layers (for example, `transactional-db` + `lexical-fts` + `episodic-agent-state`), `set-memory-arch` accepts a primary `--strategy` plus repeatable `--secondary-strategy` flags:
- `stateless`: Pure CLI/utility or deterministic transform (avoid unnecessary DB overhead).
- `transactional-db`: Structured relational/embedded state (`SQLite WAL` / `PostgreSQL`) with typed schemas.
- `lexical-fts`: Exact-match/identifier/code/log search (`SQLite FTS5`, `BM25`, `Postgres tsvector`).
- `rag-vector-db`: Unstructured semantic retrieval (`pgvector`, `Qdrant`, `LanceDB`) when semantic similarity over large corpora is mandatory.
- `hybrid-search`: Combined lexical (`BM25`/`FTS5`) + vector embeddings with Reciprocal Rank Fusion.
- `episodic-agent-state`: Multi-step agent workflow using structured handoff checkpoints + compacted episodic state to prevent context rot.

Record the memory architecture. For stateful systems, at least 1 specific memory failure mode is required before scoring `memory` `20/20` or unlocking the gate. For **stateless** systems (CLI tools, deterministic transforms, single-process scripts), pass `--strategy stateless` with a substantive `--rationale` ($\ge 15$ characters) explaining why persistent memory and agent communication do not apply; this explicitly exempts the project from `--failure-mode` and sets a default stateless communication pattern to avoid artificial gate theater:
```bash
python3 "$PREFLIGHT_SCRIPTS/state.py" --workspace . set-memory-arch \
  --strategy <stateless|transactional-db|lexical-fts|rag-vector-db|hybrid-search|episodic-agent-state> \
  --secondary-strategy <optional additional strategy, repeatable> \
  --communication "<How agents/components communicate and pass state (e.g., typed JSON handoff schemas, MCP, single-writer channel)>" \
  --workflow "<How memory is read, written, compacted, and invalidated across the workflow>" \
  --rationale "<Why this memory strategy beats RAG/Vector DB or other alternatives for this idea>" \
  --alternatives "<Rejected memory options (e.g. pure Vector DB, uncompacted chat history) and why>" \
  --failure-mode "<Memory Failure Mode 1 (e.g. context window bloat, SQLITE_BUSY, stale cache) + mitigation>" \
  --failure-mode "<Memory Failure Mode 2 + mitigation>"
```
This automatically generates `.preflight/STACK.md` and populates Tab 3 of `blueprint_report.html`.

---

### Step 4: Challenge with Prior-Art Evidence & Update the Decision Ledger

In Round 2 and subsequent rounds:

1. **Challenge with Mined Evidence**:
   - Cite specific **Active Incumbents** and **Graveyard Repos** by `owner/repo`.
   - Quote specific `🐛 BUG/FAILURE` or `🔥 TOP-VOTED` issues and `@author` comments from `scout.py`, and ask how the user's architecture avoids or solves those exact failure modes.
2. **Update Rubric, Critiques, and ADRs after each round**:
   - Update dimension scores (`0`, `10`, `20`) with substantive summaries and $\ge 2$ `--edge-case` flags:
     ```bash
     python3 "$PREFLIGHT_SCRIPTS/state.py" --workspace . update-dimension \
       --dimension <problem|scope|memory|bottlenecks|differentiation> \
       --score <0|10|20> \
       --summary "<Detailed architectural explanation (>=40 chars)>" \
       --edge-case "<Concrete edge case 1>" \
       --edge-case "<Concrete edge case 2>"
     ```
   - Record adversarial critiques uncovered during grilling:
     ```bash
     python3 "$PREFLIGHT_SCRIPTS/state.py" --workspace . add-critique \
       --title "<Risk title>" \
       --severity <critical|high|medium> \
       --attack "<How it fails under stress>" \
       --mitigation "<Architectural mitigation>"
     ```
   - Record locked architectural decisions (writes both `.preflight/decisions.json` and `docs/adr/NNNN-<slug>.md`):
     ```bash
     python3 "$PREFLIGHT_SCRIPTS/state.py" --workspace . add-decision \
       --title "<Short Decision Title>" \
       --decision "<What we decided>" \
       --rejected "<What alternatives were rejected>" \
       --rationale "<Why we chose this path>" \
       --dimension <dimension>
     ```
3. Display the Readiness Scorecard (`state.py status`) at each round.

**Completion Criterion**: All gate requirements in `state.py status` are satisfied (`UNLOCKED`).

---

### Step 5: Set System Design, Render Blueprint & Export Ordered Tickets (`.preflight/issues/`)

Once the **Readiness Gate** is unlocked:

1. Populate the Mermaid diagrams, trade-off matrix, and ordered vertical-slice implementation steps via `state.py set-design` (you can optionally use `"Title :: Detailed Deliverable :: BlockedBy"` in `--step` to declare custom or parallel dependency edges):
   ```bash
   python3 "$PREFLIGHT_SCRIPTS/state.py" --workspace . set-design \
     --topology "flowchart TD ..." \
     --sequence "sequenceDiagram ..." \
     --option "Option A|Pros|Cons|Selected (ADR-0001)" \
     --option "Option B|Pros|Cons|Rejected" \
     --step "Step 1: ..." \
     --step "Step 2: ..."
   ```
2. Render the Blueprint, Specification, Stack Document, and **ordered implementation tickets** (`.preflight/issues/01-<slug>.md`, `02-<slug>.md`, ..., plus `.preflight/issues/INDEX.md`):
   ```bash
   python3 "$PREFLIGHT_SCRIPTS/render_blueprint.py" --workspace . \
     --output blueprint_report.html \
     --spec-output .preflight/SPEC.md
   ```
   *(Note: Visual diagram rendering in `blueprint_report.html` loads Mermaid.js from `cdn.jsdelivr.net` and requires an internet connection; expandable raw Mermaid source blocks are included on every diagram card.)*
3. Present links to:
   - `blueprint_report.html`
   - `.preflight/SPEC.md` and `.preflight/STACK.md`
   - `.preflight/issues/INDEX.md` (and the individual `01-...md`, `02-...md` tickets with ticket-specific acceptance criteria)
   - `GLOSSARY.md` and `docs/adr/`
4. **Handoff to Implementation (GitHub Issues or Local Tickets)**:
   Offer the user their preferred execution path:
   - **Option 1 — Direct GitHub Issues Export (Recommended)**:
     Commit and push architecture documents so links work on GitHub, then export all tickets to GitHub Issues:
     ```bash
     # 1. Commit and push architecture artifacts so GitHub links resolve
     git add .preflight/ docs/adr/ GLOSSARY.md
     git commit -m "docs(preflight): architecture spec, stack explained, and adr ledger"
     git push origin main

     # 2. Export all tickets to GitHub Issues
     python3 "$PREFLIGHT_SCRIPTS/state.py" --workspace . export-github-issues --repo <owner/repo>
     ```
     PreFlight will:
     - Prepend GitHub links to `.preflight/SPEC.md`, `.preflight/STACK.md`, `docs/adr/`, and `GLOSSARY.md` at the top of each issue.
     - Add labels `ready-for-agent` and `needs-triage` (created via `gh label create --force` if not present).
     - Include the full, verbatim ticket content without shortening or truncating acceptance criteria.
     - Sequentially resolve `Blocked by: #<num>` with the actual upstream GitHub issue number once created.
     - Report all created issue numbers and display Issue #1 in its entirety for immediate verification.
   - **Option 2 — One Ticket at a Time (Local Files)**: Work through `.preflight/issues/01-<slug>.md`, `02-<slug>.md`, ... sequentially (one vertical slice per context window), writing tests first and verifying each ticket's specific acceptance criteria before moving to the next.
   - **Option 3 — Parallel Task Build**: When tickets declare independent `BlockedBy` edges in `.preflight/issues/INDEX.md`, use background implementer subagents to execute unblocked tickets in parallel and merge them onto an integration branch.
Pliki w paczce (4)
  • SKILL.md 19 KB
  • scripts/render_blueprint.py 40 KB
  • scripts/scout.py 49 KB
  • scripts/state.py 81 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · thilak15/preflight100MIT
andreibesleaga/gabbe100CC-BY-4.0
pathmodeio/claude-plugin100MIT
aradmanamnaoon/agent-guardrails100MIT
mo-cmyk/mazarbul100Apache-2.0
manpreet171/slopguard100MIT
rune-kit/rune100MIT
nazmirket/skills90MIT
pandysp/claude-plugins90MIT

Migawka bazy z 13.11.2026 · wersja paczki 691ee0efc123 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 86scout
    Szuka w sieci rozwiązań, konkurentów i alternatyw dla decyzji w projekcie, a wyniki zapisuje w pamięci projektu.
  • 100oss-code-analysis
    Przegląda drzewa źródeł repozytoriów open source na GitHubie, aby porównać implementacje funkcji między projektami albo dogłębnie zbadać jeden projekt.
  • 91project-preflight
    Sprawdza repozytorium, worktree, powłokę, terminal, GitHub CLI i uprawnienia przed startem pracy w projekcie.
  • 80OSS Contribution Best Practices
    Doradza przy wkładzie w open source: odpowiedzi dla opiekunów projektu, opisy pull requestów, zgłoszenia i etykieta.
  • 100assess-oss
    Ocenia projekty open source na podstawie danych z GitHub, npm i crates.io: utrzymanie, popularność i licencje.
  • 100github-repo-architect
    Zamienia pomysł na repozytorium w pełną architekturę GitHub: README, układ folderów, prompty, CI w GitHub Actions, szablony issues i pull requestów.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.