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 (login screen + access code) | | npx create-spect doctor | Diagnose — config, envelopes, sessions, delivery, backup, model routing | | npx create-spect refresh-registry | Scan skills + agents → .spect/skill-registry.md | | npx create-spect migrate-docs | Add SPECT envelopes to legacy docs (idempotent) | | 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) |

What's new in v21

v21.2.0 — Fase 7: adoption & rigor

• Interactive language — npx create-spect asks for the SPECT output language (Español / English) and seeds it into .spectrc; /setup-project and /adopt-project use it for output_language.
• Lite install profile — pick Full (all 26 skills) or Lite (the core Plan→Validate→Implement→Review loop + sync) when installing.
• /metrics dashboard route — aggregated cycles, scores, reports and risks from the envelopes.
• Gate-coherence doctor check + testable secret-scan helper (enforcement moves from prose to verifiable CLI checks).
• Domain template catalog — add template django|rails|fastapi|flutter scaffolds a stack-aware expert; unknown stacks fall back to the generic template.

v21.1.0 — Login screen for serve --tunnel

The public dashboard is no longer protected by a token in the URL. serve --tunnel prints a high-entropy access code (8–10 chars); visitors enter it on a login page that submits via POST (the code never appears in a URL) and receive an HttpOnly; SameSite=Strict session cookie. Includes a per-code lockout, a dedicated login rate-limit, a body-size cap (413), and 401 JSON for programmatic /api calls.

v21.0.0 — Security hardening

A full security audit, resolved end-to-end:

• serve --tunnel authenticated (code/login, no localhost bypass) + rate limit + security headers (CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy).
• DOMPurify replaces the regex HTML sanitizer (dashboard XSS); escapeHtml escapes quotes; SRI on versioned CDN assets.
• Pinned MCP versions in the default .mcp.json (supply-chain) + a cleaned MCP catalog (removed non-existent packages, "verify before install" guidance).
• Path-traversal guard on add template; relative paths in the registry (no leaked username); minimal JSON-schema guards.
• Wiki prompt-injection threat model documented (see Security model below); human checkpoint before git push in /auto.

⚠️ Breaking (v21.0.0): serve --tunnel now requires the printed code; /auto adds a push checkpoint.

What's new in v20.1

v20.x is the consolidated release of a six-phase roadmap that takes SPECT from a markdown-only starter kit to a parseable, calibrable, token-aware ecosystem with operational memory and delivery discipline — while keeping it portable and multi-tool.

Parseable & calibrable foundation

• .spect/config.yaml — project calibration (stack, runner, TDD flag, layers, thresholds, gates). Generated by /setup-project / /adopt-project, loaded by the orchestrator at session start. Absent → safe defaults.
• Result Envelope — additive YAML frontmatter on every output (plan / validation / report / review). Status, score, artifacts, risks, evidence. Markdown body stays human-readable. Legacy docs still parse; use migrate-docs to retro-fit.
• Skill Registry — auto-generated .spect/skill-registry.md with fingerprint cache, indexing skills and agents (path, model, compact rules).

Token optimization

• Compact Rules — curated bullets per skill/agent. Orchestrator skills inject them into subagent prompts instead of re-sending full SKILL.md / agent.md.
• Model Routing — model: field per agent honored by Claude Code automatically. Doctor audits that every agent declares it.
• Delegation Contract — four canonical elements per subagent prompt: task, artifacts (paths), Project Standards (auto-resolved), success criteria.

Production-readiness gates

• safety.hard_gates: true — /implement refuses when validation score < 7.
• testing.strict_tdd: true (opt-in) — /implement enforces red → green → triangulate per task.
• Evidence enforcement — parseEnvelope requires evidence.commands_run on every completed report.

Operational memory

• Sessions auto-snapshot (docs/wiki/sessions/) — automatic context capture at the end of /review-code (approved), /debug, /research. Markdown commitables, no external MCP.
• /recall — list and summarize last N sessions.
• Orchestrator silently loads the most recent snapshot at session start.

Delivery discipline

• Workload threshold — reviewer measures git diff --numstat against baseRef. Raises 🟡 finding when totalLoc > review_workload_threshold_loc.
• Exception heuristics — vendor/migration (≥80%), greenfield/scaffold, intentional bulk refactor.
• Four strategies — single-pr / stacked / feature-chain / exception (runtime decision).
• /split-pr — read-only skill that analyzes a plan + diff and proposes N independent slices.

Quality of life

• Backup before sync — /sync-docs snapshots CLAUDE.md/AGENTS.md/TDD.md to .spect/backups/{timestamp}/ before mutation. Retention 20.
• Delegation Matrix — classifyChange() helper categorizes changes as trivial | small | normal | large to pick the right level of ceremony.
• Auto-refresh registry — /setup-project runs refresh-registry at the end automatically.

Envelope example (plan):

---
spect_envelope: v1
kind: plan
status: draft
name: phase-1
artifacts: [docs/plans/plan-phase-1.md]
next_recommended: /validate-plan phase-1
risks:
  - { level: medium, desc: New ESM-only dep }
created_at: 2026-05-17T10:00:00Z
updated_at: 2026-05-17T10:00:00Z
---

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
7 universal rules      methodology, git-workflow, wiki, orchestrator, context-optimization, mcp, envelope
24 workflow skills     SPECT core + wiki + research + quality + ops + delivery + memory + sync
7 agent templates      extensible library for stack-specific agents

