specflow — Universal AI Workflow Bootstrap

Documentation

Everything you need to use specflow in your project.

Installation

Run without installing (recommended for first use):

bash

npx @kousthubha/specflow init

Or install globally:

bash

npm install -g @kousthubha/specflow

Requires Node 18+. No API keys needed for core features — only analyze uses Anthropic.

specflow init

Full project bootstrap. Run once from your project root.

bash

specflow init [--agent <id>] [--obsidian <path>] [--dry-run]

What it does:

→ Reads package.json / pyproject.toml / go.mod / Cargo.toml → detects stack
→ Prompts multi-select: which agents do you use? (pre-selects detected one)
→ Writes context directly into each agent's own file (CLAUDE.md, agents.md, etc.)
→ Pulls skills from skills.sh for every detected dependency
→ Optionally connects Obsidian vault
→ Initializes SPECS/ structure and SEED.md via OpenSpec
→ Creates /specflow-* slash commands for Claude Code and OpenCode
→ Saves .specflow.json config

Flags

--agent <id>Force a specific agent. Values: claude-code, cursor, copilot, windsurf, opencode, continue, aider

--obsidian <path>Absolute path to your Obsidian vault root (the folder containing .obsidian/)

--dry-runPreview everything that would be written without touching any files

specflow spec

OpenSpec lifecycle — propose, validate, archive, list, regenerate SEED.

specflow spec "add feature name"

Propose a new spec. Creates SPECS/active/<slug>/ with proposal.md, design.md, tasks.md.

specflow spec --validate <slug>

Validate a spec against SEED.md constraints and generation-spec rules. Catches missing sections, SEED conflicts.

specflow spec --archive <slug>

Archive a completed spec. Extracts patterns from design.md, merges into SEED.md. Moves spec to SPECS/archive/. Writes spec back to Obsidian vault.

specflow spec --list

List all active specs with task completion progress.

specflow spec --seed

Regenerate SEED.md from all archived spec patterns.

Spec file structure

text

SPECS/
├── SEED.md                          ← architectural DNA (commit)
├── active/
│   └── add-razorpay-payments/
│       ├── proposal.md              ← problem, solution, scope
│       ├── design.md                ← data model, API, constraints
│       └── tasks.md                 ← actionable checklist
└── archive/
    └── 2026-03-11-add-payments/     ← completed specs

specflow skill

Skills.sh lifecycle — search, create, evolve, update installed skills.

specflow skill --search "react auth"

Search the skills.sh community registry for matching skills.

specflow skill --list

List all installed skills with source (registry/builtin/placeholder) and version.

specflow skill --create <owner/name>

Create a skill from your project patterns + tagged Obsidian notes. Uses AI if ANTHROPIC_API_KEY is set.

specflow skill --evolve <owner/name>

Merge new patterns into an existing skill file.

specflow skill --update

Update all installed skills to latest versions via skills.sh CLI.

specflow add-skill <owner/name>

Install a specific skill directly. Falls back: registry → builtin → placeholder.

Install priority

For each skill: skills.sh registry → bundled builtin → placeholder file. Manifest tracked at .skills/.manifest.json.

specflow sync

Bidirectional Obsidian sync. Pulls notes in, routes them by tag, pushes specs and SEED back to vault.

bash

specflow sync                          # bidirectional (default)
specflow sync --one-way               # pull from vault only
specflow sync --discover              # auto-find Obsidian vaults on this machine
specflow sync --pin "Projects/App"    # pin a vault folder to always pull

Tag routing

#spec, #decision, #architectureOpenSpec — feeds spec proposals and SEED.md evolution

#pattern, #skill, #best-practice, #conventionSkills.sh — feeds skill creation and evolution

#specflow, #hot, #bug, #workflowMemory — MEMORY/INDEX.md (agent reads this)

Write-back (bidirectional)

After sync, specflow writes back to <vault>/specflow/:

