@kynetic-ai/spec 0.10.0 → 0.12.0

package/README.md

@@ -1,497 +1,97 @@
-# Kynetic Spec (kspec)
+# kspec
 
-> **Warning: Experimental Software**
->
-> This project is a work-in-progress and is not ready for production use. APIs, file formats, and CLI commands may change without notice. Use at your own risk.
->
-> If you're interested in the project, feel free to explore the code and design docs, but please don't depend on it for real work yet.
+`kspec` is spec-first task management for AI-assisted development.
 
-A structured specification and task management system designed for AI-assisted development. kspec provides a YAML-based format for defining project specifications that can be programmatically manipulated, with a task system to track implementation progress.
+It gives you a durable spec tree, linked implementation tasks, and a shadow-branch workflow that keeps project planning state out of your main git history. The result is a tighter loop between "what should exist", "what is being worked on", and "what shipped".
 
-**Key feature**: kspec is self-hosting - it tracks its own development using itself.
+> Early-stage software: expect rough edges and command/API changes while the workflow stabilizes.
 
-## Installation
+## Why teams use it
 
-### Quick Start (Development)
+- Define features and requirements before implementation.
+- Derive tasks directly from specs instead of duplicating intent in tickets.
+- Keep spec and task state in a separate `kspec-meta` branch via the `.kspec/` worktree.
+- Give human and AI contributors the same project context through `kspec session start` and generated agent instructions.
 
-```bash
-# Clone and install
-git clone <repo-url>
-cd kynetic-spec
-npm install
-
-# Run with npm (recommended - works from any project directory)
-npm run dev -- <command>
-```
-
-### Build and Link Globally
-
-```bash
-npm run build
-npm link
-
-# Now available as 'kspec' globally
-kspec tasks ready
-```
-
-## Basic Usage
-
-```bash
-# Initialize a new project
-kspec init
-
-# See what tasks are ready to work on
-kspec tasks ready
-
-# Task lifecycle
-kspec task start @task-slug
-kspec task note @task-slug "What you're doing..."
-kspec task submit @task-slug          # Code done, PR created
-kspec task complete @task-slug --reason "Summary"
-
-# Capture ideas
-kspec inbox add "idea or random thought"
-
-# Validate spec files
-kspec validate
-
-# Search across everything
-kspec search "pattern"
-```
-
-## Agent Integration
-
-kspec is agent-agnostic but designed to work well with AI coding assistants. The key integration point is **author attribution** for notes.
-
-### Quick Setup
-
-Run the setup command to auto-configure your agent environment:
-
-```bash
-kspec setup           # Auto-detect and configure
-kspec setup --dry-run # Preview what would be done
-```
-
-The setup command detects which agent you're running in and installs the appropriate configuration.
-
-**Supported agents:**
-- Claude Code (`CLAUDE_PROJECT_DIR`)
-- Cline (`CLINE_ACTIVE`)
-- Gemini CLI (`GEMINI_CLI`)
-- Codex CLI (`CODEX_SANDBOX`)
-- Aider (`AIDER_MODEL`)
-- OpenCode (`OPENCODE_CONFIG_DIR`)
-- Amp (`AMP_API_KEY`)
-- GitHub Copilot CLI
-
-### How Author Detection Works
-
-When adding notes, kspec auto-detects the author using this fallback chain:
-
-1. `KSPEC_AUTHOR` environment variable (explicit config)
-2. `git config user.name` (developer identity)
-3. `USER`/`USERNAME` env var (system user)
+## Quick start
 
-### Manual Setup
+Install `kspec`:
 
-If auto-setup doesn't work, configure manually:
-
-**Claude Code** - Add to `~/.claude/settings.json`:
-```json
-{
-  "env": {
-    "KSPEC_AUTHOR": "@claude"
-  }
-}
-```
-
-**Aider** - Add to `~/.aider.conf.yml`:
-```yaml
-env:
-  KSPEC_AUTHOR: "@aider"
-```
-
-**Other agents** - Set in shell profile:
 ```bash
-export KSPEC_AUTHOR="@agent-name"
-```
-
-Convention: Use `@` prefix for agent authors (e.g., `@claude`, `@copilot`) to distinguish from human authors.
-
-## References
-
-All items (tasks, spec items, inbox, plans) can be referenced by:
-- **Full ULID**: `01KEYQSD2QJCNGRKSR38V0E3BM`
-- **Short ULID**: `01KEYQSD` (unique prefix)
-- **Slug**: `@my-task-slug`
-
-## Task Management
-
-### Task States
-
+npm install -g @kynetic-ai/spec
 ```
-pending → in_progress → pending_review → completed
-              ↓              ↓
-          blocked ←──────────┘
-              ↓
-          cancelled
-```
-
-**State transitions:**
-- `kspec task start` → `in_progress`
-- `kspec task submit` → `pending_review` (code done, awaiting merge)
-- `kspec task complete` → `completed` (from `pending_review`)
-- `kspec task complete --skip-review --reason "..."` → `completed` (bypass review requirement)
-- `kspec task complete --force` → `completed` (even if blocked)
-- `kspec task block` → `blocked`
-- `kspec task unblock` → `pending`
-- `kspec task cancel` → `cancelled`
 
