nova-spec 1.0.0 → 1.0.2

package/AGENTS.md

@@ -42,6 +42,19 @@ context/
 
 Memory model: one fact = one file, filename = index, explicit supersede via `> Supersedes: <old>.md`. Wisdom about memory itself lives in `decisions/`, not in `AGENTS.md`.
 
+## Auto-sync on session start
+
+At the start of every session, check if nova-spec has pending updates by running:
+
+```
+/nova-sync
+```
+
+If `novaspec/.nova-manifest.json` exists and the installed version matches the latest, skip it silently. If there are updates or outdated custom overrides, report them to the user before proceeding.
+
+> **Claude Code** handles this automatically via a `SessionStart` hook in `.claude/settings.json`.
+> **OpenCode** relies on this instruction — always run `/nova-sync` at session start.
+
 ## Symlinks
 
 Claude Code discovers commands via `.claude/` symlinks pointing to `novaspec/`.

package/README.md

@@ -3,53 +3,49 @@
 </p>
 
 <p align="center">
-  <strong>Spec-Driven Development on top of Claude Code.</strong><br>
+  <strong>Spec-Driven Development for Claude Code and OpenCode.</strong><br>
   From a ticket to a merged PR in explicit steps, with architectural memory that doesn't decay.
 </p>
 
 <p align="center">
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
   <img alt="Status: experimental" src="https://img.shields.io/badge/status-experimental-orange.svg">
-  <img alt="Built for Claude Code" src="https://img.shields.io/badge/built%20for-Claude%20Code-purple.svg">
+  <a href="https://www.npmjs.com/package/nova-spec"><img alt="npm" src="https://img.shields.io/npm/v/nova-spec.svg"></a>
+  <img alt="Built for Claude Code" src="https://img.shields.io/badge/built%20for-Claude%20Code%20%7C%20OpenCode-purple.svg">
 </p>
 
 ---
 
 ## What it is
 
-`nova-spec` adds seven `/nova-*` commands to Claude Code that turn a ticket into a traceable change: classify, close requirements, plan, implement task by task, review, and wrap up with commit + PR + memory update. Memory (`context/decisions/`, `context/gotchas/`, `context/services/`) lives in atomic markdown files that humans edit and `grep` finds.
+`nova-spec` adds seven `/nova-*` slash commands to Claude Code (and OpenCode) that turn a ticket into a traceable change: classify, close requirements, plan, implement task by task, review, and wrap up with commit + PR + memory update.
 
-It's not a template or a generator. It's a set of conventions + commands that Claude Code runs as slash commands inside your repo.
+Architectural memory (`context/decisions/`, `context/gotchas/`, `context/services/`) lives in atomic markdown files that humans edit and `grep` finds.
+
+It's not a template or a generator. It's a set of conventions + commands that your AI agent runs as slash commands inside your repo.
 
 ## Who is this for
 
-- Developers using **Claude Code** (or OpenCode) on real projects, not toy demos.
+- Developers using **Claude Code** or **OpenCode** on real projects, not toy demos.
 - Teams that want their AI agent to follow a **disciplined ticket → PR flow** instead of one-shotting code.
 - Anyone tired of **re-explaining the same architectural context** every new chat.
 
 If you only use Claude Code for one-off scripts, this is overkill. If you ship to production with it, read on.
 
-## Why it exists
-
-Without discipline, an agent writes code fast and loses the *why*. The next ticket forces you to re-explain the same context. `nova-spec` enforces human checkpoints, separates spec from executable tasks, and leaves a trail in `context/` so the next ticket starts informed.
-
 ## Quickstart
 
 ```bash
-# 1. Clone nova-spec on your machine (one time only)
-git clone https://github.com/adansuku/nova-spec.git ~/tools/nova-spec
+npx nova-spec init
+```
+
+That's it. The interactive wizard asks where to install (global or per-project), which runtime (Claude Code, OpenCode, or both), and optionally your Jira connection. It generates a ready-to-use `config.yml` — no manual editing required.
 
