tkersey/spec-lint
codex/skills/spec-lint/SKILL.md
Lint generated implementation specs/proposed plans for missing non-goals, weak proof, unmapped requirements, absent rollback/abort criteria, unresolved material questions, missing primary invariant, missing receipts, unaccounted subagents, skipped challenge/fresh-eyes pass, oversized audit prose, or plan churn. Use for `$spec-lint`, lint this spec, implementation-ready plan checks, proof/rollback/traceability checks, or is this more plan or better plan.
$ install --global
skillsauthnpx skillsauth add tkersey/dotfiles spec-lintInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jun 4, 2026, 5:40 AM104.5s5 files scanned
SKILL.md
- name:
- spec-lint
- description:
- Lint generated implementation specs/proposed plans for missing non-goals, weak proof, unmapped requirements, absent rollback/abort criteria, unresolved material questions, missing primary invariant, missing receipts, unaccounted subagents, skipped challenge/fresh-eyes pass, oversized audit prose, or plan churn. Use for `$spec-lint`, lint this spec, implementation-ready plan checks, proof/rollback/traceability checks, or is this more plan or better plan.
- version:
- 1.2.0
- base_file_sha:
- 1d704b912216b180d2b05e7bbc6af61c719f5c72
Spec Lint
Mission
Decide whether a generated spec is ready for implementation handoff.
A spec is ready only if two competent implementers would produce materially similar solutions and know how to prove completion.
Required checks
Fail if any are missing or vague:
- Objective
- Context / Current State
- Locked Decisions
- Scope
- Non-Goals
- Requirements
- Design / Implementation Approach
- Dependency-Ordered Implementation Sequence
- Requirement-to-Test Traceability
- Proof Commands
- Risks and Edge Cases
- Rollback / Abort Criteria
- Binary Done-State
- Invariant Challenge for balanced, strict, or campaign work
- Fresh-Eyes Pass for balanced, strict, or campaign work
- Spec Pipeline Receipt when linting
$spec-pipelineoutput
Semantic lint rules
Fail or warn when:
- a major requirement lacks a test, check, demo, benchmark, trace, or review proof;
- rollback says only "revert" without naming trigger or blast radius;
- open questions are material and lack owner/default/consequence;
- the spec creates a second source of truth;
- the plan changes objective in
Round Delta; - audit sections repeat rationale without changing implementer behavior;
- strictness profile is too weak for public API, migration, security, performance, or multi-wave campaigns;
- proof is scaffold-only when runtime behavior is the success criterion;
grill_rounds: 0but the no-grill justification is empty or generic;- subagent budget or accounting is missing after fan-out;
blockedappears withoutblocked_receipt;- the output permits mutation before gate, challenge, fresh-eyes, and lint pass.
Output
SPEC_READY: true|false
blocking_errors:
material_risks:
preferences:
missing_sections:
unmapped_requirements:
rollback_gaps:
proof_gaps:
receipt_gaps:
subagent_gaps:
churn_signals:
recommended_next_action: proceed_to_plan | return_to_grill | revise_spec | run_spec_challenge | campaign_checkpoint
Script helper
python codex/skills/spec-lint/scripts/spec_lint.py --strict-receipts path/to/spec.md
The helper is structural. The model must still judge semantic quality.
Related Skills
tkersey/beads-workflow
tools
VerifiedTrustedCommunity
Convert markdown plans into beads with dependencies using br CLI. Use when creating task graphs, polishing beads before implementation, or bridging planning to agent swarm execution.
57SKILL.mdUpdated Jun 4, 2026
tkersey/opt
development
VerifiedTrustedCommunity
Orchestrate Codex skill optimization during active sessions through $cas goal control, $shadow single-session evidence, $tune diagnosis/refinement briefs, and the skill-optimizer custom subagent. Trigger for $opt, skill optimization loops, session-driven skill tuning, meta-skill audits, or explicit validated skill edits. Do not use for general code optimization, product optimization, or performance tuning.
57SKILL.mdUpdated May 31, 2026
tkersey/fresh-eyes-blunder-pass
development
VerifiedTrustedCommunity
Run a targeted fresh-eyes blunder pass over code, specs, plans, adjudications, closure gates, skill edits, or negative-evidence ledgers. Trigger when asked to reread with fresh eyes, find obvious bugs, catch mistakes/oversights/omissions, check for embarrassing misses, or perform a second independent blunder pass before closure. Do not use as a substitute for implementation, adjudication, or verification; use it as the final falsification/check pass for those workflows.
57SKILL.mdUpdated May 29, 2026
tkersey/shadow
development
VerifiedTrustedCommunity
Explicitly shadow, tail, watch, follow, monitor, supervise, or companion exactly one Codex session id/path through `$seq`, then apply a named target skill as an interpretation/reporting/proposal/action lens until the watched session stops.
57SKILL.mdUpdated May 26, 2026