-### Commands
+Or run it without a global install:
 
 ```bash
-# List tasks
-kspec tasks list                    # All tasks
-kspec tasks list --status pending   # Filter by status
-kspec tasks list --tag mvp          # Filter by tag
-kspec tasks list --count            # Count only
-kspec tasks ready                   # Tasks ready to work on
-kspec tasks next                    # Highest priority ready task
-kspec tasks blocked                 # Blocked tasks
-kspec tasks in-progress             # Active tasks
-
-# Task operations
-kspec task get <ref>                # View details
-kspec task start <ref>              # Begin work
-kspec task submit <ref>             # Submit for review
-kspec task complete <ref>           # Mark done
-kspec task complete --force <ref>   # Force complete from any state
-kspec task block <ref> --reason "..." # Block with reason
-kspec task unblock <ref>            # Remove block
-kspec task cancel <ref>             # Cancel task
-kspec task reset <ref>              # Reset to pending
-kspec task delete <ref>             # Delete permanently
-
-# Notes and todos
-kspec task note <ref> "message"     # Add note
-kspec task notes <ref>              # View notes
-kspec task todo add <ref> "text"    # Add a todo item
-kspec task todos <ref>              # View todos
-
-# Create tasks
-kspec task add --title "My task" --priority 2 --slug my-task
-kspec task add --title "Bug fix" --type bug --spec-ref @feature --tag urgent
-
-# Update tasks
-kspec task set <ref> --priority 1 --tag critical
-kspec task set <ref> --depends-on @other-task
+npx @kynetic-ai/spec --help
 ```
 
