SpecWise CLI (command: specwise)

SpecWise helps solo founders and IC developers ship AI-assisted changes safely by forcing spec-first, minimal-diff work with a built-in seatbelt.

• Who this is for:

  • Solo founders and small teams using AI heavily in development.
  • Engineers who want AI help without giant refactors.
  • People who like git-style small diffs and want visibility into AI vs human work.

• Spec first: every goal becomes a tiny, structured plan.

• Minimal diffs: no giant refactors by default.

• Seatbelt and metrics: track AI vs human work.

• JSON APIs available for dashboards: status, snapshot, seatbelt, metrics, report.

Quickstart

Commands below match the 0.3.x CLI (tag v0.3.1). Check your version with specwise version; behaviour may shift slightly between minor releases. Install from npm for normal use; cloning this repo is only needed if you are contributing to SpecWise itself.

Requirements

• Node.js 18 or newer
• Git
• API key exported or in .env: GEMINI_API_KEY or OPENAI_API_KEY

Install (npm)

npm install -g specwise
npx specwise init    # run inside the project you want to manage with SpecWise
specwise help

• specwise init asks which LLM provider you use (Gemini/OpenAI/both/not sure) and warns if required API keys are missing.
• Requires a git repo; run git init first in new projects.

Install from source (contributors)

git clone https://github.com/TomekKaszynski/SpecWise.git specwise
cd specwise
npm install
npm run build
npm link    # makes the 'specwise' command available globally

Verify the install

After linking, create or switch to a project repo and run specwise init (see Workspace layout below).

specwise version
specwise doctor
specwise help

Quick health check

$ specwise doctor
SpecWise doctor report:

✓ Workspace: .specwise directory found (/path/to/your/project/.specwise)
✓ Config: Loaded .specwise/config.json (llmProvider=gemini, model=gemini-2.0-flash)
✗ Env: Missing environment variables: GEMINI_API_KEY. Required for spec-ai and fix-ai. Next: Add GEMINI_API_KEY or OPENAI_API_KEY to .env or export it.
Seatbelt: mode=warn threshold=1

Use specwise doctor --json if you want other tools to check readiness automatically.

• specwise doctor checks local readiness; specwise ci-check prints a CI safety summary (fail-open for now).

First spec with AI (run in your project, not the SpecWise repo)

echo "GEMINI_API_KEY=your_key_here" >> .env
specwise spec-ai "Add a /health endpoint that returns { status: 'ok' }"
specwise specs
specwise view-spec 1

Try SpecWise in 3 minutes

mkdir -p /tmp/specwise-demo-app
cd /tmp/specwise-demo-app
git init
echo 'console.log("hello SpecWise");' > index.js
specwise init                     # creates .specwise/config.json and workspace
echo "GEMINI_API_KEY=your_key_here" >> .env
specwise doctor                   # should show green checks when key + workspace are present
specwise spec "add a dark mode toggle"   # saves a spec file under .specwise/specs
specwise seatbelt                 # shows status/mode/threshold (should be ok)
specwise metrics --days 3         # quick AI vs human trend
specwise report                   # shareable safety snapshot

CI Integration

Copy-paste ready templates below. Add SpecWise to your CI pipeline to enforce AI safety policies.

GitHub Actions

Create .github/workflows/specwise.yml:

name: SpecWise CI Check
on:
  pull_request:
    branches: [main, develop]

jobs:
  ai-safety:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 30 # Needed for AI density metrics

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
  
      - name: Run SpecWise Check
        run: npx specwise@latest ci-check --strict
        env:
          SPECWISE_LICENSE_KEY: ${{ secrets.SPECWISE_LICENSE_KEY }}

Note: --strict mode requires Pro tier. Omit flag for free tier (fail-open mode).

GitLab CI

Add to .gitlab-ci.yml:

specwise_check:
  stage: test
  image: node:18
  before_script:
    - npm install -g specwise@latest
  script:
    - specwise ci-check --strict
  only:
    - merge_requests
  variables:
    GIT_DEPTH: 30 # Needed for metrics

