Skip to content

INSTALL.md

Latest commit

 

History

History
168 lines (117 loc) · 5.72 KB

INSTALL.md

File metadata and controls

168 lines (117 loc) · 5.72 KB

Installing kspec in Your Project

This guide covers installing and setting up kspec in your own projects. For developing kspec itself, see README.md.

Prerequisites

  • Node.js v18 or later
  • npm (or pnpm/yarn)
  • Git - Your project must be a git repository for shadow branch mode (the default)
  • Bun (optional) - Required only for the daemon/web UI (kspec serve). Not needed for CLI-only usage. Install from bun.sh

Installation

npm (Recommended)

npm install -g @kynetic-ai/spec

Or without global install:

npx @kynetic-ai/spec <command>

From Source

For development or pre-release versions:

git clone https://github.com/lepahc/kynetic-spec.git ~/tools/kspec
cd ~/tools/kspec
npm install && npm run build && npm link

For agents developing kspec itself, use the bootstrap script which handles setup automatically:

git clone https://github.com/lepahc/kynetic-spec.git
cd kynetic-spec
node scripts/bootstrap.cjs

The bootstrap script:

  • Detects current state (skips steps that aren't needed)
  • Runs install, build, link, and init as required
  • Reports what actions it took (transparency)
  • Shows session context at the end

Setup

There are two setup paths depending on whether your project already uses kspec.

Fresh Project (No Existing kspec)

For projects not yet using kspec:

cd your-project
kspec init        # Creates shadow branch + .kspec/ worktree
kspec setup       # Configure agent author + hooks

This creates:

.kspec/                     # Shadow worktree (gitignored from main branch)
  <project>.yaml            # Manifest
  <project>.tasks.yaml      # Task file
  modules/
    main.yaml               # Spec items

The shadow branch (kspec-meta) keeps spec/task files separate from your main branch history. If you're not using git or prefer simpler setup, use kspec init --no-shadow to create files in spec/ instead. See kspec-agents.md for architecture details.

Existing kspec Project (Cloning a Repo)

When cloning a repository that already uses kspec:

git clone <repo-url>
cd <repo>
kspec setup --auto-worktree  # Creates .kspec/ from existing kspec-meta branch

This is the typical path for agents joining established projects. The --auto-worktree flag automatically creates the .kspec/ directory if the kspec-meta branch exists on the remote.

Agent Configuration

The kspec setup command auto-detects your agent environment and configures:

  • KSPEC_AUTHOR - Environment variable for note attribution (e.g., @claude, @aider)
  • Hooks - Claude Code hooks for spec-first reminders and session checkpoints
kspec setup              # Auto-detect and configure
kspec setup --dry-run    # Preview what would be configured
kspec setup --no-hooks   # Skip hook installation

For broader setup context and the spec-first workflow after install, see README.md and docs/getting-started.md.

Verification

After setup, verify everything works:

kspec --version        # Confirm installation
kspec shadow status    # Should show "healthy"
kspec session start    # Should display project context

Also check:

  • .kspec/ directory exists
  • .kspec/ is listed in .gitignore

Working Directory

Important: Always run kspec commands from your project root, not from inside .kspec/.

If you see "Cannot run kspec from inside .kspec/ directory", navigate to your project root first:

cd ..  # Return to project root
kspec session start

Quick Reference

Essential commands after setup:

kspec session start              # Get context at session start
kspec task start @task-slug      # Begin work on a task
kspec task note @task-slug "..." # Document what you're doing
kspec inbox add "..."            # Capture ideas for later

See docs/getting-started.md for the full first-task walkthrough.

Troubleshooting

Issue Solution
"Bun runtime is required" Install Bun: curl -fsSL https://bun.sh/install | bash (only needed for kspec serve)
"kspec: command not found" Run npm install -g @kynetic-ai/spec, or if using source: npm link
"Not a git repository" Run git init first, or use kspec init --no-shadow
"Cannot find .kspec" Run kspec init (fresh project) or kspec setup --auto-worktree (cloned repo)
".kspec already exists" Use kspec init --force to reinitialize
"Cannot run from inside .kspec/" Run cd .. to return to project root
Shadow branch errors Run kspec shadow repair
Sync conflicts Run kspec shadow resolve

Recovery Commands

kspec shadow status    # Diagnose issues
kspec shadow repair    # Fix broken worktree
kspec init --force     # Reinitialize completely (use as last resort)

Next Steps