Skip to content
Skills Library
Programming · Review & audit

verify-bootstrap

/verify-bootstrap

Use to check that a groundrules-bootstrapped project is coherent — version signatures, leftover placeholders, CLAUDE.md size, valid JSON, git, files vs generatedFiles — e.g. before a release or after edits. Supports --fix for trivial corrections.

Author
lozit ↗
Repository
groundrules ↗
Licence
MIT
Last repository change
09.10.2026

Assessment and security

98/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene13 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
7
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 09.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (7). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Use to check that a groundrules-bootstrapped project is coherent — version signatures, leftover placeholders, CLAUDE.md size, valid JSON, git, files vs generatedFiles — e.g. before a release or after edits. Supports --fix for trivial corrections.

Original author description

Use to check that a groundrules-bootstrapped project is coherent — version signatures, leftover placeholders, CLAUDE.md size, valid JSON, git, files vs generatedFiles — e.g. before a release or after edits. Supports --fix for trivial corrections.

How it works

  1. Phase 1 — Prerequisites
  2. Phase 2 — Per-file validations
  3. Phase 3 — Structural validations
  4. Phase 4 — Report output
  5. Phase 5 — Fix mode (if --fix)
  6. Phase 6 — Final recap
  7. Important rules
Original SKILL.md headings · 174 lines, 1,130 words
SKILL.md preview
---
name: verify-bootstrap
description: Use to check that a groundrules-bootstrapped project is coherent — version signatures, leftover placeholders, CLAUDE.md size, valid JSON, git, files vs generatedFiles — e.g. before a release or after edits. Supports --fix for trivial corrections.
disable-model-invocation: true
allowed-tools: Read, Edit, Bash, AskUserQuestion
---

# /groundrules:verify-bootstrap

You will check the coherence of a groundrules-bootstrapped project. You will produce a ✅ / ⚠️ / ❌ report and, on request, fix the safe items.

If `$ARGUMENTS` contains `--fix` (or `fix`), switch to **fix mode** after the report. Otherwise, report only.

## Phase 1 — Prerequisites

1. `.groundrules.json` must exist in the cwd. **Legacy**: if only a pre-1.0 `.starter-kit.json` exists, read that instead (its version key is `starterKitVersion`) and add a ⚠️ to the report: *"pre-1.0 state file — run `/groundrules:migrate` to upgrade."* If neither exists: *"This project was not bootstrapped with groundrules, nothing to verify."* Stop.
2. Read `.groundrules.json` → extract:
   - `groundrulesVersion` → **EXPECTED_VERSION**
   - `generatedFiles` → list of files to validate
   - `bootstrappedWithVersion` (info; may be `null` for an adopted project)

## Phase 2 — Per-file validations

For each file in `generatedFiles`, run these checks in order:

### 2.1 Existence

`test -f <path>` → if absent, mark **❌ missing** and move to the next file (the following checks are moot).

### 2.2 Signature present

Read the **first 10 lines** of the file (to accommodate a YAML frontmatter that can run 8-9 lines: `---\nname: ...\npaths:\n  - "..."\n  - "..."\n---\n<!-- signature -->`). Search for the regex `<!-- generated-by: (groundrules|starter-kit) v([0-9]+\.[0-9]+\.[0-9]+) -->` (the `starter-kit` form is the pre-1.0 legacy name — accepted, but reported as **⚠️ legacy signature**, fixable with `--fix`):
- **Match** → extract the version (FOUND_VERSION), continue
- **No match** → **❌ signature missing**, run the following checks anyway

**Exceptions** (no HTML-comment signature possible — skip this check): **JSON files** (`.groundrules.json`, `.claude/settings.json`, etc. — HTML comment invalid in JSON) and **`.gitignore`** (generated from the plain `gitignore.minimal`, which carries no signature). Generally, any generated file that is **not** in the Markdown family (a `#`-comment or syntax-restricted plain file) is exempt — only Markdown/`.tpl`/rules files are expected to carry the `<!-- generated-by -->` signature.

**YAML frontmatter note**: for files starting with `---` (rules, skills), the signature **must** be on the line right after the closing `---`. E.g.:
```
---
paths:
  - "..."
---
<!-- generated-by: groundrules v1.13.0 -->
```

