nova-spec 1.0.4 → 1.0.5

package/AGENTS.md

@@ -1,6 +1,6 @@
 # nova-spec — framework AGENTS.md
 
-> This repo uses CLAUDE.md as a stub → AGENTS.md is the instructions file.
+> This repo uses `CLAUDE.md` as a stub → `AGENTS.md` is the instructions file.
 
 This repo is the **nova-spec framework itself** — a Spec-Driven Development (SDD) system for Claude Code. It's designed to be installed into other projects.
 
@@ -8,6 +8,22 @@ This repo is the **nova-spec framework itself** — a Spec-Driven Development (S
 
 Framework that orchestrates ticket-to-PR workflow with 7 slash commands: `/nova-start` → `/nova-spec` → `/nova-plan` → `/nova-build` → `/nova-review` → `/nova-wrap` → `/nova-status`.
 
+## Installation (consumer repos)
+
+To install nova-spec into another repo, run:
+
+```bash
+npx nova-spec init
+```
+
+That leaves the repo usable without manual steps:
+
+- `AGENTS.md` and `CLAUDE.md` (shim that points to `AGENTS.md`)
+- `novaspec/` framework files
+- `.claude/` symlinks (and optionally `.opencode/`)
+- `context/` memory structure
+- `novaspec/config.yml` is **gitignored** (local per-repo configuration)
+
 ## Key commands
 
 - `/nova-start <TICKET>` — classify ticket, create branch, load context
@@ -52,8 +68,13 @@ At the start of every session, check if nova-spec has pending updates by running
 
 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.
+This repo (and consumer repos) use `npx nova-spec sync` to update stock files **idempotently** without clobbering local edits.
+Sync records what was last shipped to the repo in `novaspec/.nova-manifest.json`, and only updates files that are still untouched locally.
+
+Hooks are maintained in:
+
+- `.claude/settings.local.json` (Claude Code)
+- `.opencode/settings.local.json` (OpenCode)
 
 ## Symlinks
 
@@ -66,6 +87,14 @@ This repo uses itself. When modifying nova-spec:
 2. Verify symlinks work: `ls -la .claude/`
 3. Run through a full ticket cycle
 
+## Tests
+
+Run the smoke test suite with:
+
+```bash
+npm test
+```
+
 ## Reference
 
 - Full docs: [README.md](./README.md)

package/CLAUDE.md

@@ -0,0 +1,3 @@
+AGENTS.md
+
+This repository uses `AGENTS.md` as the single source of truth for working instructions.

package/PHILOSOPHY.md

@@ -94,14 +94,14 @@ We accept living without features. We do not accept living with bloat. The cost
 
 ## Forking and customization
 
-**Today (known limitation).** The installer does `rm -rf novaspec/` and re-copies from source. Local edits to `novaspec/commands/`, `skills/`, `templates/`, or `agents/` are **lost on re-run**. The installer only preserves `novaspec/config.yml` (via backup) and the consumer's `context/`.
+**Today.** Updates are applied with `npx nova-spec sync`, which is idempotent and will not overwrite local edits to stock framework files. Sync records the last-shipped hashes in `novaspec/.nova-manifest.json` and:
 
-This contradicts principle 5. We acknowledge the gap. Two practical paths today:
+- Updates files that are still untouched locally
+- Skips files you edited and reports them so you can merge intentionally
 
-- **Team fork**: clone the nova-spec repo into your team's space, customize, install from your fork. Your fork is your `SCRIPT_DIR`.
-- **Manual updates**: don't re-run the installer; pull updates by hand and merge edits.
+This keeps the framework from being the reason you can't ship: your local edits remain yours.
 
-**Planned (not built).** A `team-overrides/` directory that survives re-installs. Until shipped, the fork is the answer. Do not pretend otherwise to consumers.
+If you need deeper customization, commit it in your repo (or fork nova-spec). When upstream changes touch files you customized, sync will intentionally refuse to overwrite them — you choose how to merge.
 
 ---
 

package/lib/forge.js

@@ -38,7 +38,9 @@ function buildPrCommand({ forge, cli, title, body, base }) {
     return `gh pr create --base ${q(base)} --title ${q(title)} --body ${q(body)}`;
   }
   if (forge === 'gitlab' || resolvedCli === 'glab') {
-    return `glab mr create --target-branch ${q(base)} --title ${q(title)} --description ${q(body)} --fill`;
+    // NOTE: Avoid `--fill` because it can trigger glab autofill/push behavior depending on user config.
+    // We always pass title/body explicitly, and we never implicitly push.
+    return `glab mr create --target-branch ${q(base)} --title ${q(title)} --description ${q(body)} --yes`;
   }
   throw new Error(`Unknown forge: ${forge}`);
 }