CircleCI

Add to .circleci/config.yml:

version: 2.1
jobs:
  specwise:
    docker:
      - image: cimg/node:18.0
    steps:
      - checkout
      - run:
          name: Install SpecWise
          command: npm install -g specwise@latest
      - run:
          name: Run AI Safety Check
          command: specwise ci-check --strict

workflows:
  test:
    jobs:
      - specwise

Jenkins

pipeline {
  agent any
  stages {
    stage('SpecWise Check') {
      steps {
        sh 'npx specwise@latest ci-check --strict'
      }
    }
  }
}

What Gets Blocked?

In --strict mode (Pro tier), CI fails when:

• ✗ AI density exceeds configured threshold (default: 60%)
• ✗ Code changes without spec/plan updates (ghost specs)
• ✗ Large changes (5+ files) with no test updates

Exit code 1 blocks the merge. Clear reason printed:

❌ SpecWise CI Seatbelt: BLOCKED
Reason: AI 78% > 60% threshold, no test files changed
Override with --force or adjust thresholds

Workspace layout

SpecWise only writes inside .specwise in the current repo and never edits your app code or other config files.

• .specwise/config.json - CLI config, including seatbelt mode and threshold.
• .specwise/specs/*.json - saved specs (AI and human).
• .specwise/fixes/*.json - saved fix plans.
• .specwise/logs/YYYY-MM-DD.log - daily human-friendly log of specs, fixes, and commands.

SpecWise CI Seatbelt Pro

• Local CLI is free (MIT); no license needed for local work.
• Pro CI seatbelt runs via specwise ci-check, activated with SPECWISE_LICENSE_KEY in CI (keys start with sp_; never commit them).
• Today ci-check is fail-open (always exits 0) and prints a safety report; Pro will support fail-closed enforcement in CI soon.
• Signals in ci-check: AI density (AI vs human work), ghost spec risk (fixes without specs), and a CI threshold to flag risky states.
• No dashboard yet; focus is on CLI and CI seatbelt.
• Interested in Pro CI seatbelt? Open an issue at https://github.com/TomekKaszynski/SpecWise/issues to join early tests.

SpecWise sits in CI as a neutral auditor: it watches AI density and ghost specs so teams can move fast without letting AI wreck the codebase. Think “refactor insurance” for AI-heavy repos.

Enforcement config example (honored only with a Pro license + --strict):

{
  "enforcement": {
    "enabled": true,
    "aiDensityThreshold": 1.5,
    "ghostSpecTolerance": 0
  }
}

Pricing (beta)

• Local CLI – free forever for individual developers.
• CI Seatbelt Pro (planned) – starting around $19 per seat / month for teams that want CI to enforce AI safety rules.
• Founders Club (early beta) – limited lifetime deal for early teams; details via Pro contact.

This is beta pricing and may change; early teams will be grandfathered at their agreed rate. Want exact pricing or to join Founders Club? Open an issue at https://github.com/TomekKaszynski/SpecWise/issues.

| Feature | Free (local) | Pro CI seatbelt | |---------------------------------------|--------------|-----------------| | Local specs and fixes | Included | Included | | CI specwise ci-check report | Included | Included | | AI density and ghost spec metrics | Included | Included | | Pro enforcement preview signals | Included | Included | | Fail closed CI enforcement | Not yet | Planned Pro only |

Why Pro: Pro focuses on CI reliability and AI refactor insurance—keeping merges safe when AI work is high or specs are missing. It builds on the same CLI outputs you have locally, but adds enforcement in CI so risky runs can be blocked once enabled.

Founders Club (lifetime, limited)

• Lifetime Pro CI seatbelt for a small team (up to 5 seats).
• One-time $99 during early beta (standard price: $249 after early access).
• Capped at 50 teams.
• Local CLI stays free for everyone.

This is early Founders Club pricing. Standard lifetime pricing will be $249 after the first 50 teams.

Onboarding is manual (Stripe payment + license keys; no automated portal yet). See docs/founders-club.md in this repo and apply via GitHub issues.

CI example (GitHub Actions)

• Store SPECWISE_LICENSE_KEY as a repository secret; reference it with env: SPECWISE_LICENSE_KEY: ${{ secrets.SPECWISE_LICENSE_KEY }}.

jobs:
  ci-seatbelt:
    runs-on: ubuntu-latest
    env:
      SPECWISE_LICENSE_KEY: ${{ secrets.SPECWISE_LICENSE_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm install
      - run: npm run build
      - run: npx specwise ci-check --json  # fail-open today; emits a safety report
      # In Pro, this step can block based on aiDensity and ghostSpecs thresholds.

Pro enforcement (blocks risky AI merges)

      - run: npx specwise ci-check --strict
        env:
          SPECWISE_LICENSE_KEY: ${{ secrets.SPECWISE_LICENSE_KEY }}

Keep license keys out of .specwise/config.json in real teams. Current CI behavior is advisory; Pro will enable blocking rules in CI.

Licensing

• Local use is free; no license required.
• Pro (CI enforcement coming soon) uses SPECWISE_LICENSE_KEY.
• Keys start with sp_; keep them secret.

CI secrets

• Store SPECWISE_LICENSE_KEY as a CI secret (e.g., GitHub Actions) and read it via env.
• .specwise/config.json can hold licenseKey for local experiments, but avoid committing it in real teams.
• specwise ci-check is fail-open today and prints a CI safety report.

Husky v9 (pre-push example)

• Install Husky and init: npm install -D husky && npx husky init (adds "prepare": "husky").
• Example .husky/pre-push:

  #!/usr/bin/env sh
  . "$(dirname "$0")/_/husky.sh"
  npm test || exit 1
  npx specwise ci-check   # fail-open today; surfaces seatbelt signals

• ci-check is fail-open today, so this hook surfaces issues but won’t block pushes yet.

VS Code extension (coming soon)

• Planned extension will build on specwise snapshot --json and specwise ci-check --json.
• Current CLI outputs are stable; early adopters can script against them to prototype editors or dashboards. No hosted dashboard yet; focus is CLI and CI.

Dashboard (new)

Visual dashboard

Run:

npx specwise dashboard

This starts a local dashboard at http://localhost:3000 that shows:

• AI density for your repo
• Timeline of AI usage over time
• File heatmap by AI density and spec coverage
• “Share Score” button for posting your metrics on Twitter

Override the port if needed:

SPECWISE_DASHBOARD_PORT=4000 specwise dashboard

Troubleshooting

• specwise: command not found after npm link — add npm global bin to PATH. macOS/Linux: export PATH="$(npm bin -g):$PATH" (add to your shell rc).
• GEMINI_API_KEY is not set in specwise doctor — add to .env: echo "GEMINI_API_KEY=your_key" >> .env or export GEMINI_API_KEY=your_key, then rerun specwise doctor.
• Node version too low — SpecWise needs Node 18+. Check with node -v; upgrade via nvm or your package manager if below 18.

CLI commands

• specwise init - initialise a .specwise workspace.
• specwise spec "<goal>" - create a deterministic spec template.
• specwise spec-ai "<goal>" [--dry-run] - ask Gemini to generate a spec with small, safe steps.
• specwise fix <file> "<error>" - create a deterministic fix plan.
• specwise fix-ai <file> "<error>" [--dry-run] - ask Gemini to propose a minimal diff fix plan.
• specwise status - show today’s specs, fixes and commands from logs.
• specwise status --json - machine-readable status summary (JSON).
• specwise specs / specwise specs --json - list saved specs (human or JSON).
• specwise view-spec <index> - view a saved spec.
• specwise fixes / specwise fixes --json - list saved fix plans (human or JSON).
• specwise view-fix <index> - view a saved fix plan.
• specwise history / specwise history --json - show today’s actions from logs (human or JSON).
• specwise seatbelt [--json] [--set-mode warn|enforce|off] [--set-threshold <n>] - view or tune AI seatbelt.
• specwise metrics [--days <n>] [--json] - view AI vs human trend over recent days.
• specwise snapshot --json - one-call JSON summary for dashboards.
• specwise report [--json] [--days <n>] - shareable AI vs human safety snapshot.
• specwise ci-check [--json] - CI safety summary (fail-open today; enforcement with Pro later).
• specwise dashboard - start SpecWise dashboard at http://localhost:3000.

--dry-run prints the AI generated plan but does not save a spec or fix JSON file.

JSON APIs

SpecWise provides stable JSON shapes for integrations and dashboards:

• specwise status --json
• specwise snapshot --json
• specwise seatbelt --json
• specwise metrics --json
• specwise report --json
• specwise doctor --json

Examples:

specwise snapshot --json (top-level fields):

{
  "version": "0.3.0",
  "workspacePath": "/repo/.specwise",
  "configPath": "/repo/.specwise/config.json",
  "context": { "date": "2024-08-01", "specs": { "count": 2 } },
  "health": { "ok": true },
  "aiSpecs": 1,
  "humanSpecs": 1,
  "aiFixes": 0,
  "humanFixes": 1,
  "seatbeltStatus": "ok",
  "seatbelt": { "mode": "warn", "threshold": 1 }
}

specwise report --json (top-level fields):

{
  "daysBack": 7,
  "metrics": [
    { "date": "2024-08-01", "aiSpecs": 1, "humanSpecs": 2, "aiFixes": 0, "humanFixes": 1, "seatbeltStatus": "ok" }
  ],
  "seatbelt": { "mode": "warn", "threshold": 1 }
}

Review today's work

• specwise status now shows specs, fixes, commands, and a one-line seatbelt summary (mode, threshold, status, AI vs human counts, ratio).
• For scripts or dashboards, use specwise status --json instead of parsing human output.

Seatbelt & AI metrics

SpecWise tracks AI vs human work per day. Seatbelt modes:

• warn (default): warn when AI work exceeds your threshold ratio.
• enforce: block AI calls unless you override when the ratio is too high.
• off: disable warnings and enforcement.

View and tune seatbelt and ratios:

• specwise seatbelt / specwise seatbelt --json - see today’s AI/human counts, ratio, mode, threshold, status.
• specwise seatbelt --set-mode warn|enforce|off - update seatbelt mode in the current workspace.
• specwise seatbelt --set-threshold <n> - set the ratio threshold (e.g., 2.5).
• specwise metrics --days 7 / --json - see AI vs human trend over the last N days.
• specwise report / specwise report --json - shareable AI vs human safety snapshot (today + optional trend).

Philosophy

SpecWise is built around a simple idea:

Do not let AI take huge bites out of your codebase.

Always clarify, plan, patch, verify, log.

Keep work small enough that you never get stuck in the washing machine.

SpecWise seatbelt demo

Prerequisites

• Node.js 18 or newer
• SpecWise CLI installed from source (see Quickstart above).
• Valid GEMINI_API_KEY or OPENAI_API_KEY exported or in .env

Try the demo

specwise doctor
specwise spec-ai "Test the seatbelt line"
specwise seatbelt
specwise metrics --days 3
specwise report

What you should see

• When AI work goes above the threshold, seatbelt status shifts from ok to review-first (or stronger if configured).
• specwise report and specwise metrics summarize AI vs human specs and fixes for recent days so you can see the balance at a glance.
• For CI, use specwise ci-check or specwise ci-check --json as shown in the CI Seatbelt Pro section above.

Release checklist

For a new SpecWise CLI release:

1. Update the version in package.json.
2. npm run build
3. npm run test:smoke
4. git tag vX.Y.Z
5. git push origin main
6. git push origin vX.Y.Z
7. Update docs/releases/vX.Y.Z.md with a short release summary.

Update / uninstall

• Update: cd specwise && git pull && npm run build && npm link
• Uninstall: npm unlink -g specwise-cli (and optionally remove the cloned repo)