# Spec Flow

> Use when planning, executing, checkpointing, finishing, or inspecting

- **Type:** Skill
- **Install:** `agentstack add skill-alexei-led-cc-thingz-spec-flow`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [alexei-led](https://agentstack.voostack.com/s/alexei-led)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [alexei-led](https://github.com/alexei-led)
- **Source:** https://github.com/alexei-led/cc-thingz/tree/master/dist/claude/plugins/spec-flow/skills/spec-flow

## Install

```sh
agentstack add skill-alexei-led-cc-thingz-spec-flow
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.md` for artifact shapes, planning rules, task quality, and mini-interview guidance.
- `references/specctl-commands.md` for 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:

```bash
scripts/specctl init
```

Then plan the first executable slice. Do not build a full backlog unless the user asks.

Existing project:

1. Inspect current code and project instructions.
2. Create the smallest task that can be verified.
3. Link optional REQ/EPIC context only when it reduces ambiguity.

Stop and resume:

```bash
scripts/specctl checkpoint --message ""
scripts/specctl session handoff
```

Iterate:

```bash
scripts/specctl ready
scripts/specctl start TASK-
# implement + verify
scripts/specctl done TASK- --summary "..." --tests "..."
```

## Modes

### Orient

Use when the user asks for status, next task, resume, health, or what to do next.

```bash
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.

1. Run `scripts/specctl init`.
2. Check status/session before changing files.
3. Ask 3-5 questions only if the slice is unclear.
4. Optionally scan the codebase for relevant files and patterns.
5. Draft the smallest useful artifact set:
   - one clear slice → one `TASK-*`
   - several slices → one `EPIC-*` plus tasks
   - unclear WHY/WHAT → one `REQ-*` first
6. Show the proposed plan and ask before writing.
7. Write with `scripts/specctl new task ` when possible, then edit details.
8. Run `scripts/specctl validate` and `scripts/specctl ready`.

Do not write implementation code in plan files.

### Execute

Use when the user wants to work, continue, or implement a task.

1. Run `scripts/specctl status` and `scripts/specctl session show`.
2. If a session exists, ask whether to resume, checkpoint, clear, or stop.
3. Select with `scripts/specctl ready` or verify the named task with `scripts/specctl show TASK-`.
4. Start with `scripts/specctl start TASK-`.
5. Make a short implementation plan; ask before editing.
6. Implement only the approved task.
7. Run project-appropriate checks from project instructions and changed files.
8. Show scoped diff or `scripts/specctl session handoff` before close.
9. Close with `scripts/specctl done ...` or checkpoint with `scripts/specctl checkpoint`.

### Checkpoint or close

Use when the user stops, switches context, or finishes.

Checkpoint:

```bash
scripts/specctl checkpoint --message ""
```

Close:

```bash
scripts/specctl done TASK- \
  --summary "" \
  --tests "" \
  --files "" \
  --commits ""
```

`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

```markdown
## Spec flow

Mode: orient | plan | execute | checkpoint | close
Task: 
Status: 
Evidence: 
Next: 
```

## Failure handling

- No `.spec/`: run or offer `scripts/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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [alexei-led](https://github.com/alexei-led)
- **Source:** [alexei-led/cc-thingz](https://github.com/alexei-led/cc-thingz)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-alexei-led-cc-thingz-spec-flow
- Seller: https://agentstack.voostack.com/s/alexei-led
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.