-## Spec Item Management
-
-Spec items define WHAT to build — features, requirements, constraints.
+Initialize a project:
 
 ```bash
-# List and browse
-kspec item list                        # All items
-kspec item list --type feature         # Filter by type
-kspec item list --tree                 # Hierarchical view
-kspec item list --count                # Count only
-kspec item types                       # Item types and counts
-kspec item tags                        # Tags and counts
-
-# View details
-kspec item get <ref>                   # Item details
-kspec item status <ref>                # Implementation status + linked tasks
-
-# Create items (--under is required)
-kspec item add --under @parent --title "My Feature" --type feature --slug my-feature
-kspec item add --under @parent --title "Sub-feature" --type requirement
-kspec item add --under @parent --title "Auditable" --type constraint --trait @trait-ref
-
-# Trait lifecycle
-kspec trait list                       # Discover available traits
-kspec trait get <ref>                  # Trait details and ACs
-kspec trait add "Trait Name" --description "..." --slug my-trait
-
-# Update items
-kspec item set <ref> --title "New Title" --priority 1
-kspec item set <ref> --relates-to @other-item    # Add relationship
-kspec item set <ref> --implements @parent-item    # Add implements link
-kspec item set <ref> --depends-on @dependency     # Add dependency
-kspec item set <ref> --clear-relates-to           # Clear relationships
-
-# Notes
-kspec item note <ref> "Design rationale..."
-kspec item notes <ref>
-
-# Acceptance criteria
-kspec item ac list <ref>
-kspec item ac add <ref> --given "user is logged in" --when "they click logout" --then "session ends"
-kspec item ac set <ref> ac-1 --then "updated expectation"
-kspec item ac remove <ref> ac-1
-
-# Traits
-kspec item trait add <ref> @trait-a @trait-b
-kspec item trait remove <ref> @trait-a
-
-# Derive implementation task from spec
-kspec derive <ref>                     # Create task from spec item
-kspec derive --all --dry-run           # Preview tasks for all unlinked specs
-```
-
-## Inbox
-
-Low-friction capture for ideas that aren't yet tasks.
-
-```bash
-kspec inbox add "idea or random thought"         # Capture
-kspec inbox add "tagged idea" --tag dx --tag cli  # With tags
-kspec inbox list                                  # Show items (oldest first)
-kspec inbox list --newest --limit 5               # Recent items
-kspec inbox list --tag dx                         # Filter by tag
-kspec inbox list --count                          # Count only
-kspec inbox get <ref>                             # View details
-
-# Edit items
-kspec inbox set <ref> --content "updated text"    # Update content
-kspec inbox set <ref> --tag new-tag               # Add tags
-kspec inbox set <ref> --clear-tags                # Remove all tags
-kspec inbox note <ref> "additional context"       # Append a note
-
-# Convert to task
-kspec inbox promote <ref> --title "Task title"
-kspec inbox promote <ref> --title "Task" --priority 2 --note "Context from triage"
-
-# Remove
-kspec inbox delete <ref>
-```
-
-## Plans
-
-Plans capture implementation context and rationale. They can auto-generate specs and tasks from structured markdown.
-
-```bash
-# Create plans
-kspec plan add --title "Feature Name" --content "Description..."
-kspec plan add --title "Feature Name" --content-file ./plan.md
-
-# Import structured plan (auto-creates specs and tasks)
-kspec plan import ./plan.md --module @target-module --dry-run   # Preview
-kspec plan import ./plan.md --module @target-module             # Execute
-kspec plan import ./plan.md --module @target-module --update    # Re-import
-
-# Manage plans
-kspec plan list                          # List all plans
-kspec plan get <ref>                     # View details
-kspec plan set <ref> --status active     # Update status
-kspec plan note <ref> "Progress..."      # Add note
-kspec plan derive <ref>                  # Create task from plan
-```
-
-## Validation
-
-Validate spec files for schema conformance, reference integrity, and alignment.
-
-```bash
-kspec validate                    # Full validation
-kspec validate --schema           # Schema conformance only
-kspec validate --refs             # Reference resolution only
-kspec validate --alignment        # Spec-task alignment
-kspec validate --completeness     # Spec completeness
-kspec validate --orphans          # Orphaned items
-kspec validate --strict           # Treat warnings as errors
-kspec validate --warnings-ok      # Treat warnings-only as success (exit 0)
-kspec validate --fix              # Auto-fix (invalid ULIDs, missing timestamps)
-kspec validate -v                 # Verbose output
-```
-
-**Exit codes:** `0` = success, `4` = validation errors, `6` = warnings only (unless `--warnings-ok`).
-
-## Session Log
-
-View and search historical session data.
-
-```bash
-kspec session log list                     # List sessions with stats
-kspec session log list --since 7d          # Recent sessions
-kspec session log list --agent ralph       # Filter by agent type
-kspec session log show <session-id>        # Detailed session view
-kspec session log show <id> --events       # Include events
-kspec session log stats                    # Aggregate analytics
-kspec session log stats --by-day           # Daily breakdown
-kspec session log stats --tool-usage       # Tool usage stats
-kspec session log search "pattern"         # Search across events
-```
-
-## Search and Export
-
-```bash
-# Search across items, tasks, inbox, and meta
-kspec search "pattern"
-kspec search "auth" --tasks-only
-kspec search "feature" --items-only --limit 10
-
-# Git history by spec/task
-kspec log @task-ref                  # Commits related to a ref
-kspec log --spec @spec-ref           # Search by spec trailer
-kspec log --since "2 weeks ago"      # Filter by date
-
-# Export
-kspec export                         # JSON export
-kspec export --format html -o out.html
-```
-
-## Batch Execution
-
-Execute multiple commands atomically or with per-command commits.
-
-```bash
-# Atomic (default) — single commit, rollback on failure
-echo '[{"command":"task note","args":{"ref":"@task","message":"update"}}]' | kspec batch
-kspec batch --file commands.json
-
-# Immediate mode — per-command commits
-kspec batch --no-atomic --file commands.json
-
-# Continue on error, dry run
-kspec batch --continue --file commands.json
-kspec batch --dry-run --file commands.json
-
-# Discover available batch commands
-kspec batch commands
-```
-
-Each command: `{"command": "cli path", "args": {...}, "id": "optional"}`. Only mutating commands allowed. Typos in command names produce did-you-mean suggestions.
-
-## Shadow Branch
-
-kspec stores spec/task state on a separate orphan branch (`kspec-meta`) via a git worktree at `.kspec/`. This keeps spec changes out of your main branch history.
-
-```bash
-kspec init                    # Initialize project (creates shadow branch)
-kspec shadow status           # Check shadow branch health
-kspec shadow sync             # Sync with remote
-kspec shadow repair           # Fix broken worktree
-kspec shadow log              # Recent shadow commits
+kspec init
+kspec setup
+kspec session start
 ```
 
