post start validation

Other Community v0.2.19

Skill notes

0. Shell Rule

Detect OS. Use Git Bash syntax on Windows (forward slashes, /dev/null).

1. Determine Scope

Classify changes by detecting file patterns: Frontend? — .ts, .tsx, .js, .jsx, .css, .vue, .svelte files Backend? — .java, .kt, .py, .go, .rs, .rb files Infrastructure? — Dockerfile, docker-compose*, k8s/, .github/workflows/, *.tf Docs-only? — .md files only outside source directories

2. Read Governance Gates

The governance file defines which gates to run and in what order. If it specifies "biome → tsc → build" — run exactly that. If it specifies "pytest" — run that. The gates are project-specific; this skill is not.

3.0. Workspace-aware gate execution

If the discovery cache indicates a workspace: Read root governance gates (from workspace root .claude/governance.md) Identify which members have changes: check git diff --name-only HEAD paths For changed members with their own governance: read member governance, merge with root gates Execute merged gates in order: root cross-stack gates first, then member-specific gates

Gate annotations (v2 format)

Path-scoped sections: ### Frontend (path: frontend/) Before running any command in this section, cd into the specified directory. After the section completes, cd back to the project root. Example: Conditional sections: ### TypeScript (if: tsconfig.json) Skip the ENTIRE section if the referenced file does not exist at project root. Check before running any gate in the section: Gate classifications (suffix on individual gate lines):

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Other
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
98 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@ruah-dev · v0.2.19 · MIT
Token usage
Lean
Setup complexity
Manual integration
External API key
Not required
Operating systems
Windows · Docker
Runtime requirements
Python · Docker
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
  • Env read
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Author source file SKILL.md

# /post-start-validation

Run **after completing any task**. Discovers what changed, applies governance gates, captures knowledge, commits and verifies.

---

## 0. Shell Rule

Detect OS. Use Git Bash syntax on Windows (forward slashes, /dev/null).

---

## 1. Determine Scope

```
git diff --name-only HEAD 2>/dev/null || git status --short
```

Classify changes by detecting file patterns:
- **Frontend?** — `.ts`, `.tsx`, `.js`, `.jsx`, `.css`, `.vue`, `.svelte` files
- **Backend?** — `.java`, `.kt`, `.py`, `.go`, `.rs`, `.rb` files
- **Infrastructure?** — `Dockerfile`, `docker-compose*`, `k8s/`, `.github/workflows/`, `*.tf`
- **Docs-only?** — `.md` files only outside source directories

> **Skip rules:** Docs-only → skip code checks. Infra-only → skip local checks.

---

## 2. Read Governance Gates

```
Read .claude/governance.md
```

> The governance file defines which gates to run and in what order. If it specifies "biome → tsc → build" — run exactly that. If it specifies "pytest" — run that. The gates are project-specific; this skill is not.

---

## 3. Run Gates

### 3.0. Workspace-aware gate execution

If the discovery cache indicates a workspace:
1. Read root governance gates (from workspace root `.claude/governance.md`)
2. Identify which members have changes: check `git diff --name-only HEAD` paths
3. For changed members with their own governance: read member governance, merge with root gates
4. Execute merged gates in order: root cross-stack gates first, then member-specific gates

### Gate annotations (v2 format)

**Path-scoped sections:** `### Frontend (path: frontend/)`
Before running any command in this section, `cd` into the specified directory. After the section completes, `cd` back to the project root. Example:
```bash
(cd frontend/ && npx biome check .) || exit 1
```

**Conditional sections:** `### TypeScript (if: tsconfig.json)`
Skip the ENTIRE section if the referenced file does not exist at project root. Check before running any gate in the section:
```bash
[ -e tsconfig.json ] || echo "Skipping TypeScript gates (no tsconfig.json)"
```

**Gate classifications** (suffix on individual gate lines):
- `# [MANDATORY]` (default) — stop execution on failure
- `# [OPTIONAL]` — log failure, print warning, continue to next gate
- `# [ADVISORY]` — always run, log result, never stop

When an OPTIONAL gate fails:
1. Print: `⚠ [OPTIONAL] <gate command> failed — continuing`
2. Record in gate_results.failed but do NOT exit
3. Proceed to the next gate in order

When an ADVISORY gate fails:
1. Print: `ℹ [ADVISORY] <gate command> failed (informational)`
2. Record in gate_results.failed for session state
3. Always proceed

**Inheritance marker:** `## Gates (inherit: root)`
When found in a member's governance.md, merge root gates first (prepend), then member gates (append). Execute in order.

### Standard execution (no annotations)

Execute the gates defined in governance.md, in order. Stop at first MANDATORY failure.

**Common patterns** (the governance file will specify which apply):

Frontend gates:
```
# Lint (biome, eslint, etc.)
# Type check (tsc --noEmit, mypy, etc.)
# Build (npm run build, etc.)
# Test (vitest, jest, pytest, etc.)
```

Backend gates:
```
# Compile (gradlew compileJava, cargo build, go build, etc.)
# Test (gradlew test, pytest, cargo test, go test, etc.)
# Check (gradlew check, clippy, etc.)
```

> Use `rtk` prefix on all commands for token compression.

---

## 3.5. Gate Auto-Fix (Bounded Retry)

If a gate command fails, attempt an automatic fix before escalating to the user.

**Step 1 — Classify the failure:**