### 2.3 Version match

If a signature is found:
- `FOUND_VERSION == EXPECTED_VERSION` → **✅ version OK**
- Otherwise → **⚠️ version mismatch (FOUND_VERSION vs EXPECTED_VERSION)**

### 2.4 Leftover placeholders

Search the whole file content for the **known placeholders** from bootstrap phase 5 (exact whitelist):

```
\{\{(PROJECT_NAME|DESCRIPTION|STACK|DATE|HAS_PLAN|HAS_ARCHITECTURE|HAS_GLOSSARY|HAS_CHANGELOG|HAS_INBOX|HAS_DATA_MODEL|HAS_SECURITY|HAS_DESIGN_SYSTEM|HAS_ROADMAP|HAS_I18N|HAS_PROCESS|HAS_RELEASE|HAS_AGENT_EVALS|GLOBAL_CLAUDE_NOTE|REMOTE_PROVIDER|REMOTE_VISIBILITY|CONTENT|INTENT_SOURCE|GOAL|USERS|CONSTRAINTS|NONGOALS|ACCEPTANCE)\}\}
```

For every match, apply the **backtick rule** before flagging: a placeholder **wrapped in backticks** (`` `{{KEY}}` ``) is a *documentation reference* (a doc/CHANGELOG/PLAN line that mentions the placeholder by name), **not** an unsubstituted placeholder — **ignore it**. Only a **bare** occurrence (not inside backticks) is a real leftover. This matters on self-referential projects: a project's own `CHANGELOG.md`/`PLAN.md` legitimately contains backticked `{{HAS_PROCESS}}`, `{{INTENT_SOURCE}}`, etc.

- **No bare match** → **✅ no placeholder**
- **Bare match** → **❌ unsubstituted placeholders: {{PROJECT_NAME}}, {{DESCRIPTION}}, ...**

Also ignore generic illustrative tokens like `{{KEY}}`, `{{X}}`, `{{NNNN}}` — they aren't in the whitelist anyway, but they're always documentation about the concept.

**Exception**: if the file is in `skills/bootstrap/templates/` or is itself a `*.tpl`, skip this check (templates contain these placeholders by design — only relevant in the dogfood, not a normal user project).

## Phase 3 — Structural validations

### 3.1 `.git/`

`test -d .git` → **✅ git initialized** / **⚠️ no git** (maybe intentional but unusual)

### 3.2 CLAUDE.md size

If `CLAUDE.md` exists:
- `wc -l CLAUDE.md` → number of lines
- **≤ 200** → **✅ CLAUDE.md X/200 lines**
- **> 200** → **⚠️ CLAUDE.md X lines (target: < 200 — run `/groundrules:slim` for concrete extraction proposals)**

### 3.3 Valid JSON

For each of the following files if it exists:
- `.groundrules.json`
- `.claude/settings.json`
- `.claude-plugin/plugin.json` (present only if the project is itself a plugin)

JSON test: `python3 -c "import json,sys; json.load(open(sys.argv[1]))" <file>` (or `node -e "JSON.parse(require('fs').readFileSync('<file>'))"`).
- **OK** → **✅ valid JSON**
- **Parse error** → **❌ invalid JSON: <message>**

### 3.4 General coherence

- If `intent.source = "skipped"` but `docs/VISION.md` exists → **⚠️ inconsistency: intent skipped but vision present**
- If `intent.source` ≠ `"skipped"` but `docs/VISION.md` missing → **❌ vision expected but absent**
- **Adopted project** (`adopted: true`): `bootstrappedWithVersion` is `null` by design — do not flag it. If `adoptedFiles` is present, check each listed path exists (**⚠️** if a mapped file is gone).

## Phase 4 — Report output

Clear text format, grouped by category:

