# Workflow

Choose the right workflow for your task - from spec-driven development to quick fixes

## [Workflow](https://knowns.sh/docs/workflow#workflow)

Pick the right flow for your task. All workflows use `/kn-*` skills that AI understands.

Use this page when you need to decide whether a task should go through full spec-driven development, a normal task workflow, or a quick fix path.

## [Choose Your Flow](https://knowns.sh/docs/workflow#choose-your-flow)

| Flow | When to Use | Steps |
| --- | --- | --- |
| **Full SDD** | Large features, new systems | init → spec → plan → research → implement → verify → extract |
| **Normal** | Small features, enhancements | init → plan → implement |
| **Quick Fix** | Bug fixes, hotfixes | init → implement |

* * *

## [Full SDD Flow](https://knowns.sh/docs/workflow#full-sdd-flow)

**For large features that need specifications first.**

### [1. Initialize Session](https://knowns.sh/docs/workflow#1-initialize-session)

```
/kn-init
```

Reads project context, conventions, and current task backlog.

### [2. Create Spec](https://knowns.sh/docs/workflow#2-create-spec)

```
/kn-spec user-auth
```

AI creates a spec document with:

- Overview & requirements
- Acceptance criteria
- Scenarios & edge cases

Saved to `.knowns/docs/specs/user-auth.md`

### [3. Generate Tasks from Spec](https://knowns.sh/docs/workflow#3-generate-tasks-from-spec)

```
/kn-plan --from @doc/specs/user-auth
```

AI breaks the spec into tasks, each linked to the spec via `spec:` field and `fulfills` for AC mapping.

### [Task-Spec Linking with Fulfills](https://knowns.sh/docs/workflow#task-spec-linking-with-fulfills)

The `fulfills` field creates explicit mapping between tasks and spec ACs:

```
# Create task linked to spec ACs
knowns task create "Implement search API" \
  --spec specs/semantic-search \
  --fulfills AC-1,AC-2

# Or via MCP
mcp__knowns__create_task({
  "title": "Implement search API",
  "spec": "specs/semantic-search",
  "fulfills": ["AC-1", "AC-2"]
})
```

| Field | Purpose |
| --- | --- |
| `spec` | Links task to spec document |
| `fulfills` | Maps task to specific spec ACs (e.g., AC-1, AC-2) |

**Auto-sync:** When task is marked done, the corresponding spec ACs are automatically checked.

### [4. Research (Optional)](https://knowns.sh/docs/workflow#4-research-optional)

```
/kn-research
```

Explore codebase patterns before coding. Useful for unfamiliar areas.

### [5. Implement](https://knowns.sh/docs/workflow#5-implement)

```
/kn-implement 42
```

AI reads the task, follows spec reference, and implements. ACs auto-sync between task and spec.

### [6. Verify](https://knowns.sh/docs/workflow#6-verify)

```
/kn-verify
```

Checks:

- All ACs completed
- References resolve
- Spec coverage

### [7. Extract Knowledge (Optional)](https://knowns.sh/docs/workflow#7-extract-knowledge-optional)

```
/kn-extract
```

Extract reusable patterns to docs for future reference.

* * *

## [Normal Flow](https://knowns.sh/docs/workflow#normal-flow)

**For small features with existing tasks.**

### [1. Initialize](https://knowns.sh/docs/workflow#1-initialize)

```
/kn-init
```

### [2. Plan](https://knowns.sh/docs/workflow#2-plan)

```
/kn-plan 42
```

AI reads task, searches related docs, creates implementation plan.

### [3. Implement](https://knowns.sh/docs/workflow#3-implement)

```
/kn-implement 42
```

Code it. AI tracks progress and checks ACs.

* * *

## [Quick Fix Flow](https://knowns.sh/docs/workflow#quick-fix-flow)

**For bug fixes and hotfixes.**

### [1. Initialize](https://knowns.sh/docs/workflow#1-initialize-1)

```
/kn-init
```

### [2. Implement](https://knowns.sh/docs/workflow#2-implement)

```
/kn-implement 42
```

Just code it. AI reads task and fixes the issue.

* * *

## [All Skills Reference](https://knowns.sh/docs/workflow#all-skills-reference)

| Skill | Description |
| --- | --- |
| `/kn-init` | Read project context & docs |
| `/kn-spec <name>` | Create spec document |
| `/kn-plan [task]` | Create implementation plan |
| `/kn-research` | Explore codebase patterns |
| `/kn-implement <task>` | Implement a task |
| `/kn-verify` | Check ACs & references |
| `/kn-extract` | Extract patterns to docs |
| `/kn-doc` | Manage documentation |
| `/kn-task` | Manage tasks |
| `/kn-template` | Run code templates |

* * *

## [CLI Fallback](https://knowns.sh/docs/workflow#cli-fallback)

If skills aren't available, use CLI commands directly:

```
# Initialize
knowns doc list --plain
knowns doc "README" --plain --smart

# Take task
knowns task edit 42 -s in-progress -a @me
knowns time start 42

# Plan
knowns task edit 42 --plan $'1. Step one
2. Step two'

# Check AC after completing work
knowns task edit 42 --check-ac 1
knowns task edit 42 --append-notes "✓ Done: feature X"

# Complete
knowns time stop
knowns task edit 42 -s done
```

* * *

## [Definition of Done](https://knowns.sh/docs/workflow#definition-of-done)

A task is **Done** when:

- [ ] All acceptance criteria checked
- [ ] Implementation notes added
- [ ] Timer stopped
- [ ] Tests passing
- [ ] Status set to `done`

## [Handling Blockers](https://knowns.sh/docs/workflow#handling-blockers)

```
# Mark as blocked
knowns task edit 42 -s blocked
knowns task edit 42 --append-notes "Blocked: Waiting for API spec"

# When unblocked
knowns task edit 42 -s in-progress
knowns task edit 42 --append-notes "Unblocked: API spec received"
```