| Error pattern | Classification | Action |
|---|---|---|
| Lint errors with auto-fix flag | **Auto-fixable** | Run linter with `--fix` / `--write` |
| Format errors (prettier, rustfmt, ruff, biome) | **Auto-fixable** | Run the formatter on affected files |
| Unused imports / variables | **Auto-fixable** | Remove them |
| Missing semicolons, trailing commas | **Auto-fixable** | Fix inline |
| Type errors in files you changed this session | **Maybe fixable** | Attempt one fix, re-run |
| Failing tests | **NOT auto-fixable** | Escalate — tests may be validating the change |
| Build errors from missing dependencies | **NOT auto-fixable** | Escalate |
| Errors in files you did NOT change | **NOT auto-fixable** | Escalate — pre-existing issue |

**Step 2 — If auto-fixable, apply the fix:**

```bash
# Lint auto-fix (use whichever the project has)
npx eslint --fix <files>           # or: npx biome check --write <files>
npx prettier --write <files>       # format
cargo clippy --fix --allow-dirty   # Rust
ruff check --fix <files>           # Python
ruff format <files>                # Python format
```

For other mechanical errors (unused imports, missing semicolons): edit the files directly.

**Auto-fix boundaries:**
- ONLY edit files within this repository
- NEVER install new global packages as a fix
- NEVER modify files outside the repo or system config
- NEVER delete files that weren't created this session
- If a fix requires out-of-bounds changes → escalate to user

**Step 3 — Re-run ONLY the failed gate.** Do not re-run gates that already passed.

**Step 4 — Bounded retry:**
- Maximum **2 auto-fix attempts** per gate
- If the same gate fails after 2 attempts → **stop and escalate to the user**
- Never retry the exact same fix that didn't work
- The circuit breaker hook (`PostToolUseFailure`) provides an additional safety net

**Step 5 — After ALL gates pass, write the sentinel:**

```bash
touch .claude/.gates-passed
```

This sentinel is:
- **Checked** by the auto-post-start hook before commits
- **Cleared** by pre-start-context at the beginning of each session
- Ensures gates are verified at least once per session before any commit

---

## 4. Cross-Stack Consistency

If both frontend and backend changed, verify alignment:
- API contracts match (routes, types, schemas)
- New environment variables added to `.env.example`
- Docker/K8s configs updated if services changed
- Migration files don't conflict

> Read governance.md for project-specific alignment points.

---

## 5. Security Review

```
Grep -rn "sk_live\|sk_test\|AKIA\|password.*=.*['\"]" . --type ts --type java --type py 2>/dev/null | grep -v node_modules | grep -v test | grep -v example | head -20
```

For every new endpoint/route added:
- Authentication required (unless explicitly public)?
- Input validation present?
- No mass-assignment (explicit DTOs, not raw entity binding)?

> Read governance.md for project-specific security requirements (rate limiting, file upload rules, auth patterns).

---

## 6. Documentation

If changes introduced new endpoints, services, env vars, or architecture changes — update README.

If changes are bug fixes, refactors, tests, CSS — skip.

---

## 7. Knowledge Capture

If MemStack rules exist (`.claude/rules/diary.md`), follow them — add-insight, add-session, set-context.

If not, at minimum report:
- What was done
- Key decisions made and why
- Any gotchas discovered
- What to do next session

---

## 8. Self-Update

Check: did any governance rule get violated during this session? Did any discovery instruction find something unexpected?

**If governance was violated:** Flag it to the user. Do NOT change governance.md.

**If the pre-start or post-start skill itself had a gap** (missing a check, wrong assumption): Update the skill file. Log the change.

> Discovery instructions rarely need updating — they read the filesystem. Governance rules only change when the user decides.

---

## 9. Commit & Deploy

Read governance.md for:
- Branch strategy (feature branches or trunk-based?)
- Commit convention (conventional commits or free-form?)
- Autonomy level (auto-commit after gates or ask first?)

Execute accordingly:

```
git add <files>
git commit -m "<type>: <description>

Co-Authored-By: Claude <noreply@anthropic.com>"
```

Then:
- Push to remote
- Monitor CI (if configured): `gh run list --limit 3`
- Verify deployment (if governance specifies how)

### Branch cleanup (if feature branch workflow)

After merge:
```
git branch -d <branch-name>
```

---

## Skip Rules

| Change type | Skip |
|---|---|
| Docs-only | S3-S5 |
| Infra-only | S3 (local gates), S6 |
| Backend-only (no API change) | Frontend gates |
| Frontend-only (no API change) | Backend gates |
| CSS/styling only | Backend gates, S4, S5 |

---

## 10. Write Session State

Write `.claude/.session-state.json` for warm starts next session:

```json
{
  "version": 1,
  "timestamp": "<ISO 8601 — use: date -u +%Y-%m-%dT%H:%M:%SZ>",
  "branch": "<current branch>",
  "commit": "<HEAD short hash>",
  "task_summary": "<one-line summary of what was accomplished>",
  "gate_results": {
    "passed": ["<gate commands that passed>"],
    "failed": ["<gate commands that failed — empty if all passed>"],
    "auto_fixed": ["<gates that needed auto-fix before passing>"]
  },
  "files_changed": ["<files modified this session>"],
  "open_questions": ["<unresolved decisions or ambiguities>"],
  "next_steps": ["<suggested actions for next session>"]
}
```

This file is consumed by pre-start Section 0.1 for warm starts. It enables the next session to:
- Skip re-explaining context if the user is continuing the same work
- Surface open questions and next steps immediately
- Combined with the discovery cache, achieve near-zero-latency startup

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.