```
=== Verify Bootstrap Report ===
Project: <project name from .groundrules.json>
Expected version: <EXPECTED_VERSION>
Bootstrapped with: <bootstrappedWithVersion>

--- Files (X/Y tracked) ---
✅ docs/decisions/README.md
   ✅ signature v1.3.3 · ✅ no placeholder
✅ docs/VISION.md
   ✅ signature v1.3.3 · ✅ no placeholder
⚠️ docs/ARCHITECTURE.md
   ⚠️ signature v0.10.0 (expected v1.3.3)
❌ docs/missing-file.md
   ❌ file absent

--- Structural ---
✅ .git/ initialized
✅ CLAUDE.md: 78/200 lines
✅ .groundrules.json valid JSON
✅ .claude/settings.json valid JSON
✅ intent/vision coherence

--- Summary ---
✅ N items OK
⚠️ M items need attention (version mismatch, size)
❌ K items in error (missing, placeholders, invalid JSON)
```

## Phase 5 — Fix mode (if `--fix`)

> If `$ARGUMENTS` does not contain `--fix`, **skip this phase**. Show only: *"To apply trivial fixes, re-run with: `/groundrules:verify-bootstrap --fix`"*

### Auto-fixable items

- **Version mismatch (⚠️)**: replace the signature line `<!-- generated-by: groundrules vX.Y.Z -->` with the current version via `Edit`.
- **Legacy signature (⚠️)**: rewrite `<!-- generated-by: starter-kit vX.Y.Z -->` as `<!-- generated-by: groundrules v<current> -->` via `Edit`.

### NON auto-fixable items (show, don't touch)

- Missing file → the user must decide (recreate via `migrate`? forget it?)
- Leftover `{{KEY}}` placeholder → bootstrap bug, to report (mapping issue in SKILL.md)
- Invalid JSON → manual editing required
- CLAUDE.md > 200 lines → manual refactor (extract to `.claude/rules/`)
- intent/vision inconsistency → the user decides

### Confirmation

For version-mismatch fixes:
- List the affected files
- `AskUserQuestion`: `Fix the N signatures` / `Cancel`
- If yes, apply the Edits
- Show: `✅ Signatures fixed: N files`

## Phase 6 — Final recap

```
=== Result ===
Mode: report / fix
Fixes applied: N signatures
Remaining items: K errors, M warnings
```

If everything is ✅: *"Project coherent. No fix needed."*

If remaining errors: per-category suggestion of manual action.

**NEVER commit automatically** — let the user review the signature fixes before committing.

## Important rules

- **Read-only by default**: without `--fix`, the skill modifies no file.
- **Fix limited to signatures**: any other kind of correction requires human intervention.
- **No effect on `.groundrules.json`**: the skill does not modify state — it reports and fixes user files only.
- For the signature regex, accept `v0.0.0` (3 numbers separated by `.`) with no length constraint — future-proof.
- If both `python3` and `node` are absent for the JSON check, use a fallback: `cat <file> | python -m json.tool > /dev/null 2>&1` or simply skip with a warning *"No JSON parser available"*.

Versions

RepositoryScoreLicence
This page · lozit/groundrules98MIT
shimo4228/claude-harness100MIT

Database snapshot: 13.11.2026 · package version 0881a515105c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100bootstrap
    Use when starting a new, empty project and you want the full groundrules structure generated interactively (CLAUDE.md, docs/, intent capture, git init, optional remote).
  • 95project-setup
    Project configuration initialization. Use when: first-time setup, auto-detecting framework, replacing CLAUDE.md placeholders. Not for: ongoing config checks (use claude-health), skill creation (use skill-creator). Output: configured CLAUDE.md + project settings + rules + hooks.
  • 100adopt
    Use when bringing an existing (brownfield) project under groundrules: it scans, maps existing files to groundrules roles, captures intent from existing docs, and generates only what's missing. Never overwrites.
  • 96repo-bootstrap
    Use when the user asks to bootstrap a new repo or project.
  • 100bootstrap-v6-install
    Add Bootstrap 6 to a project and set it up for local development. Use when installing Bootstrap, adding Bootstrap to a new or existing project, or setting up Bootstrap's CSS and JavaScript via CDN or a package manager.
  • 95bootstrap-v5-v6-migration
    Migrate projects from Bootstrap 5 to Bootstrap 6. Use when upgrading from Bootstrap 5, migrating v5 to v6, or updating v5 class names, components, Sass, or JavaScript to the latest version. For Bootstrap 4 projects, start with the v4-to-v6 migration skill instead.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.