Skip to content
/
Tier B A4 Markdown scaffold

SDD (Solokit)

sdd-session-ankushdixit · ankushdixit/sdd · ★ 61 · last commit 2026-01-16

Eliminate AI context loss between sessions by reconstructing full work state from git history and spec files at each session start.

Best whenMulti-session continuity achieved through git history injection is more reliable than memory databases — no infrastructure required.
Skip ifStarting work without sk init / work item creation, Manual session management without sk start/end
vs seeds
openspec(command-per-phase pattern), but uniquely ships a Python CLI (sk) with persistent work item state, multi-session commit …
Primitive shape 18 total
Commands 17 Subagents 1
00

Summary

SDD / Solokit — Summary

Solokit (published as pip install solokit, slug sdd-session-ankushdixit) is a session-driven development framework for solo developers building production software with AI assistants. It provides an sk CLI that manages work items, starts sessions with comprehensive AI briefings (including previous session commits, related learnings, and spec files), enforces quality gates at session end, and persists learnings in a growing knowledge base. The framework ships 17 Claude Code slash commands (start, end, work-new, work-list, work-update, etc.), 1 agent (codebase-auditor), and a Python backend with 4 scaffolding stacks (T3, FastAPI, Refine, Next.js). Quality tiers from Essential (60% coverage) to Production-Ready (monitoring + observability) are selectable at sk init. The core innovation is spec-first session management: each work item has a .session/specs/{id}.md file as single source of truth, and the AI briefing at session start includes the full spec plus previous session's git history.

Differs from seeds: Closest to agent-os (bash install, structured markdown workflow) and spec-driver (spec-first, quality gates), but Solokit uniquely adds a Python-backed CLI with work item database, multi-session commit history injection into briefings, and 4-tier quality enforcement via automated gates at session end. Unlike openspec or spec-kit (which ship IDE command files), Solokit ships an actual Python CLI (solokit package on PyPI) with a sk binary that manages the full project lifecycle including session state, work item tracking, and knowledge capture.

01

Overview

SDD / Solokit — Overview

Origin

GitHub repo: ankushdixit/sdd (61 stars), MIT license, Python 3.11+. Published to PyPI as solokit. The repo README is titled "Solokit" throughout, suggesting the sdd repo slug is legacy. Two contributors.

Philosophy

From the README:

"Build production software alone with team-level sophistication." "Solokit is a complete development framework for solo developers building production software with AI assistants like Claude Code. It combines minimal scaffolding templates with comprehensive documentation, automated quality gates, intelligent session management, and AI-powered knowledge capture into a cohesive workflow that enables you to build alone with the sophistication of a 10-person engineering team."

The core problem it names:

"Solo developers using AI assistants face critical challenges: Setup Time Waste — hours configuring frameworks; Context Loss — AI forgets previous work between sessions; Quality Entropy — standards slip without enforcement; Knowledge Fragmentation — learnings and decisions get lost; Lack of Process — no systematic workflow for complex projects."

Key Ideas

  1. Session continuity: The sk start command injects the full work item spec, previous session commits, related learnings, and current git state into the AI's context.
  2. Spec-first architecture: .session/specs/{work_item_id}.md is the single source of truth. The briefing warns if the spec is incomplete.
  3. Quality tiers: Four explicit tiers (Essential, Standard, Comprehensive, Production-Ready) with concrete coverage thresholds and tooling gates.
  4. Knowledge compounding: 6-category AI learning classification with smart deduplication and searchable knowledge base.
  5. Multi-session continuity: For in-progress work items, briefings include all commits from previous sessions with file stats and quality gate results.

Antipatterns (implied)

  • Starting coding without initializing a work item
  • Manual session management without sk start/end
  • Skipping quality gates at session end
  • Ignoring CHANGELOG updates
02

Architecture

SDD / Solokit — Architecture

Distribution

  • Type: Python CLI package (PyPI)
  • Package name: solokit
  • Install: pip install solokit (macOS/Linux) or py -m pip install solokit (Windows)
  • Binary: sk
  • License: MIT

Install

pip3 install solokit
sk init    # new project
sk adopt   # existing project with code

