alexei-led/spec-flow
src/skills/spec-flow/SKILL.md
Use when planning, executing, checkpointing, finishing, or inspecting lightweight spec-driven work. Runs one task at a time using `.spec/` markdown files and the bundled `specctl` helper. NOT for broad product discovery beyond a short requirement interview.
$ install --global
skillsauthnpx skillsauth add alexei-led/claude-code-config spec-flowInstall 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 5, 2026, 3:40 AM9.2s6 files scanned
SKILL.md
- name:
- spec-flow
- description:
- Use when planning, executing, checkpointing, finishing, or inspecting lightweight spec-driven work. Runs one task at a time using `.spec/` markdown files and the bundled `specctl` helper. NOT for broad product discovery beyond a short requirement interview.
Spec flow
Lightweight spec loop for controlled task-by-task work.
Loop: plan one slice → execute one task → checkpoint or close → repeat.
specctl owns state. Do not edit task status or .spec/SESSION.yaml by hand.
Read first
references/method.mdfor artifact shapes, planning rules, task quality, and mini-interview guidance.references/specctl-commands.mdfor CLI commands.
State model
.spec/tasks/TASK-*.md— executable vertical slices. Required for work..spec/epics/EPIC-*.md— optional group for multi-task plans..spec/reqs/REQ-*.md— optional WHY/WHAT context for ambiguous work..spec/SESSION.yaml— active task, step, base commit..spec/PROGRESS.md— append-only activity log.
Task states: todo, in-progress, done.
Common flows
New project:
scripts/specctl init
Then plan the first executable slice. Do not build a full backlog unless the user asks.
Existing project:
- Inspect current code and project instructions.
- Create the smallest task that can be verified.
- Link optional REQ/EPIC context only when it reduces ambiguity.
Stop and resume:
scripts/specctl checkpoint --message "<where to resume>"
scripts/specctl session handoff
Iterate:
scripts/specctl ready
scripts/specctl start TASK-<id>
# implement + verify
scripts/specctl done TASK-<id> --summary "..." --tests "..."
Modes
Orient
Use when the user asks for status, next task, resume, health, or what to do next.
scripts/specctl status
scripts/specctl ready
scripts/specctl session handoff
scripts/specctl validate
Report active session, next ready task, validation issues, and the smallest next action.
Plan
Use when the user has an idea, requirement, bug, or project gap and wants an executable plan.
- Run
scripts/specctl init. - Check status/session before changing files.
- Ask 3-5 questions only if the slice is unclear.
- Optionally scan the codebase for relevant files and patterns.
- Draft the smallest useful artifact set:
- one clear slice → one
TASK-* - several slices → one
EPIC-*plus tasks - unclear WHY/WHAT → one
REQ-*first
- one clear slice → one
- Show the proposed plan and ask before writing.
- Write with
scripts/specctl new task <slug>when possible, then edit details. - Run
scripts/specctl validateandscripts/specctl ready.
Do not write implementation code in plan files.
Execute
Use when the user wants to work, continue, or implement a task.
- Run
scripts/specctl statusandscripts/specctl session show. - If a session exists, ask whether to resume, checkpoint, clear, or stop.
- Select with
scripts/specctl readyor verify the named task withscripts/specctl show TASK-<id>. - Start with
scripts/specctl start TASK-<id>. - Make a short implementation plan; ask before editing.
- Implement only the approved task.
- Run project-appropriate checks from project instructions and changed files.
- Show scoped diff or
scripts/specctl session handoffbefore close. - Close with
scripts/specctl done ...or checkpoint withscripts/specctl checkpoint.
Checkpoint or close
Use when the user stops, switches context, or finishes.
Checkpoint:
scripts/specctl checkpoint --message "<where to resume>"
Close:
scripts/specctl done TASK-<id> \
--summary "<what changed>" \
--tests "<checks passed or not run: reason>" \
--files "<changed files or none>" \
--commits "<sha or none>"
specctl done needs --summary and --tests unless the user explicitly approves --force.
Guardrails
- One task is the execution unit.
- Checkpoint before stopping or switching.
- Keep work inside the approved task.
- File follow-up tasks instead of expanding scope.
- Verification is adaptive; do not assume every project has
make. - User approval is required before writing plan files, editing code, forcing state, or clearing another session.
Output
## Spec flow
Mode: orient | plan | execute | checkpoint | close
Task: <TASK-id or none>
Status: <ready | in-progress | checkpointed | done | blocked>
Evidence: <commands/tests/checks or skipped reason>
Next: <one command or action>
Failure handling
- No
.spec/: run or offerscripts/specctl init. - Active session conflicts: show handoff and ask before switching.
- No ready tasks: show blockers; plan new work or finish blockers.
- Validation fails: fix the smallest artifact issue before work.
- Verification fails: fix within scope, checkpoint, or stop; do not mark done.
Related Skills
alexei-led/writing-shell
tools
VerifiedTrustedCommunity
Idiomatic shell development for POSIX sh, Bash, Zsh, Fish, hooks, CI shell steps, and scriptable CLI glue. Use when writing or changing `.sh`, `.bash`, `.zsh`, `.fish`, `.bats`, shell functions, shell pipelines, or command-runner recipes. Emphasizes portability, quoting, safe filesystem/process handling, non-TUI CLI tools, ShellCheck, shfmt, Bats, and ShellSpec. NOT for Python, TypeScript, Go, web code, or infrastructure operations.
33SKILL.mdUpdated Jun 5, 2026
alexei-led/operating-infra
testing
VerifiedTrustedCommunity
Author, inspect, troubleshoot, and review infrastructure across IaC, Kubernetes, cloud resources, containers, CI/CD, and Linux hosts. Use when changing Terraform/OpenTofu, Kubernetes, Helm, Kustomize, Dockerfiles, GitHub Actions, AWS, GCP, Cloud Run, BigQuery, IAM, logs, instances, or service health. NOT for deploy/apply/rollback workflows (see deploying-infra). NOT for shell scripts or generic command pipelines (see writing-shell).
33SKILL.mdUpdated Jun 5, 2026
alexei-led/configuring-git-hygiene
development
VerifiedTrustedCommunity
Configure safe git workflow hygiene: pre-commit/pre-push hooks, Gitleaks secret scanning, .gitignore rules, local git config, and guardrails. Use when setting up git hooks, gitleaks/git leaks, staged pre-commit checks, pre-push validation, core.hooksPath, .gitignore, or git config best practices. NOT for creating commits (use committing-code), cleaning branches/worktrees (use cleanup-git), or creating worktrees (use using-git-worktrees).
33SKILL.mdUpdated Jun 5, 2026
alexei-led/browser-automation
tools
VerifiedTrustedCommunity
Browser automation for rendered UI exploration, validation, screenshots, recordings, and end-to-end flows. Use when a task needs an actual browser or rendered DOM: inspect UI state, click/fill forms, debug frontend behavior, capture evidence, verify a feature, or run/generate browser tests. NOT for API checks or pure logic tests where curl, unit tests, or JSDOM is cheaper.
33SKILL.mdUpdated Jun 5, 2026