package/lib/installer.js

@@ -7,6 +7,7 @@ const {
   generateManifest,
   buildHookCommand,
   HOOK_MARKER,
+  MANIFEST_FILE,
 } = require('./sync.js');
 const { detectForge } = require('./forge.js');
 const { listTransitionsAsync } = require('./jira.js');
@@ -15,7 +16,6 @@ const PACKAGE_ROOT = path.join(__dirname, '..');
 const NOVASPEC_SRC = path.join(PACKAGE_ROOT, 'novaspec');
 const AGENTS_SRC = path.join(PACKAGE_ROOT, 'AGENTS.md');
 const CLAUDE_MD_SRC = path.join(PACKAGE_ROOT, 'CLAUDE.md');
-const MANIFEST_FILE = '.nova-manifest.json';
 
 async function init() {
   console.log('\n  nova-spec installer\n  ───────────────────\n');

package/lib/jira.js

@@ -79,58 +79,6 @@ async function transitionAsync({ url, email, token, ticket, transitionId }) {
   });
 }
 
-function runCli() {
-  // CLI mode: node lib/jira.js <command> [args...]
-  const [, , cmd, ...args] = process.argv;
-  const { JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN } = process.env;
-
-  if (!JIRA_URL || !JIRA_EMAIL || !JIRA_API_TOKEN) {
-    console.error('Missing env vars: JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN');
-    process.exit(2);
-  }
-
-  const baseArgs = { url: JIRA_URL, email: JIRA_EMAIL, token: JIRA_API_TOKEN };
-  let promise;
-
-  switch (cmd) {
-    case 'get':
-      if (!args[0]) {
-        console.error('Usage: nova-jira get <TICKET>');
-        process.exit(2);
-      }
-      promise = getIssueAsync({ ...baseArgs, ticket: args[0] });
-      break;
-    case 'transitions':
-      if (!args[0]) {
-        console.error('Usage: nova-jira transitions <TICKET>');
-        process.exit(2);
-      }
-      promise = listTransitionsAsync({ ...baseArgs, ticket: args[0] });
-      break;
-    case 'transition':
-      if (!args[0] || !args[1]) {
-        console.error('Usage: nova-jira transition <TICKET> <TRANSITION_ID>');
-        process.exit(2);
-      }
-      promise = transitionAsync({ ...baseArgs, ticket: args[0], transitionId: args[1] });
-      break;
-    default:
-      console.error('Commands: get <TICKET> | transitions <TICKET> | transition <TICKET> <ID>');
-      process.exit(2);
-  }
-
-  promise
-    .then((r) => {
-      if (r != null) console.log(JSON.stringify(r, null, 2));
-    })
-    .catch((err) => {
-      console.error(err.message);
-      process.exit(err.status === 401 ? 401 : err.status === 404 ? 404 : 1);
-    });
-}
-
-if (require.main === module) runCli();
-
 module.exports = {
   getIssueAsync,
   listTransitionsAsync,

package/lib/sync.js

@@ -245,4 +245,5 @@ module.exports = {
   collectPackageFiles,
   HOOK_MARKER,
   FRAMEWORK_FILES,
+  MANIFEST_FILE,
 };

package/novaspec/agents/context-loader.md

@@ -27,7 +27,7 @@ If `context/` doesn't exist, return:
 ## Loaded context
 **Services**: not documented (context/ missing)
 **Decisions**: none
-**Gaps**: context/ structure not initialized — run `npx nova-spec init`
+**Gaps**: context/ structure not initialized — run npx nova-spec init
 **Questions**: none
 ```
 And stop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nova-spec",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Spec-Driven Development framework for Claude Code and OpenCode",
   "bin": {
     "nova-spec": "bin/nova-spec.js"
@@ -15,6 +15,7 @@
     "novaspec/templates/",
     "novaspec/config.example.yml",
     "AGENTS.md",
+    "CLAUDE.md",
     "INSTALL.md",
     "PHILOSOPHY.md"
   ],