sk init presents:

  • Stack selection: SaaS T3 Stack | ML/AI FastAPI | Dashboard Refine | Full-Stack Next.js
  • Quality tier: Essential | Standard | Comprehensive | Production-Ready
  • Options: CI/CD, Docker, environment templates

Directory Tree (post-init)

.session/
  specs/              # Work item specification files
    {work_item_id}.md # Single source of truth per work item
  temp_learnings.txt  # Staging area for session learnings

ARCHITECTURE.md       # AI-generated architecture guide
CHANGELOG.md          # Updated at each sk end

.claude/
  commands/           # 17 slash commands
    start.md
    end.md
    work-new.md
    work-list.md
    work-update.md
    work-show.md
    work-delete.md
    work-next.md
    work-graph.md
    status.md
    validate.md
    init.md
    adopt.md
    learn.md
    learn-show.md
    learn-search.md
    learn-curate.md
  agents/
    codebase-auditor.md

Source Structure (Python Package)

src/
  solokit/
    work_items/
      get_next_recommendations.py  # Dependency-aware next item selection
      get_dependencies.py          # Dependency resolution
    cli/                           # sk subcommands
    knowledge/                     # Learning capture + search
    quality/                       # Quality gate implementations

Quality Tiers

Tier Coverage Additional
Essential 60-80% Basic CI
Standard 80% + security scan Production apps
Comprehensive 90% + E2E + mutation Mission-critical
Production-Ready + monitoring + observability Enterprise-grade

Required Runtime

  • Python 3.11+

Target AI Tools

Claude Code (primary) — slash command UI. Also usable with any AI that reads files (sk start outputs a markdown briefing file that any AI can consume).

03

Components

SDD / Solokit — Components

CLI Subcommands (sk binary)

Command Purpose
sk init Initialize new project with stack + quality tier selection
sk adopt Adopt existing codebase into Solokit workflow
sk start [work_item_id] Start session with full AI briefing
sk end Complete session with quality gates and learning capture
sk work-new Create new work item

Claude Code Slash Commands (17)

Command Purpose
/start [id] Start session — presents work item options, runs sk start
/end End session with quality gates, CHANGELOG update, learnings
/work-new Create work item via interactive AskUserQuestion UI
/work-list List all work items with status
/work-update Update work item status/spec
/work-show [id] Show work item details
/work-delete [id] Delete work item
/work-next Get next recommended work item
/work-graph Show dependency graph
/status Show current project status
/validate Run quality gates manually
/init Initialize project (GUI)
/adopt Adopt existing project
/learn Capture a learning manually
/learn-show [id] Show learning detail
/learn-search [query] Search knowledge base
/learn-curate Review and curate learnings

Agents (1)

  • codebase-auditor.md — Reviews codebase structure, identifies quality issues

Quality Gates (at sk end)

  1. CHANGELOG.md update check
  2. Uncommitted changes: stage + commit with conventional format
  3. Learning extraction: 2-5 key learnings per session
  4. Work item completion survey (AskUserQuestion)
  5. Coverage threshold enforcement (tier-dependent)

Learning Categories (6)

Per the README: best_practices, patterns, architecture, gotchas, performance, security

Learning scoring uses:

  • Keyword matching from work item title and spec
  • Work item type relevance
  • Tag overlap
  • Category bonuses (best_practices, patterns, architecture score higher)
  • Recency weighting
  • Returns top 10 most relevant (scoring-weighted)

Session Briefing Contents

Generated by sk start {work_item_id}:

  • Complete project context (tech stack, directory tree, docs)
  • Previous work context: all commits from prior sessions, file stats, quality gate results
  • Full work item spec from .session/specs/{id}.md
  • Work item tracking: title, type, priority, dependencies
  • Spec validation warnings if spec is incomplete
  • Top 10 relevant learnings (multi-factor scored)
  • Milestone context and progress if applicable
05

Prompts

SDD / Solokit — Prompts

Excerpt 1: /start command (.claude/commands/start.md)

Technique: AskUserQuestion interaction pattern + context injection via CLI output. Combines programmatic context assembly with interactive selection.

## Step 2: Get Recommendations and Ask User

Get the top 4 recommended work items:

```bash
python -m solokit.work_items.get_next_recommendations --limit 4

This will output ready-to-start work items in format:

work_item_id | type | title | priority

Parse the output and present options using AskUserQuestion:

Question: Which work item do you want to start?

  • Question: "Select a work item to start working on:"
  • Multi-select: false
  • Options (up to 4): Label: "{work_item_id}: {title}", Description: "Type: {type} | Priority: {priority}"

## Step 3: Start Session

```bash
sk start {work_item_id}

The briefing includes:

  • Previous work context (for in-progress items) - commits made, files changed, quality gates from prior sessions
  • Full work item specification from .session/specs/{work_item_id}.md (source of truth)
  • Top 10 relevant learnings scored by keyword matching, type relevance, recency, and category

## Excerpt 2: /end command (`.claude/commands/end.md`)

**Technique**: Pre-flight checklist with git integration + learning extraction. Conventional commit format enforced inline.

```markdown
## Step 1.2: Check and Commit Uncommitted Changes

```bash
git commit -m "$(cat <<'EOF'
<type>: <short description>

<detailed description of changes>

LEARNING: <one key insight from this work>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

Where <type> is one of: feat, fix, refactor, docs, test, chore

Step 1.3: Generate Learnings

Extract 2-5 key learnings from the session and write them to a file:

cat > .session/temp_learnings.txt << 'EOF'
<learning 1 - technical insight or pattern discovered>
<learning 2 - gotcha or edge case encountered>
<learning 3 - best practice that worked well>
EOF

What makes a good learning:

  • Technical insights discovered during implementation
  • Gotchas or edge cases encountered
  • Best practices or patterns that worked well
  • Architecture decisions and their rationale
  • Performance or security considerations

## Excerpt 3: /work-new command (`.claude/commands/work-new.md`)

**Technique**: Multi-step AskUserQuestion flow — 5 sequential interactive questions drive structured work item creation.

