superintent 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Acodera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# superintent
+
+The CLI backend for [Superintent Development](https://github.com/acoderacom/superintent) — a framework where your intent drives the entire development cycle, and knowledge compounds with every iteration.
+
+Built on Turso/libSQL for ticket management, RAG-powered knowledge storage, and feature spec planning. Designed to work as the data layer for the **Superintent** Claude Code plugin.
+
+## The Loop
+
+```
+  ┌──────────────────────────────────┐
+  │                                  │
+  ▼                                  │
+Intent ──► Work ──► Test ──► Compound
+                                │
+                        knowledge extracted
+```
+
+**Intent** — Say what you want. Superintent figures out the right size: `/spec` for big features, `/ticket` for standard work, `/task` for quick fixes.
+
+**Work** — AI builds it, informed by knowledge from past cycles — patterns, architecture, gotchas, decisions.
+
+**Compound** — Knowledge is extracted from completed work and stored. What was built, how, why, what went wrong. This feeds back into the next cycle.
+
+## Features
+
+- **Ticket Management** — Structured tickets with intent, constraints, tasks, definition-of-done, change classification, and execution plans. Full lifecycle: Backlog → In Progress → In Review → Done.
+- **Knowledge Base (RAG)** — Semantic vector storage with 384-dimensional embeddings ([all-MiniLM-L6-v2](https://huggingface.co/Xenova/all-MiniLM-L6-v2)). Categories: `pattern`, `truth`, `principle`, `architecture`, `gotcha`. Confidence scoring with usage-based growth and staleness decay.
+- **Semantic Search** — Cosine similarity search across knowledge entries with namespace, category, tag, and ticket-type filters.
+- **Feature Specs** — Break big features into sequenced tickets. Specs link to their derived tickets.
+- **Knowledge Extraction** — Auto-generates knowledge proposals when tickets are marked Done. Extracts patterns, truths, principles, decisions, and trade-offs.
+- **Web Dashboard** — Kanban board, semantic search, knowledge browser, and spec viewer. Built with Hono + HTMX.
+
+## Requirements
+
+- Node.js >= 18.0.0
+
+## Installation
+
+```bash
+npm install -g superintent
+```
+
+Or use directly via npx:
+
+```bash
+npx superintent init
+```
+
+## Quick Start
+
+### Local Database (no account needed)
+
+```bash
+npx superintent init --url "file:.superintent/local.db"
+```
+
+### Cloud Database (Turso)
+
+Create `.superintent/.env`:
+
+```env
+TURSO_URL="libsql://your-db.turso.io"
+TURSO_AUTH_TOKEN="your-token"
+```
+
+Then initialize:
+
+```bash
+npx superintent init
+```
+
+### Verify
+
+```bash
+npx superintent status
+```
+
+## CLI Commands
+
+All commands output JSON in the format `{ success: boolean, data?: T, error?: string }`.
+
+### Setup
+
+| Command | Description |
+| --- | --- |
+| `superintent init [--url <url>] [--token <token>]` | Create database tables |
+| `superintent status` | Check connection and counts |
+| `superintent ui [-p <port>] [-o]` | Start web dashboard (default: port 3456) |
+
+### Tickets
+
+```bash
+# Create from markdown via stdin
+superintent ticket create --stdin <<'EOF'
+# Add user authentication
+
+**Type:** feature
+**Intent:** Add JWT-based authentication to the API
+**Context:** Currently no auth, all endpoints are public
+**Constraints:**
+- Use: jsonwebtoken, bcrypt
+- Avoid: session cookies
+**Assumptions:** PostgreSQL already stores user table
+**Change Class:** B - Adds new middleware to all routes
+EOF
+
+# Get, list, update, delete
+superintent ticket get TICKET-20260210-143000
+superintent ticket list --status "In Progress" --limit 10
+superintent ticket update TICKET-20260210-143000 --status "Done"
+superintent ticket delete TICKET-20260210-143000
+```
+
+**Update options:** `--status`, `--context`, `--comment`, `--spec`, `--plan-stdin`, `--complete-task <indices>`, `--complete-dod <indices>`, `--complete-all`
+
+### Knowledge
+
+```bash
+# Create from markdown via stdin
+superintent knowledge create --stdin <<'EOF'
+# API Error Handling Pattern
+
+**Namespace:** my-project
+**Category:** pattern
+**Source:** discovery
+**Confidence:** 0.85
+**Scope:** new-only
+**Tags:** api, error-handling, express
+
+## Content
+
+Why:
+Consistent error responses improve debugging and client experience.
+
+When:
+All new API endpoints.
+
+Pattern:
+Wrap route handlers in try/catch, return { success: false, error: message }.
+EOF
+
+# Search, list, get, update, activate/deactivate
+superintent search "error handling patterns" --limit 5
+superintent knowledge list --category pattern --namespace my-project
+superintent knowledge get KNOWLEDGE-20260210-150000
+superintent knowledge update KNOWLEDGE-20260210-150000 --confidence 0.9
+superintent knowledge deactivate KNOWLEDGE-20260210-150000
+superintent knowledge recalculate --dry-run
+```
+
+### Specs
+
+```bash
+# Create from markdown via stdin
+superintent spec create --stdin <<'EOF'
+# User Authentication System
+
+## Summary
+Full auth system with registration, login, JWT tokens, and middleware.
+
+## Tickets
+1. Add user model and registration endpoint
+2. Add login endpoint with JWT generation
+3. Add auth middleware to protected routes
+EOF
+
+# Get, list, update, delete
+superintent spec get SPEC-20260210-160000
+superintent spec list --limit 10
+superintent spec delete SPEC-20260210-160000
+```
+
+### Knowledge Extraction
+
+```bash
+# Extract knowledge proposals from a completed ticket
+superintent extract TICKET-20260210-143000
+```
+
+## Web Dashboard
+
+```bash
+superintent ui --open
+```
+
+Opens a web UI at `http://localhost:3456` with four tabs:
+
+1. **Kanban** — Ticket board with status columns, quick create, edit, and detail modals
+2. **Search** — Real-time semantic search across the knowledge base
+3. **Knowledge** — Filterable list with category, namespace, scope, and status filters
+4. **Specs** — Feature specs with linked ticket counts
+
+## Claude Code Plugin
+
+This CLI is the data layer for the [Superintent plugin](https://github.com/acoderacom/superintent). Install the plugin in Claude Code to get skill-driven workflows:
+
+| Skill | Trigger | What It Does |
+| --- | --- | --- |
+| `/ticket` | "I want...", "Add...", "Build..." | Create and execute structured tickets with planning, implementation, review, and knowledge extraction |
+| `/task` | "quick fix", "just do it" | Fast execution for confident, low-risk changes (Class A only) |
+| `/spec` | "spec", "plan feature", "big feature" | Write comprehensive specs for big features, then derive tickets |
+| `/learn` | "learn how...", "document how..." | Explore codebase and capture understanding as searchable knowledge |
+| `/explain` | "explain...", "why do we..." | Answer questions from the knowledge base before codebase exploration |
+| `/maintain` | "maintain", "sync knowledge" | Distill the knowledge database into CLAUDE.md between managed markers |
+
+The plugin auto-approves CLI commands via hooks, searches knowledge before every action, and extracts knowledge when tickets are completed — closing the compound loop.
+
+## Database
+
+Three tables:
+
+- **tickets** — Work items with structured metadata (tasks, DoD, plan, constraints, etc.)
+- **knowledge** — RAG entries with `F32_BLOB(384)` vector column and cosine similarity index
+- **specs** — Feature specifications linking to tickets via `origin_spec_id`
+
+Supports both local SQLite (`file:` URLs) and Turso Cloud (`libsql://` URLs).
+
+## Configuration
+
+Config is read from `.superintent/.env` or environment variables (`TURSO_URL`, `TURSO_AUTH_TOKEN`). Environment variables take priority.
+
+Local file URLs (`file:...`) do not require an auth token.
+
+## License
+
+MIT

package/bin/superintent.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/index.js');

package/dist/commands/extract.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const extractCommand: Command;

package/dist/commands/extract.js

@@ -0,0 +1,66 @@
+import { Command } from 'commander';
+import { getClient, closeClient } from '../db/client.js';
+import { parseTicketRow } from '../db/parsers.js';
+import { getProjectNamespace } from '../utils/config.js';
+import { generateExtractProposals } from './ticket.js';
+export const extractCommand = new Command('extract')
+    .description('Extract knowledge from a completed ticket')
+    .argument('<ticket-id>', 'Ticket ID to extract knowledge from')
+    .option('--namespace <namespace>', 'Override namespace (default: derived from ticket)')
+    .action(async (ticketId, options) => {
+    try {
+        const client = await getClient();
+        const result = await client.execute({
+            sql: 'SELECT * FROM tickets WHERE id = ?',
+            args: [ticketId],
+        });
+        closeClient();
+        if (result.rows.length === 0) {
+            const response = {
+                success: false,
+                error: `Ticket ${ticketId} not found`,
+            };
+            console.log(JSON.stringify(response));
+            process.exit(1);
+        }
+        const ticket = parseTicketRow(result.rows[0]);
+        if (ticket.status !== 'Done') {
+            const response = {
+                success: false,
+                error: `Ticket ${ticketId} is not Done (status: ${ticket.status}). Only completed tickets can have knowledge extracted.`,
+            };
+            console.log(JSON.stringify(response));
+            process.exit(1);
+        }
+        const namespace = options.namespace || getProjectNamespace();
+        const suggestions = generateExtractProposals(ticket, namespace);
+        // Output proposal for AI to review and confirm
+        const proposal = {
+            action: 'propose',
+            ticketId,
+            namespace,
+            ticket: {
+                intent: ticket.intent,
+                context: ticket.context || null,
+                assumptions: ticket.assumptions || null,
+                constraints_use: ticket.constraints_use || null,
+                constraints_avoid: ticket.constraints_avoid || null,
+                plan: ticket.plan || null,
+            },
+            suggestedKnowledge: suggestions,
+        };
+        const response = {
+            success: true,
+            data: proposal,
+        };
+        console.log(JSON.stringify(response));
+    }
+    catch (error) {
+        const response = {
+            success: false,
+            error: `Failed to extract knowledge: ${error.message}`,
+        };
+        console.log(JSON.stringify(response));
+        process.exit(1);
+    }
+});

package/dist/commands/init.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const initCommand: Command;

package/dist/commands/init.js

@@ -0,0 +1,56 @@
+import { Command } from 'commander';
+import { createClientWithConfig } from '../db/client.js';
+import { initSchema } from '../db/init-schema.js';
+import { saveConfig, loadConfig } from '../utils/config.js';
+export const initCommand = new Command('init')
+    .description('Create database tables (reads credentials from .superintent/.env)')
+    .option('--url <url>', 'Turso database URL (file:local.db for local, libsql://... for cloud)')
+    .option('--token <token>', 'Turso auth token (required for cloud, optional for local)')
+    .action(async (options) => {
+    try {
+        let url;
+        let token;
+        // If URL provided via CLI, use it
+        if (options.url) {
+            url = options.url;
+            token = options.token; // May be undefined for local URLs
+            saveConfig({ url, authToken: token });
+        }
+        else {
+            // Try to load from .env
+            try {
+                const config = loadConfig();
+                url = config.url;
+                token = config.authToken;
+            }
+            catch {
+                const response = {
+                    success: false,
+                    error: 'Create .superintent/.env with TURSO_URL (and TURSO_AUTH_TOKEN for cloud)',
+                };
+                console.log(JSON.stringify(response));
+                process.exit(1);
+            }
+        }
+        // Test connection and create tables
+        const client = await createClientWithConfig(url, token);
+        await initSchema(client);
+        client.close();
+        const response = {
+            success: true,
+            data: {
+                message: 'Database tables created successfully',
+                configPath: '.superintent/.env',
+            },
+        };
+        console.log(JSON.stringify(response));
+    }
+    catch (error) {
+        const response = {
+            success: false,
+            error: `Initialization failed: ${error.message}`,
+        };
+        console.log(JSON.stringify(response));
+        process.exit(1);
+    }
+});

package/dist/commands/knowledge.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const knowledgeCommand: Command;