Workflow

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

4 min read

Workflow

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

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

For large features that need specifications first.

1. Initialize Session

/kn-init

Reads project context, conventions, and current task backlog.

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

/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

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)

/kn-research

Explore codebase patterns before coding. Useful for unfamiliar areas.

5. Implement

/kn-implement 42

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

6. Verify

/kn-verify

Checks:

All ACs completed
References resolve
Spec coverage

7. Extract Knowledge (Optional)

/kn-extract

Extract reusable patterns to docs for future reference.

Normal Flow

For small features with existing tasks.

1. Initialize

/kn-init

2. Plan

/kn-plan 42

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

3. Implement

/kn-implement 42

Code it. AI tracks progress and checks ACs.

Quick Fix Flow

For bug fixes and hotfixes.

1. Initialize

/kn-init

2. Implement

/kn-implement 42

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

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

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

A task is Done when:

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"