```markdown
## Instructions

1. **First, gather basic information** using the `AskUserQuestion` tool with these 4 questions:

   **Question 1: Work Item Type**
   - Question: "What type of work item would you like to create?"
   - Options: feature | bug | refactor | security

   **Question 3: Priority**
   - Question: "What is the priority level?"
   - Options: critical | high | medium | low

   **Question 4: Urgent Status**
   - Question: "Does this work item require immediate attention? (Only ONE item can be urgent at a time)"

2. **Then, ask about dependencies** in a separate follow-up question:

   **Question 5: Dependencies**
   - Multi-select: true
   - Use: `python -m solokit.work_items.get_dependencies --title "<title>" --max 3`
09

Uniqueness

SDD / Solokit — Uniqueness

Differs from Seeds

Closest to agent-os (structured markdown workflow, bash-adjacent CLI) and openspec (commands + skills per feature), but Solokit distinguishes itself by: (1) shipping a real Python CLI (pip install solokit, sk binary) that manages persistent work item state — not just markdown files the agent reads passively; (2) multi-session commit history injection into AI briefings — the agent sees all git commits from prior sessions for the same work item, eliminating context loss without requiring explicit memory tools; (3) tiered quality enforcement (4 tiers with explicit coverage thresholds and tool requirements), which no seed provides as a first-class configuration choice; (4) dependency-aware work item scheduling via get_next_recommendations.py that excludes blocked items and scores by type/priority/urgency.

Positioning

  • Target user: Solo developers who want production-grade structure without enterprise ceremony overhead
  • Key differentiator: Git history as the memory system — no external DB, no MCP server required; the session briefing reconstructs state from git commits
  • Strong suit: The 5-question interactive /work-new workflow and tiered quality gates make it the most user-experience-focused command framework in the batch

Observable Failure Modes

  1. Single-agent only: No parallelism. Large projects require sequential work items, which can be slow.
  2. Python 3.11+ required: Stricter than most tools in the corpus; may cause setup friction.
  3. Quality gates post-session: TDD enforcement is at session end, not pre-implementation — the agent can write untested code during the session and only hit the gate at the end.
  4. Claude Code coupling: The interactive /work-new flow relies on AskUserQuestion which is Claude Code-specific; portability to other AI tools requires rewriting the command UX.
  5. Knowledge base opacity: Exact storage format and location of learnings is not documented in the public README; users cannot manually inspect or migrate it.
04

Workflow

SDD / Solokit — Workflow

Primary Loop

sk init / sk adopt
    ↓
/work-new (create work item + spec)
    ↓
/start [id]  →  AI receives full briefing
    ↓
Work with Claude (implement, test, iterate)
    ↓
/end  →  CHANGELOG check → uncommitted changes → learnings → quality gates
    ↓
(repeat per work item)

Phase to Artifact Map

Phase Artifact
Project initialization Stack scaffold, ARCHITECTURE.md, quality tier config, CI/CD
Work item creation .session/specs/{id}.md (source of truth)
Session start AI briefing (markdown injected into context)
Implementation Source code, tests, commits
Session end CHANGELOG update, committed changes, .session/temp_learnings.txt, quality gate results

Approval Gates

  1. Work item start gate: If no work item ID, AI presents top 4 recommendations via AskUserQuestion — user must select before briefing runs
  2. CHANGELOG gate: Session end checks CHANGELOG update; if missing, AI generates and stages it
  3. Uncommitted changes gate: Session end detects and commits any uncommitted work before proceeding
  4. Quality gates (tier-dependent): Coverage threshold, linting, formatting, security scan
  5. Learning extraction gate: AI extracts 2-5 learnings and writes to temp_learnings.txt; user confirms

Dependency Management

python -m solokit.work_items.get_dependencies --title "<title>" --max 3

Returns top 3 dependency candidates (excludes completed items). Work items can declare depends_on: [id1, id2]; /work-next returns only work items with all dependencies completed.

Spec Lifecycle

  1. Work item created → sk work-new generates .session/specs/{id}.md
  2. Spec edited manually or via AI
  3. sk start reads spec + injects into briefing
  4. Post-session: spec can be updated to reflect implementation decisions
  5. Spec validation runs at sk start — warns if sections are incomplete

Multi-Session Continuity

For in-progress work items, sk start generates a "Previous Work" section:

  • All commits made in previous sessions (full messages + file stats)
  • Quality gate results from each session
  • Session dates and durations

This eliminates the need to re-explain context at the start of each new session.

06

Memory Context

SDD / Solokit — Memory & Context

State Storage

  • Type: File-based (Python CLI manages state)
  • Persistence scope: Project
  • Location: .session/ directory + Python CLI backend

State Files

Path Purpose
.session/specs/{id}.md Work item specification (source of truth)
.session/temp_learnings.txt Staging area for session learnings
ARCHITECTURE.md AI-generated project architecture
CHANGELOG.md Session-by-session change history

Learning Persistence

Learnings are captured at session end via sk end and stored in the Python CLI's knowledge base (exact storage path not exposed in README — likely SQLite or JSON in .session/). Multi-factor scoring enables relevance-ranked recall at session start.

Learning lifecycle:

  1. Manual capture via /learn or automated extraction at /end
  2. Classification into 6 categories: best_practices, patterns, architecture, gotchas, performance, security
  3. Deduplication via similarity detection
  4. Recall: top 10 by weighted score at session start

Context Injection

sk start {id} generates a comprehensive briefing that is injected into the AI's context. For in-progress work items, this includes:

  • All git commits from previous sessions (full messages + file stats)
  • Quality gate results from each previous session
  • Session dates and durations
  • Full spec from .session/specs/{id}.md

This approach converts stateless AI (context-reset each session) into effectively stateful development by reconstructing state from git history.

Compaction Handling

No explicit compaction handling. Context is reconstructed from persistent files at each session start.

Cross-Session Handoff

Yes — the central innovation. sk start rebuilds complete context from persistent state (git history, spec, learnings) rather than requiring the user to re-explain manually.

Keyword-based with relevance scoring (no vector search mentioned in README).

07

Orchestration

SDD / Solokit — Orchestration

Multi-Agent: Limited

Ships 1 agent (codebase-auditor). The /start command references AskUserQuestion tool for interactive work item selection — this is Claude Code's interactive mode, not multi-agent spawning.

Orchestration Pattern: Sequential

Single-agent workflow. No parallel execution, no hierarchical coordination. One work item at a time (the --urgent flag enforces only one urgent item).

Isolation Mechanism: None

Works in-place (edits directly in working tree). No git worktree isolation.

Execution Mode: Interactive-loop

Session-based: sk start initiates, sk end completes. Not a background daemon.

Multi-Model: No

No model routing. Claude Code is the assumed AI; no configuration for multiple models.

Consensus Mechanism: None

Prompt Chaining: Yes

Work item spec → session briefing → implementation → commit message with LEARNING field → knowledge base for future sessions. Each output feeds the next session's input.

Auto-Validators

At sk end:

  • Uncommitted changes check (git status)
  • CHANGELOG update check
  • Quality gates (tier-dependent): coverage threshold, linting, formatting, security scan
  • Learning extraction (2-5 per session)

Git Automation

  • sk end stages uncommitted changes and creates a commit with conventional format and LEARNING: field
  • CHANGELOG.md updated at session end
  • No auto PR creation
  • No branch management automation

TDD Enforcement

Yes — quality tiers enforce coverage thresholds:

  • Essential: 60-80%
  • Standard: 80%
  • Comprehensive: 90% + E2E + mutation
  • Production-Ready: same + monitoring

Enforcement mechanism: quality gate at sk end (post-session, not pre-implementation).

Cross-Tool Portability: Medium

Commands are Claude Code-specific (.claude/commands/). The sk CLI binary can be used standalone to generate briefing context for any AI that reads files.

08

Ui Cli Surface

SDD / Solokit — UI / CLI Surface

CLI Binary

  • Name: sk
  • Package: solokit (PyPI)
  • Is thin wrapper: No — manages work items, session state, knowledge base, quality gates
  • Subcommands: init, adopt, start, end, work-new (main session subcommands; others via slash commands)

Local UI

None. No web dashboard, no TUI, no desktop app.

IDE Integration

Claude Code: Full support via .claude/commands/ (17 slash commands). The /start command uses Claude Code's AskUserQuestion interactive feature for work item selection. This makes the workflow feel interactive inside the Claude Code chat interface.

Other IDEs: Not explicitly supported. sk CLI binary is IDE-agnostic; the briefing output can be pasted into any AI chat.

Slash Command UX

Notable: the /work-new command drives a full 5-question interactive session via AskUserQuestion:

  1. Work item type (feature/bug/refactor/security)
  2. Title (with AI-suggested examples per type)
  3. Priority (critical/high/medium/low)
  4. Urgent status (only 1 item can be urgent)
  5. Dependencies (multi-select from relevant existing items)

This is more interactive than any seed framework's command UI.

Observability

  • Git history serves as primary audit trail
  • CHANGELOG.md updated at session end
  • .session/temp_learnings.txt shows what was captured
  • Quality gate output displayed in terminal at sk end

Stack Templates

Four pre-configured scaffolding templates (sk init):

  • SaaS T3 Stack: Next.js + tRPC + Prisma
  • ML/AI FastAPI: FastAPI + Python ML libraries
  • Dashboard Refine: Refine + shadcn/ui
  • Full-Stack Next.js: Next.js + Prisma

Each includes comprehensive ARCHITECTURE.md with patterns, CI/CD workflows, Docker support, environment templates.

Related frameworks

same archetype · same primary tool · same memory type

BMAD-METHOD ★ 48k
A4 Markdown scaffold

Provides a full agile delivery lifecycle with named expert-persona AI collaborators that elicit the human's best thinking rather…

Agent OS ★ 4.6k
A4 Markdown scaffold

Extracts implicit codebase conventions into token-efficient markdown standards files and injects them selectively into AI agent…

Claude Conductor ★ 367
A4 Markdown scaffold

Gives Claude Code a persistent, cross-linked, auto-analyzed documentation system so it retains codebase context across sessions.

Spec-Driver (Greenfield Spec-Driven Development) ★ 25
A4 Markdown scaffold

Prevents spec rot in AI-assisted development by making implementation changes flow back into evergreen, authoritative specs via…

Anthropic Knowledge Work Plugins ★ 16k
A4 Markdown scaffold

Role-specialized plugin bundles with live MCP connectors that turn Claude into a domain expert for enterprise knowledge workers.

Codex Integration for Claude Code (skill-codex) ★ 1.3k
A4 Markdown scaffold

Single Claude Code skill that handles Codex CLI invocation correctly (stdin blocking, thinking token suppression, session resume)…