→ Archived specs → specflow/specs/<slug>.md (tagged #specflow #archived)
→ SEED.md snapshot → specflow/SEED.md (tagged #specflow #seed)
→ Evolved skills → specflow/skills/<id>.md (tagged #specflow #skill)

specflow analyze

AI-analyze your actual code and generate project-specific skill files. Requires Anthropic API key.

bash

specflow analyze                        # analyze all detected skills
specflow analyze --key sk-ant-...      # pass API key directly
specflow analyze --force               # regenerate even if files exist
specflow analyze --only stripe/node    # target specific skills

Uses claude-haiku-4-5 — fast and cheap. Set ANTHROPIC_API_KEY in env to avoid passing --key every time.

Slash commands

For Claude Code and OpenCode, specflow init creates native slash commands. Type /specflow- in the AI chat to see them.

These are AI-native — they instruct the AI agent itself to analyze your code and generate context, using the three-tool trinity (OpenSpec + skills.sh + Obsidian).

/specflow-initAI scans codebase → writes to agent's context file (CLAUDE.md, etc.) + SPECS/SEED.md + .skills/

/specflow-specAI reads codebase + SEED.md → generates structured specs via OpenSpec lifecycle

/specflow-skillAI analyzes code patterns → creates/evolves project-specific skills via skills.sh

/specflow-syncAI reads Obsidian notes → routes by tag (#spec → OpenSpec, #pattern → skills.sh, #bug → memory)

/specflow-analyzeAI deep-dives codebase → generates detailed skill files with project-specific patterns

Supported agents: Claude Code (.claude/commands/) and OpenCode (.opencode/commands/). Other agents use CLI commands directly.

Config file (.specflow.json)

Auto-created by specflow init. Persists state between commands.

json

{
  "agent": "claude-code",
  "agents": ["claude-code", "cursor"],
  "agentRoot": "/absolute/path/to/monorepo/root",
  "stack": ["nextjs", "prisma", "clerk", "stripe"],
  "skills": ["vercel/nextjs", "prisma/best-practices", "stripe/stripe-node"],
  "obsidianPath": "/Users/you/obsidian/MyProject",
  "pinnedFolders": ["Projects/MyApp", "Architecture"],
  "lastSync": "2026-03-11T09:00:00.000Z",
  "activeSpec": null
}

.gitignore

bash

# specflow — do not commit these
MEMORY/INDEX.md        # personal vault content
.specflow.json         # contains local paths (vault, agentRoot)
.skills/               # downloaded skills — regenerated on demand

# commit these
# CLAUDE.md (or agents.md, .cursor/rules/, etc.)
# SPECS/
# .specflow/generation-spec.json

Plugin API

Use specflow as a library in your own CLI tool or editor extension.

typescript

import { createSpecflowPlugin } from "@kousthubha/specflow/plugin";

const sf = await createSpecflowPlugin("/path/to/project");

// Optional: register your CLI's native AI for spec-driven generation
await sf.registerCliAI(cliAIInstance);

// Bootstrap
const result = await sf.detectAndSetup({
  agents: ["claude-code", "cursor"],
  obsidianPath: "/path/to/vault",
  useCliAI: true,  // use registered AI to generate context files
});
// result.stack  → ["nextjs", "prisma"]
// result.files  → ["CLAUDE.md", "SPECS/SEED.md", ...]
// result.method → "ai-driven" | "static"

Detection only

typescript

const info = await sf.detect();
// { stack: ["nextjs","prisma"], currentAgent: "cursor", availableAgents: [...] }

OpenSpec lifecycle

typescript

await sf.proposeSpec("add payments");
await sf.validateSpec("add-payments");
await sf.archiveSpec("add-payments");
const specs = await sf.listSpecs();    // [{ slug, progress }]
await sf.regenerateSeed();

Skills lifecycle

typescript

const results = await sf.searchSkills("react auth");
await sf.discoverSkills();           // auto-discover for detected stack
await sf.createSkill("team/patterns");
await sf.evolveSkill("team/patterns");
await sf.updateSkills();
const installed = await sf.listSkills();

Obsidian

typescript

await sf.syncBidirectional("/path/to/vault");
const specNotes  = await sf.getSpecNotes("/vault");   // #spec, #decision
const skillNotes = await sf.getSkillNotes("/vault");  // #pattern, #skill

Obsidian setup

Auto-discover vaults

specflow reads Obsidian's own config JSON to find your vaults:

bash

specflow sync --discover
# Found vaults:
#   MyVault     /Users/sky/Documents/MyVault
#   WorkNotes   /Users/sky/obsidian/WorkNotes

Connect manually

bash

specflow init --obsidian "/absolute/path/to/vault"
# vault root = folder containing .obsidian/ directory

Vault path by OS

WindowsC:\Users\<you>\Documents\<VaultName>

macOS/Users/<you>/Documents/<VaultName>

Linux~/obsidian/<VaultName>

Tagging notes

Inline tag (anywhere in note body):

markdown

#specflow
#decision  your decision here

Front-matter tags:

yaml

---
tags: [specflow, decision, architecture]
---

generation-spec.json

The stable source of truth for all context generation. Lives at .specflow/generation-spec.json in your project — commit it.

It defines: file schemas (required sections, token limits), validation rules, AI generation prompts, integration settings for OpenSpec/skills/Obsidian. Follows semantic versioning — switching AI models or CLI tools doesn't break your specs because the spec is the source of truth, not the model.

bash

# Initialize generation-spec in your project
specflow init  # creates .specflow/generation-spec.json automatically