.spect/config.yaml     Project calibration (committed)
.mcp.json              MCP servers (context7, sequential-thinking — version-pinned + stack-detected)
.env / .env.example    API keys (private / template)

docs/plans/            Generated plans + reports with envelopes
docs/validations/      Generated validations with score + envelope
docs/reviews/          Generated reviews with verdict + envelope
docs/wiki/             Obsidian vault (project brain)
docs/wiki/sessions/    Session snapshots (opt-in, auto-pruned at 20)
docs/tdd/              TDD sub-documents (overflow from TDD.md root)

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 (envelope, ≤ 15 tasks)
/validate-plan ── validator + domain → score 1-10 (hard gate: ≥ 7 to implement)
/implement ───── domain agents follow the plan → report (evidence required)
/review-code ─── reviewer + domain → verdict + workload check → commit
                                      ↓ (if approved + sessions on)
                                      → session snapshot → /wiki-update → /sync-docs (with backup)

Delegation Matrix — pick the right level of ceremony

| Class | Criteria | Recommended flow | |-------|----------|------------------| | trivial | ≤ 2 LOC, 1 file, no new logic | Commit directly. No SPECT. | | small | ≤ 50 LOC, ≤ 3 files, 1 domain | Skip /validate-plan → /implement + /review-code → commit | | normal | Everything else under 400 LOC / 10 files / 2 domains | Full SPECT cycle | | large | > 400 LOC or > 10 files or > 2 domains | Full SPECT + /split-pr |

Security, infra, public-interface, or payment-touching changes are always normal or larger regardless of LOC.

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
/recall [N]     list + summarize last N sessions
/split-pr       analyze plan + diff → propose N slices (read-only)
/sync-docs      drift detection + auto backup → 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 with 4 badges (config, delivery, backup, sessions) + metrics + last 5 sessions | | /metrics | Aggregated SPECT metrics — cycles, completed/failed reports, avg validation/review score, risks by level | | /wiki/{slug} | Wiki pages with [[wikilinks]], tags, status badges | | /search?q=term | Full-text search across all documentation | | /export | Standalone HTML export (no server needed) | | /tdd | TDD viewer (root + sub-docs) | | /plans/{name} | SPECT plans (envelope rendered as header) | | /reports/{name} | Implementation reports (envelope + evidence table) | | /validations/{name} | Validations with score badge | | /reviews/{name} | Reviews with verdict + workload finding |

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
• Parseable foundation — envelope + config.yaml + skill registry
• Token-aware — compact rules + delegation contract + model routing
• Hard gates with conscious override — hard_gates: true by default
• Operational memory — session snapshots in Markdown, no external MCP
• Delivery discipline — workload threshold + four strategies + /split-pr
• Backup-safe sync — /sync-docs snapshots core docs before mutation
• 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 — 12+ health checks across config, envelopes, sessions, delivery, backup, model routing
• 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, MCP config, and .spect/config.yaml.

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

Security model

SPECT treats certain repo files as authoritative-but-auditable data, not as trusted commands. Two surfaces deserve explicit care:

• Wiki & registry as instructions. The agent reads docs/wiki/, .spect/skill-registry.md and ## Compact Rules as project knowledge. A malicious commit to those files is a persistent prompt injection — it triggers every time someone opens the agent. PRs touching docs/wiki/ or .spect/skill-registry.md require mandatory human review — they are not "just docs". The agent is instructed to treat embedded shell imperatives as information and ask for confirmation before acting on them.

• Pinned MCP versions. The default .mcp.json pins exact versions (@upstash/[email protected]) on purpose. An unpinned npx -y <pkg> would auto-pull whatever the maintainer last published — a supply-chain risk. To bump, re-run npx create-spect update. The MCP catalog in .claude/rules/mcp.md ships a "verify before install" warning; always npm view <pkg> and pin a version.

• serve --tunnel is authenticated by a login screen. Exposing the dashboard publicly requires interactive confirmation and then prints a high-entropy access code (8–10 chars). Visitors hit a login page and submit the code via POST (it never travels in the URL); on success they get an HttpOnly; SameSite=Strict session cookie. There is no localhost bypass (under localtunnel all traffic looks like 127.0.0.1). Failed attempts trigger a temporary lockout, and the server adds rate limiting + security headers. Programmatic /api/... requests return 401 instead of the HTML form.

  Migration (v21.1.0): the earlier ?token= URL scheme was replaced by the login screen. Bookmarks/links with ?token= no longer authenticate — enter the access code (printed in the console on startup) on the login page instead.

Backward Compatibility

v20.x is fully backward-compatible:

• Projects without .spect/config.yaml get sensible defaults — the flow doesn't break.
• Documents without envelopes still parse (parseEnvelope() returns null).
• fingerprint(entries) without agents still works (parameter is optional with default []).
• Backup toggle default true doesn't break existing projects (.spect/backups/ is gitignored).
• Delegation Matrix is documentation + pure helper — no auto-invocation.

v21.0.0 breaking changes (CLI behavior only — no data/format migration needed):

• serve --tunnel now requires the access code shown on startup (was open / ?token=).
• /auto adds a human checkpoint before git push.

Use npx create-spect migrate-docs to retro-fit envelopes to legacy docs when convenient.

License

MIT © Facundo Guardia