-# 2. From the repo where you want to use it
-cd /path/to/your-project
-bash ~/tools/nova-spec/install.sh
+Then open your editor and run your first ticket:
 
-# 3. Open Claude Code and launch your first ticket
-claude
+```
 /nova-start PROJ-123
 ```
 
-Full details in [INSTALL.md](./INSTALL.md).
-
 ## A taste of it
 
 What `/nova-start PROJ-42` actually does:
@@ -72,7 +68,7 @@ Loaded context:
 Next step: /nova-spec
 ```
 
-No code yet. The agent has classified the work, created the branch, and pulled in only the architectural decisions that matter for this ticket. From here you'd move on to `/nova-spec` to close requirements, then `/nova-plan`, then `/nova-build`.
+No code yet. The agent classified the work, created the branch, and pulled in only the architectural decisions that matter for this ticket.
 
 ## Flow
 
@@ -82,7 +78,6 @@ No code yet. The agent has classified the work, created the branch, and pulled i
 
 | Command | What it does |
 |---|---|
-| `/nova-init` | One-off bootstrap: scans the repo and generates draft `context/services/` files with TODOs |
 | `/nova-start <TICKET>` | Pulls the ticket, classifies it (quick-fix / feature / architecture), creates a branch, loads context |
 | `/nova-spec` | Closes open decisions and writes `proposal.md` |
 | `/nova-plan` | Translates the spec into `tasks.md` (plan + tasks) |
@@ -90,8 +85,32 @@ No code yet. The agent has classified the work, created the branch, and pulled i
 | `/nova-review` | Final code review against spec, conventions and decisions |
 | `/nova-wrap` | Updates memory, archives the spec, creates commit and PR |
 | `/nova-status [TICKET]` | Current status of the ticket (read-only) |
+| `/nova-sync` | Updates nova-spec core to the latest version |
+| `/nova-diff <name>` | Shows diff between your custom override and the new core version |
+
+`quick-fix` tickets skip `/nova-spec` and `/nova-plan`.
+
+## Customizing skills and commands
+
+Place any file in `novaspec/custom/` to override the core version — same name, your rules:
 
-`quick-fix` tickets skip `/nova-spec` and `/nova-plan`. `/nova-init` is optional and runs only once when installing nova-spec into an existing repo.
+```
+novaspec/
+├── skills/         ← core (managed by nova-spec)
+└── custom/
+    └── skills/
+        └── nova-wrap/   ← your override, same name wins
+```
+
+Run `/nova-sync` to update the core. Your `custom/` folder is never touched.
+
+## Keeping up to date
+
+```bash
+npx nova-spec sync
+```
+
+Updates the core, preserves your custom overrides and `config.yml`, and tells you if any of your overrides have upstream changes worth reviewing.
 
 ## Principles
 
@@ -102,15 +121,10 @@ No code yet. The agent has classified the work, created the branch, and pulled i
 
 ## Documentation
 
-- Detailed install: [INSTALL.md](./INSTALL.md)
-- Internal architecture: [novaspec/README.arch.md](./novaspec/README.arch.md)
-- Quick reference: [novaspec/README.quickref.md](./novaspec/README.quickref.md)
+- Install options: [INSTALL.md](./INSTALL.md)
+- Design philosophy: [PHILOSOPHY.md](./PHILOSOPHY.md)
 - Contributing: [CONTRIBUTING.md](./CONTRIBUTING.md)
 
-## See also
-
-`nova-spec` was built using itself. The full development history — including specs, decisions, gotchas and dogfooding — is preserved in the lab repo: [adansuku/nova-spec-lab](https://github.com/adansuku/nova-spec-lab).
-
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/lib/installer.js

@@ -131,9 +131,10 @@ function installFiles(destDir, runtime, scope) {
     if (!fs.existsSync(notes)) fs.writeFileSync(notes, '');
   }
 
-  // Runtime symlinks / .opencode settings
+  // Runtime symlinks / settings
   if (runtime === 'claude' || runtime === 'both') {
     createSymlinks(destDir, '.claude');
+    writeClaudeSettings(path.join(destDir, '.claude'));
   }
   if (runtime === 'opencode' || runtime === 'both') {
     createSymlinks(destDir, '.opencode');
@@ -150,13 +151,40 @@ function createSymlinks(destDir, dotDir) {
   for (const name of ['commands', 'skills', 'agents']) {
     const link = path.join(dir, name);
     const target = path.join('..', 'novaspec', name);
-    if (fs.existsSync(link) || fs.lstatSync(link).isSymbolicLink?.()) {
-      fs.rmSync(link, { recursive: true, force: true });
-    }
+    fs.rmSync(link, { recursive: true, force: true });
     fs.symlinkSync(target, link);
   }
 }
 
+function writeClaudeSettings(claudeDir) {
+  const settingsPath = path.join(claudeDir, 'settings.local.json');
+  const hook = {
+    hooks: {
+      SessionStart: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              command: 'npx nova-spec@latest sync 2>/dev/null || true',
+              timeout: 30,
+            },
+          ],
+        },
+      ],
+    },
+  };
+
+  if (fs.existsSync(settingsPath)) {
+    const existing = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    if (existing.hooks?.SessionStart) return; // already configured
+    existing.hooks = existing.hooks || {};
+    existing.hooks.SessionStart = hook.hooks.SessionStart;
+    fs.writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + '\n');
+  } else {
+    fs.writeFileSync(settingsPath, JSON.stringify(hook, null, 2) + '\n');
+  }
+}
+
 function writeOpenCodeSettings(opencodeDir) {
   const settingsPath = path.join(opencodeDir, 'settings.local.json');
   if (!fs.existsSync(settingsPath)) {
@@ -216,6 +244,7 @@ function ensureGitignore(destDir) {
     'novaspec/custom/',
     '.env',
     'notes.md',
+    '.claude/settings.local.json',
     '.opencode/settings.local.json',
     '.opencode/node_modules/',
     '.DS_Store',

package/lib/sync.js

@@ -87,6 +87,15 @@ async function sync(destDir = process.cwd()) {
   // Restore config
   if (configBackup) fs.writeFileSync(configPath, configBackup);
 
+  // Update AGENTS.md and CLAUDE.md (always overwrite — these are framework files)
+  for (const file of ['AGENTS.md', 'CLAUDE.md']) {
+    const src = path.join(PACKAGE_ROOT, file);
+    const dest = path.join(destDir, file);
+    if (fs.existsSync(src) && fs.existsSync(dest)) {
+      fs.copyFileSync(src, dest);
+    }
+  }
+
   // Regenerate manifest with new hashes
   const newManifest = generateManifest(novaspecDest);
 
@@ -114,6 +123,9 @@ async function sync(destDir = process.cwd()) {
   newManifest.outdated_customs = outdated;
   fs.writeFileSync(manifestPath, JSON.stringify(newManifest, null, 2) + '\n');
 
+  // Ensure SessionStart hook is present (idempotent)
+  ensureSessionStartHook(destDir);
+
   // Report
   console.log('\n  ✓ nova-spec core updated to v' + newManifest.version + '\n');
 
@@ -144,4 +156,32 @@ function copyDirSync(src, dest) {
   }
 }
 
+function ensureSessionStartHook(destDir) {
+  const hook = {
+    type: 'command',
+    command: 'npx nova-spec@latest sync 2>/dev/null || true',
+    timeout: 30,
+  };
+
+  const targets = [
+    path.join(destDir, '.claude', 'settings.local.json'),
+    path.join(destDir, '.opencode', 'settings.local.json'),
+  ].filter(p => fs.existsSync(path.dirname(p))); // only if runtime dir exists
+
+  for (const settingsPath of targets) {
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+      try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch (_) {}
+    }
+
+    const existing = settings.hooks?.SessionStart?.[0]?.hooks?.[0];
+    if (existing?.command === hook.command) continue; // already up to date
+
+    // Overwrite if missing or using outdated command (e.g. without @latest)
+    settings.hooks = settings.hooks || {};
+    settings.hooks.SessionStart = [{ hooks: [hook] }];
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  }
+}
+
 module.exports = { sync, generateManifest };

package/novaspec/.nova-manifest.json

@@ -0,0 +1,30 @@
+{
+  "version": "1.0.1",
+  "generated_at": "2026-05-10T07:46:23.881Z",
+  "hashes": {
+    "commands/nova-build": "5d9c103168f97dd60e4efbe1f9a277a7",
+    "commands/nova-diff": "529389d8d7d187c70de708610101009c",
+    "commands/nova-plan": "44709e96a49e86d808f3cad94c0bdc86",
+    "commands/nova-review": "aa2e4e91fe5e774ae7f374c7f3bf8882",
+    "commands/nova-spec": "726194e235d566dfbb81e785a6437b46",
+    "commands/nova-start": "d031e1958cf769864f566e9d768b1552",
+    "commands/nova-status": "cf0b7db18d4290479c35ed3b87fecc56",
+    "commands/nova-sync": "4364efbb594eeddaff7deba8d7e2a947",
+    "commands/nova-wrap": "846dfee6faaba65d80c082bb90e9b306",
+    "skills/close-requirement": {
+      "SKILL.md": "43d5f32320a635b15601a21ef5a0bf93"
+    },
+    "skills/jira-integration": {
+      "SKILL.md": "513f8b116be4bed955a8e3631bbf250c"
+    },
+    "skills/update-service-context": {
+      "SKILL.md": "b0788661cc61e2c6acb4bead24f48017"
+    },
+    "skills/write-decision": {
+      "SKILL.md": "20ea0ac9f19ec17a72d562f811c4a61e"
+    },
+    "agents/context-loader": "42a4cf797452bd76c720bd8f36e261f4",
+    "agents/nova-review-agent": "5658926243d4ce01cfc3b79ee8e4ad93"
+  },
+  "outdated_customs": []
+}

package/novaspec/commands/nova-sync.md

@@ -12,7 +12,7 @@ which custom overrides may need attention.
 Execute in the terminal:
 
 ```bash