-## Utility Commands
+That three-command sequence is the common starting point across real kspec projects:
 
-```bash
-kspec util ulid               # Generate a valid ULID
-kspec util ulid --count 5     # Generate multiple ULIDs
-kspec help                    # Extended help
-kspec help --all              # Full command reference
-kspec help --exit-codes       # Exit code documentation
-kspec help <cmd> --json-schema  # JSON Schema for a command
-```
+1. `kspec init` creates the project manifest plus the `.kspec/` shadow worktree.
+2. `kspec setup` configures agent authoring and local runtime integration.
+3. `kspec session start` shows active work, ready tasks, and pending project context.
 
-## Task File Format
-
-Tasks are stored in YAML files (`*.tasks.yaml`):
-
-```yaml
-- _ulid: 01KEYQSD2QJCNGRKSR38V0E3BM
-  slugs: [my-task]
-  title: My task title
-  type: task          # task, epic, bug, spike, infra
-  status: pending     # pending, in_progress, pending_review, completed, blocked, cancelled
-  priority: 2         # 1 (highest) to 5 (lowest)
-  spec_ref: "@feature-slug"
-  depends_on: ["@other-task"]
-  tags: [mvp]
-  notes:
-    - _ulid: 01KEYRJ953HRYWJ0W4XEG6J9FB
-      created_at: "2026-01-14T17:00:00Z"
-      author: "@claude"
-      content: |
-        Started implementing feature X...
-```
+For install details, cloning existing kspec projects, and troubleshooting, see [INSTALL.md](INSTALL.md).
 
-## JSON Output
+## The spec-first loop
 
-Add `--json` flag for machine-readable output:
+The core workflow is short:
 
 ```bash
-kspec --json tasks ready
-kspec --json task get @my-task
-```
+# 1. Define what should exist
+kspec item add --under @main --title "Contributing guide" --type feature --slug contributing-guide
+kspec item ac add @contributing-guide \
+  --given "a new contributor opens the repository" \
+  --when "they look for project workflow guidance" \
+  --then "they can follow a documented path to set up, make changes, and submit work"
 
-## Project Structure
+# 2. Derive implementation work from the spec
+kspec derive @contributing-guide
 
-```
-kynetic-spec/
-├── .kspec/                    # kspec's own spec (shadow branch worktree)
-│   ├── kynetic.yaml          # Root manifest
-│   ├── project.tasks.yaml    # Active tasks
-│   ├── project.inbox.yaml    # Inbox items
-│   └── modules/              # Spec items by domain
-├── src/                       # TypeScript implementation
-│   ├── schema/               # Zod schemas
-│   ├── parser/               # YAML loading
-│   └── cli/                  # Command handlers
-└── tests/                     # Vitest tests
-```
-
-## Development
+# 3. Start and track execution
+kspec task start @task-contributing-guide
+kspec task note @task-contributing-guide "Drafting CONTRIBUTING.md and linking it from README."
 
-```bash
-# Run tests
-npm test
-npm run test:watch
+# 4. Submit after code/docs + PR are ready
+kspec task submit @task-contributing-guide
 
-# Type check
-npm run build
-
-# Run CLI in dev mode
-npm run dev -- tasks ready
+# 5. Complete after merge
+kspec task complete @task-contributing-guide --reason "Merged in PR #123."
 ```
 
-### Troubleshooting: ESM + npm link
+For the full walkthrough from install to first completed task, see [docs/getting-started.md](docs/getting-started.md).
 
-When using `npm link` to develop kspec globally, ESM module detection can break without proper symlink resolution. This manifests as the CLI executing twice or commands not working correctly.
+## How it works
 
-**Symptoms:**
-- Commands execute twice
-- CLI seems to hang or behave unexpectedly
-- "Cannot find module" errors when using `npm link`
+### Specs stay separate from product code
 
-**Why it happens:**
-- `npm link` creates symlinks for global CLI binaries
-- Node.js ESM uses `import.meta.url` to detect if a module is the main entry point
-- Without symlink resolution, `import.meta.url` doesn't match the symlinked path
-- This causes the module to be imported but not executed, or executed multiple times
+By default, `kspec` stores specs, tasks, plans, and workflow state inside `.kspec/`, which is a git worktree backed by an orphan `kspec-meta` branch. Your source branch stays focused on code. Your planning state remains versioned and auditable.
 
