create-spect

SPECT methodology starter kit for AI coding agents.

Plan → Validate → Implement → Review → Commit

Works with Claude Code, OpenCode, Gemini CLI, Codex CLI, and GitHub Copilot CLI. A portable, language-agnostic ecosystem with expert agents, intelligent rules, workflow skills, an Obsidian wiki, MCP servers, and a built-in dashboard — for any project, in any stack, with any AI coding tool.

Quick Start

cd my-project
npx create-spect              # Select your AI tool, install ecosystem

$ npx create-spect

  ███████╗██████╗ ███████╗ ██████╗████████╗
  ██╔════╝██╔══██╗██╔════╝██╔════╝╚══██╔══╝
  ███████╗██████╔╝█████╗  ██║        ██║
  ╚════██║██╔═══╝ ██╔══╝  ██║        ██║
  ███████║██║     ███████╗╚██████╗   ██║
  ╚══════╝╚═╝     ╚══════╝ ╚═════╝   ╚═╝

  Plan  →  Validate  →  Implement  →  Review  →  Commit

  AI methodology starter kit
  language-agnostic · agents · skills · obsidian wiki

  Which AI coding tool are you using?

  ❯ Claude Code
    OpenCode
    Gemini CLI
    Codex CLI
    GitHub Copilot CLI

Commands

| Command | Description | |---------|-------------| | npx create-spect | Install ecosystem (interactive tool selection) | | npx create-spect --tool claude | Install for specific tool (skip selection) | | npx create-spect --dry-run | Preview what would be installed without changes | | npx create-spect update | Update base files (preserves project files) | | npx create-spect status | Show installed components + version check | | npx create-spect serve | Dashboard local — wiki + project status (port 4321) | | npx create-spect serve --tunnel | Dashboard + public URL for stakeholders | | npx create-spect doctor | Diagnose issues — check missing/broken components | | npx create-spect add template <name> | Add agent template (e.g. django, spring-boot) | | npx create-spect eject | Remove SPECT (preserves docs and project files) |

Supported Tools

| Tool | Config Dir | Primary File | Agents | Skills | |------|-----------|-------------|--------|--------| | Claude Code | .claude/ | CLAUDE.md | .claude/agents/ | .claude/skills/ | | OpenCode | .opencode/ | AGENTS.md | .opencode/agents/ | .opencode/skills/ | | Gemini CLI | .gemini/ | GEMINI.md | .agents/agents/ | .agents/skills/ | | Codex CLI | .codex/ | AGENTS.md | .agents/agents/ | .agents/skills/ | | Copilot CLI | .agents/ | AGENTS.md | .agents/agents/ | .agents/skills/ |

Core content is identical across all tools. Only directory structure and file references adapt.

What Gets Installed

6 universal agents      planner, validator, reviewer, wiki-maintainer, researcher, docs-sync
6 universal rules       methodology, git-workflow, wiki, orchestrator, context-optimization, mcp
22 workflow skills      SPECT core + wiki + research + quality + ops + sync
7 agent templates       extensible library for stack-specific agents

.mcp.json               MCP servers (context7, sequential-thinking + stack-detected)
.env / .env.example     API keys (private / template)

docs/plans/             Generated plans (Spanish)
docs/validations/       Generated validations (Spanish)
docs/reviews/           Generated reviews (Spanish)
docs/wiki/              Obsidian vault (project brain)
docs/tdd/               TDD sub-documents (overflow)

MCP Servers

Default (no API key, installed automatically):

• context7 — Up-to-date documentation for any library
• sequential-thinking — Structured problem-solving

Stack-detected (suggested by /setup-project and /adopt-project): github, supabase, postgres, playwright, sentry, slack, notion, stripe, firebase, figma.

SPECT Flow

/create-plan ─── planner + domain agents → plan
/validate-plan ── validator + domain → score 1-10
/implement ───── domain agents follow the plan
/review-code ─── reviewer + domain → verdict → commit → wiki-update → sync-docs

Beyond SPECT

/research       wiki + code + web → deep analysis → wiki-save
/debug          wiki context + code trace → root cause → fix plan
/refactor       conventions analysis → tech debt → refactor plan
/test-coverage  modules vs tests → gap analysis → test plan
/migrate        breaking changes + impact → phased migration plan
/retrospective  SPECT history → patterns + insights
/audit-deps     vulnerabilities + outdated + unused
/changelog      git + SPECT → CHANGELOG.md
/report         progress summary for stakeholders
/sync-docs      keeps CLAUDE.md, AGENTS.md, TDD.md in sync

Dashboard

npx create-spect serve              # http://localhost:4321
npx create-spect serve --tunnel     # + public URL for stakeholders

| Route | Content | |-------|---------| | / | Project status: metrics, validation scores, review verdicts | | /wiki/{slug} | Wiki pages with [[wikilinks]], tags, status badges | | /search?q=term | Full-text search across all documentation | | /graph | Force-directed graph view of wiki connections | | /export | Standalone HTML export (no server needed) | | /tdd | TDD viewer (root + sub-docs) | | /plans/{name} | SPECT plans |

Zero files generated in your project. Separate port. Live reload.

Key Features

• Multi-tool — one ecosystem, five AI coding tools
• Language-agnostic — TypeScript, Java, Python, Go, Rust, or any stack
• MCP built-in — context7 + sequential-thinking by default, stack-detected suggestions
• Expert agents — researches aitmpl.com, GitHub, official docs
• Deep analysis — /adopt-project reads every file
• Professional docs — TDD.md (<35k chars, auto-split), CLAUDE.md, AGENTS.md
• Obsidian wiki — Karpathy LLM Wiki: ingest, query, lint, save
• Dashboard — serve for team + --tunnel for stakeholders
• Document sync — /sync-docs keeps core docs current
• Research-first — /research uses wiki → code → context7 → web
• Orchestrator — describes what you need, AI suggests the right skill
• Git CLI — git + gh commands, no MCP for version control
• Doctor — doctor diagnoses missing/broken components
• Dry-run — preview changes before installing
• Eject — clean removal that preserves your docs

Protection Policy

npx create-spect never overwrites user files (CLAUDE.md, AGENTS.md, PRD.md, TDD.md, .mcp.json).

npx create-spect update only refreshes base (agents, rules, skills, templates). Preserves domain agents, project rules, docs, wiki, and MCP config.

npx create-spect eject removes only base SPECT files. Preserves all documentation, wiki, domain agents, and project config.

License

MIT © Facundo Guardia