-npx nova-spec sync
+npx nova-spec@latest sync
 ```
 
 Show the output to the user as-is.
@@ -43,4 +43,4 @@ If everything is clean:
 
 - Don't modify any custom files.
 - Don't auto-merge or apply changes.
-- If `npx nova-spec sync` fails, show the error and stop.
+- If `npx nova-spec@latest sync` fails, show the error and stop.

package/novaspec/config.yml

@@ -0,0 +1,23 @@
+# nova-spec — project configuration
+# This file is gitignored — do not push it to the repo.
+
+branch:
+  pattern: "{type}/{ticket}-{slug}"
+  types:
+    bugfix: bugfix
+    hotfix: hotfix
+    feature: feature
+    documentation: docs
+    refactor: refactor
+    chore: chore
+    architecture: arch
+  ticket_case: upper
+  base: main
+
+jira:
+  skill: "jira-integration"
+  url: https://your-workspace.atlassian.net
+  project: PROJ
+  email: 
+  token: ${JIRA_API_TOKEN}
+  done_transition_id: "41"

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "nova-spec",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Spec-Driven Development framework for Claude Code and OpenCode",
   "bin": {
-    "nova-spec": "./bin/nova-spec.js"
+    "nova-spec": "bin/nova-spec.js"
   },
   "files": [
     "bin/",
@@ -23,7 +23,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Adansuku/nova-spec"
+    "url": "git+https://github.com/Adansuku/nova-spec.git"
   },
   "keywords": [
     "claude-code",