-**The fix:**
-kspec uses `fs.realpathSync()` to resolve symlinks before comparing paths:
+### Tasks stay linked to intent
 
-```javascript
-// src/cli/index.ts
-const scriptPath = realpathSync(process.argv[1]);
-if (import.meta.url === `file://${scriptPath}`) {
-  program.parse();
-}
-```
+When you run `kspec derive @spec-ref`, the resulting task keeps a `spec_ref` back to the originating item. Reviews can validate the implementation against acceptance criteria instead of relying on a loosely-related ticket title.
 
-This ensures the CLI works correctly whether run via:
-- `npm run dev` (direct TypeScript execution)
-- `npm link` (symlinked global binary)
-- `node dist/cli/index.js` (built code)
+### Agents get the same context humans do
 
-**For contributors:** If you encounter similar issues in ESM CLIs, remember to resolve symlinks before path comparisons. The pattern is:
-1. Import `realpathSync` from `fs`
-2. Resolve `process.argv[1]` before comparing with `import.meta.url`
-3. This makes the CLI work correctly in all installation modes
+`kspec setup` and `kspec agents generate` produce project-scoped instructions and skills so agents can follow the same conventions, workflows, and task lifecycle you use manually.
 
-## Design Decisions
+## Where to go next
 
-- **Library-first**: Core parsing logic is separate from CLI for reuse
-- **Zod schemas**: TypeScript-native validation
-- **YAML format**: Human-readable, git-friendly, supports comments
-- **ULID identifiers**: Time-sortable, globally unique, shortenable
-- **Slug aliases**: Human-friendly names that map to ULIDs
+- [docs/getting-started.md](docs/getting-started.md): first-project tutorial for humans and agents
+- [INSTALL.md](INSTALL.md): installation, setup modes, and troubleshooting
+- [AGENTS.md](AGENTS.md): project instructions for agent contributors
+- [docs/history/KYNETIC_SPEC_DESIGN.md](docs/history/KYNETIC_SPEC_DESIGN.md): design rationale and architecture history
 
-## License
+## Developing kspec itself
 
-MIT
+This repository is the source for the `@kynetic-ai/spec` npm package. If you want to work on `kspec` rather than adopt it in another repo, use the contributor/development setup in [INSTALL.md](INSTALL.md#from-source) and the project workflow in [AGENTS.md](AGENTS.md).

package/dist/agent-runtime/bootstrap.d.ts

@@ -0,0 +1,31 @@
+import type { Agent } from "../schema/meta.js";
+import type { DispatchWorkspaceMetadata, DispatchWorkspaceRole } from "./workspace.js";
+export interface DispatchBootstrapStep {
+    source: "dispatch" | "agent";
+    name: string;
+    run: string;
+    roles?: Array<DispatchWorkspaceRole>;
+    idempotent: boolean;
+    allowTrackedChanges: boolean;
+    reviewerRerunAllowed: boolean;
+}
+export interface EnsureWorkspaceBootstrapOptions {
+    projectDir: string;
+    workspaceDir: string;
+    metadataPath: string;
+    metadata: DispatchWorkspaceMetadata;
+    role: DispatchWorkspaceRole;
+    agent: Agent;
+    env: Record<string, string>;
+}
+export interface EnsureWorkspaceBootstrapResult {
+    metadata: DispatchWorkspaceMetadata;
+    reused: boolean;
+    ranSteps: boolean;
+}
+export declare class DispatchBootstrapError extends Error {
+    suggestion: string;
+    constructor(message: string, suggestion: string);
+}
+export declare function ensureWorkspaceBootstrap(options: EnsureWorkspaceBootstrapOptions): Promise<EnsureWorkspaceBootstrapResult>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/agent-runtime/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/bootstrap.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAEV,yBAAyB,EACzB,qBAAqB,EACtB,MAAM,gBAAgB,CAAC;AAMxB,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACrC,UAAU,EAAE,OAAO,CAAC;IACpB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,+BAA+B;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,yBAAyB,CAAC;IACpC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,yBAAyB,CAAC;IACpC,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,UAAU,EAAE,MAAM,CAAC;gBAEP,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAKhD;AAoJD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,8BAA8B,CAAC,CAwOzC"}