nova-spec 1.0.2 → 1.0.4

package/INSTALL.md

@@ -0,0 +1,144 @@
+# Installing nova-spec
+
+---
+
+## Quick install
+
+```bash
+npx nova-spec init
+```
+
+The interactive wizard guides you through:
+
+1. **Scope** — install globally (all your projects) or just in the current repo
+2. **Runtime** — Claude Code, OpenCode, or both
+3. **Jira** — optional: URL, project key, email, Done transition ID
+4. **Branch** — base branch (default: `main`)
+
+It generates a ready-to-use `novaspec/config.yml`. No manual editing required.
+
+---
+
+## What gets installed
+
+```
+.
+├── AGENTS.md                    Repo anchor — first thing the agent reads
+├── notes.md                     Scratch pad
+│
+├── novaspec/                    Framework content (edit any file directly)
+│   ├── config.yml               Your project config (gitignored)
+│   ├── commands/                /nova-* slash commands
+│   ├── skills/                  Auxiliary skills (Jira, memory, etc.)
+│   ├── agents/                  Subagents (context-loader, review)
+│   ├── guardrails/              Shared preconditions (bash scripts)
+│   ├── templates/               Artifact templates (PR body, commit, etc.)
+│   └── .nova-manifest.json      Tracks last-shipped hashes (gitignored)
+│
+├── .claude/                     Symlinks so Claude Code discovers the commands
+│   ├── commands -> ../novaspec/commands
+│   ├── skills   -> ../novaspec/skills
+│   └── agents   -> ../novaspec/agents
+│
+├── .opencode/                   (only if you install for OpenCode)
+│   └── ... (same symlinks)
+│
+└── context/                     Architectural memory
+    ├── decisions/               Why we did X (one fact per file)
+    │   └── archived/
+    ├── gotchas/                 Non-obvious traps
+    ├── services/                One flat file per service
+    └── changes/
+        ├── active/              In-progress specs
+        └── archive/             Closed specs
+```
+
+---
+
+## Global vs project install
+
+| | Global (`~/.claude`) | Project (`.claude/`) |
+|---|---|---|
+| Works everywhere | ✓ | ✗ |
+| Per-repo customization | ✗ | ✓ |
+| Commit with the team | ✗ | ✓ |
+
+Choose **global** for personal use. Choose **project** when the team shares the same flow.
+
+---
+
+## Verification
+
+After installing, open Claude Code or OpenCode at the repo root and type `/` — you should see the `/nova-*` commands in autocomplete.
+
+Run your first ticket:
+
+```
+/nova-start TICKET-ID
+```
+
+---
+
+## Customizing the framework
+
+Edit any file under `novaspec/` directly. There is no separate "custom" folder — your edits live where they're used:
+
+```bash
+# Customize the PR/MR description for your team
+$EDITOR novaspec/templates/pr-body.md
+
+# Add an extra step to /nova-wrap
+$EDITOR novaspec/commands/nova-wrap.md
+```
+
+When `npx nova-spec sync` runs, it hashes every framework file and compares it with what was last shipped. If it matches → safe to overwrite with the new version. If it differs → you've edited it, sync skips it and reports the path so you can `/nova-diff <path>` to see what changed upstream.
+
+Your customizations are part of your repo. Commit them with the team — every developer gets the same flow.
+
+---
+
+## Keeping up to date
+
+`npx nova-spec sync` runs automatically every time Claude Code or OpenCode start (via a `SessionStart` hook). You can also run it manually:
+
+```bash
+npx nova-spec sync
+```
+
+Or from inside Claude Code / OpenCode:
+
+```
+/nova-sync
+```
+
+The sync report lists: new files, updated files (untouched locally), skipped files (you edited), and removed files. Your local edits are always preserved.
+
+---
+
+## Uninstall
+
+```bash
+rm -rf novaspec .claude .opencode
+rm -f AGENTS.md notes.md
+```
+
+> This also removes all architectural memory (`context/`). Move it elsewhere first if you want to keep it.
+
+---
+
+## Common issues
+
+### Commands don't show up
+
+1. Check symlinks: `ls -la .claude/`
+2. Restart Claude Code (it sometimes caches the listing)
+3. Verify files in `novaspec/commands/` have valid frontmatter (`description:`)
+
+### Broken symlinks after cloning
+
+```bash
+git config core.symlinks true
+git reset --hard HEAD
+```
+
+On native Windows, symlinks require Developer Mode or admin. Use WSL instead.

package/PHILOSOPHY.md

@@ -0,0 +1,149 @@
+# Philosophy
+
+> **Simple. The developer controls the framework, not the other way around.**
+
+This document is the antibody to scope creep. Read it before adding a feature, before adopting nova-spec in a new team, and before saying yes to a feature request.
+
+If a future version of nova-spec is "richer" but no longer fits this document, **the document wins**. We will remove features to defend the philosophy. We will not change the philosophy to justify features.
+
+---
+
+## Core principles
+
+### 1. Form, not substance
+
+nova-spec enforces **shape** — sequence, file structure, naming conventions. It does **not** enforce **quality** — whether your spec is good, whether your decision is right, whether your code is correct. Quality is the developer's job.
+
+A check that requires LLM judgment to evaluate is not a guardrail. It's a suggestion. Don't dress it up as the former. Real guardrails are deterministic (e.g. `guardrails/old-decision-archived.md`: bash, file existence, exit code). Everything else is a check or a convention — call it that.
+
+### 2. Plain markdown, no DSLs
+
+Specs, decisions, gotchas, services, templates — all plain markdown. No frontmatter required except where Claude Code demands it for slash commands and skills. No schema enforcement. No build step.
+
+If a junior cannot open `context/decisions/<x>.md` and understand the decision in 30 seconds, the file is wrong, not the format.
+
+### 3. No hidden state
+
+Everything lives in git: `context/`, `novaspec/`, `AGENTS.md`. No database, no daemon, no telemetry, no cloud component. If Claude Code disappears tomorrow, your repo still tells the full story.
+
+This is the property that makes nova-spec survivable across tool changes. Defend it.
+
+### 4. Atomic memory
+
+One fact = one file. Filename = index (no `NNNN-` prefixes, no global numbering, no frontmatter). Supersede explicitly with `> Supersedes: <old>.md` and `git mv` the old file to `archived/`. The bash validator in `guardrails/old-decision-archived.md` enforces this invariant — that is a real guardrail because it is deterministic and exits non-zero.
+
+### 5. The developer can always escape
+
+If a phase gate gets in the way of real work, the developer can:
+
+- Skip it manually (touch the expected file, mark a task done by hand)
+- Edit the relevant command in their own `novaspec/commands/` and re-run
+- Bypass nova-spec entirely and use Claude Code raw
+
+The framework must never be the reason a developer cannot ship.
+
+---
+
+## In scope
+
+- Ticket → branch → spec → plan → build → review → wrap workflow
+- Atomic markdown memory: `decisions/`, `gotchas/`, `services/`
+- Slash commands for Claude Code and OpenCode (via symlinks)
+- Optional Jira integration as one skill (opt-in via `config.yml`)
+- Phase gates that enforce **sequence** (file existence, branch shape)
+- Human checkpoints where review materially matters (post-spec, pre-wrap)
+- Templates as starting points
+
+That's the surface. Everything else needs an explicit decision.
+
+---
+
+## Out of scope (we will say no)
+
+We say no to:
+
+- **CI/CD integration.** Your CI is your team's concern.
+- **Cross-repo coordination.** One repo = one nova-spec instance.
+- **Auto-merge or auto-approve PRs.** Humans decide.
+- **Hosted memory, DB, or cloud component.** Markdown in git is the system of record.
+- **Issue tracker abstraction layer.** Jira is the integrated path; Linear/GitHub Issues/Asana = fork the skill, don't extend core.
+- **Real-time collaboration features.** Git handles concurrency.
+- **Telemetry or metrics dashboards.** Out of scope by principle.
+- **Auto-generated tests or auto-style fixes.** The dev decides what to test and how to style.
+- **Plugins beyond markdown skills.** If it requires a runtime, server, or daemon, it does not belong in nova-spec.
+- **Multi-tenant config.** One project = one `config.yml`.
+- **Bypassable LLM-judgment-based blocks.** A "guardrail" that depends on the model reading carefully is not a guardrail.
+
+This list is allowed to grow. It is not allowed to shrink without justification.
+
+---
+
+## Decision criteria for new features
+
+Before merging a feature, the answer to all five must be acceptable:
+
+1. **Form or substance?** If it enforces substance, reject.
+2. **Is the runtime cost zero?** If it requires a server, daemon, DB, or external service, reject.
+3. **Can a junior understand it in 5 minutes from the file alone?** If not, simplify or reject.
+4. **Could a 10-line fork in the consuming repo achieve the same result?** If yes, don't add to core. Document the fork pattern instead.
+5. **Does it survive if Claude Code is replaced by another tool tomorrow?** If no, think hard.
+
+We accept living without features. We do not accept living with bloat. The cost of saying no is borne by one team. The cost of saying yes is borne by every team that adopts nova-spec from then on.
+
+---
+
+## 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/`.
+
+This contradicts principle 5. We acknowledge the gap. Two practical paths today:
+
+- **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.
+
+**Planned (not built).** A `team-overrides/` directory that survives re-installs. Until shipped, the fork is the answer. Do not pretend otherwise to consumers.
+
+---
+
+## How another team adopts nova-spec
+
+This is not a sales pitch. It is the contract:
+
+1. You will read this document. If anything here is incompatible with how your team works, do not adopt nova-spec — pick a tool whose philosophy fits.
+2. You will pin to a tagged version (e.g. `v0.x.y`). You will not track `main`.
+3. If you need something nova-spec does not have, you fork. You do not block on us merging your change.
+4. If your fork generalizes, open a PR with rationale against the decision criteria above.
+5. We do not promise backward compatibility across major versions. We do promise to document breaking changes in the release notes.
+
+If those terms are unacceptable, OpenSpec or GitHub Spec Kit are externally maintained alternatives — adopt those instead. We won't be offended.
+
+---
+
+## Review cadence
+
+Every 3 months, the maintainers re-read this file and answer in writing:
+
+- Has any principle been quietly violated?
+- Has any "out of scope" item snuck in?
+- Has the lema started to feel like a slogan instead of a practice?
+- Are we saying yes to feature requests we should be saying no to?
+
+If yes to any: revert or remove the offending feature, or rewrite the relevant principle to acknowledge the change explicitly. **The framework is allowed to lose features. It is not allowed to lose its soul.**
+
+---
+
+## Maintainer's commitment
+
+The maintainers commit to:
+
+- Saying no to feature requests that violate this document, even from people they like.
+- Defending simplicity over completeness when the two conflict.
+- Treating "we already built it" as a reason to remove, not a reason to keep.
+- Writing down what we removed and why, in `context/decisions/`.
+
+The maintainers do **not** commit to:
+
+- Long-term backward compatibility.
+- Supporting every team's specific tooling.
+- Accepting every PR that "would be useful."
+- Replacing tools that already do the job better externally.

package/README.md

@@ -60,6 +60,8 @@ Affected services: auth-api ✓
 Branch created: feature/PROJ-42-rate-limit-login (from main)
 
 Loaded context:
+  Stack: ✓ loaded
+  Conventions: ✓ loaded
   Services: auth-api ✓
   Decisions read: throttling-strategy.md, redis-usage.md
   Gaps: none
@@ -86,31 +88,44 @@ No code yet. The agent classified the work, created the branch, and pulled in on
 | `/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 |
+| `/nova-diff <path>` | Shows diff between your local edits and the latest package version |
 
 `quick-fix` tickets skip `/nova-spec` and `/nova-plan`.
 
-## Customizing skills and commands
+## Customizing the framework
 
-Place any file in `novaspec/custom/` to override the core version — same name, your rules:
+Edit any file under `novaspec/` directly. **There is no separate "custom" folder** — your edits live where they're used. `npx nova-spec sync` hash-compares every file and never overwrites the ones you've touched.
 
-```
-novaspec/
-├── skills/         ← core (managed by nova-spec)
-└── custom/
-    └── skills/
-        └── nova-wrap/   ← your override, same name wins
-```
+### The 5 things your team will likely want to change
+
+1. **PR / MR template** → `novaspec/templates/pr-body.md`
+   What `/nova-wrap` puts in the description box. Add your team's QA checklist, ticket-link format, security notes.
+
+2. **Code review checklist** → `novaspec/templates/review.md`
+   The structure `/nova-review` follows. Add your conventions, your blockers, your sections.
+
+3. **Commit message format** → `novaspec/templates/commit.md`
+   Conventional commits, custom prefixes, ticket-in-subject — whatever your team enforces.
 
-Run `/nova-sync` to update the core. Your `custom/` folder is never touched.
+4. **Ticket system** → `novaspec/config.yml` → `ticket_system`
+   Set to `jira` for Atlassian Jira, or `none` to paste tickets manually. `none` skips ticket-key validation in `/nova-start`.
+
+5. **Stack & conventions context** → `context/stack.md` and `context/conventions.md`
+   Loaded at the start of every ticket so the agent knows your tech, your patterns, your "we don't do that here". The installer creates both files with comments explaining what to put in them.
+
+Other useful tweaks: forge (`config.yml` → `forge.type`: github/gitlab), branch base (`branch.base`), guardrails (`novaspec/guardrails/*.sh`).
+
+After any edit, commit it with the team — everyone gets the same flow.
 
 ## Keeping up to date
 
+`npx nova-spec sync` runs automatically when Claude Code or OpenCode start (via a `SessionStart` hook). You can also run it manually:
+
 ```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.
+It updates only the files you haven't edited locally and reports the rest.
 
 ## Principles
 

package/lib/cli.js

@@ -1,7 +1,10 @@
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
 const { init } = require('./installer.js');
 const { sync } = require('./sync.js');
+const jira = require('./jira.js');
 
 async function run() {
   const command = process.argv[2];
@@ -14,11 +17,160 @@ async function run() {
     case 'sync':
       await sync();
       break;
+    case 'jira':
+      await runJira(process.argv.slice(3));
+      break;
+    case 'forge':
+      await runForge(process.argv.slice(3));
+      break;
+    case 'source':
+      runSource(process.argv.slice(3));
+      break;
     default:
       console.error(`Unknown command: ${command}`);
-      console.error('Usage: nova-spec [init|sync]');
+      console.error('Usage: nova-spec [init|sync|jira <subcmd>|forge <subcmd>|source <path>]');
       process.exit(1);
   }
 }
 
+function runSource(args) {
+  const [relPath] = args;
+  if (!relPath) {
+    console.error('Usage: nova-spec source <relative-path>');
+    process.exit(2);
+  }
+  const PACKAGE_ROOT = path.join(__dirname, '..');
+  const abs = path.join(PACKAGE_ROOT, relPath);
+  if (!fs.existsSync(abs)) {
+    console.error(`✗ ${relPath} is not part of the nova-spec package.`);
+    process.exit(1);
+  }
+  console.log(abs);
+}
+
+async function runJira(args) {
+  const [subcmd, ...rest] = args;
+  if (!subcmd) {
+    console.error('Usage: nova-spec jira <get|transitions|transition> [args...]');
+    process.exit(2);
+  }
+
+  const config = readJiraConfig();
+  if (!config) {
+    console.error('  ✗ Jira not configured. Run `npx nova-spec init` and enable Jira.');
+    process.exit(1);
+  }
+
+  try {
+    let result;
+    if (subcmd === 'get') {
+      if (!rest[0]) throw new Error('Usage: nova-spec jira get <TICKET>');
+      result = await jira.getIssueAsync({ ...config, ticket: rest[0] });
+    } else if (subcmd === 'transitions') {
+      if (!rest[0]) throw new Error('Usage: nova-spec jira transitions <TICKET>');
+      result = await jira.listTransitionsAsync({ ...config, ticket: rest[0] });
+    } else if (subcmd === 'transition') {
+      if (!rest[0] || !rest[1]) throw new Error('Usage: nova-spec jira transition <TICKET> <ID>');
+      result = await jira.transitionAsync({ ...config, ticket: rest[0], transitionId: rest[1] });
+    } else {
+      throw new Error(`Unknown jira subcommand: ${subcmd}`);
+    }
+    if (result != null) console.log(JSON.stringify(result, null, 2));
+  } catch (err) {
+    if (err.status === 401) {
+      console.error('  ✗ Jira 401: invalid credentials. Regenerate JIRA_API_TOKEN.');
+    } else if (err.status === 404) {
+      console.error(`  ✗ Jira 404: ticket not found.`);
+    } else {
+      console.error(`  ✗ ${err.message}`);
+    }
+    process.exit(err.status || 1);
+  }
+}
+
+async function runForge(args) {
+  const { detectForge, buildPrCommand, reviewTerm, checkCliAvailable } = require('./forge.js');
+  const [subcmd, ...rest] = args;
+
+  if (subcmd === 'detect') {
+    const f = detectForge();
+    if (f) console.log(f);
+    else process.exit(1);
+    return;
+  }
+
+  if (subcmd === 'pr-command') {
+    const config = readForgeConfig();
+    const forge = config.type !== 'auto' ? config.type : detectForge();
+    if (!forge || forge === 'none') {
+      console.error('  ✗ Forge not detected. Set forge.type in novaspec/config.yml.');
+      process.exit(2);
+    }
+    const cli = config.cli !== 'auto' ? config.cli : null;
+    const [title, body, base] = rest;
+    if (!title || !body || !base) {
+      console.error('Usage: nova-spec forge pr-command <title> <body> <base>');
+      process.exit(2);
+    }
+    console.log(buildPrCommand({ forge, cli, title, body, base }));
+    return;
+  }
+
+  if (subcmd === 'term') {
+    const config = readForgeConfig();
+    const forge = config.type !== 'auto' ? config.type : detectForge();
+    console.log(reviewTerm(forge));
+    return;
+  }
+
+  console.error('Usage: nova-spec forge <detect|pr-command|term>');
+  process.exit(2);
+}
+
+function readJiraConfig() {
+  const configPath = path.join(process.cwd(), 'novaspec', 'config.yml');
+  if (!fs.existsSync(configPath)) return null;
+  const text = fs.readFileSync(configPath, 'utf8');
+
+  const url = extractYamlScalar(text, 'jira', 'url');
+  const email = extractYamlScalar(text, 'jira', 'email');
+  let token = extractYamlScalar(text, 'jira', 'token');
+
+  if (token && /^\$\{[A-Z_]+\}$/.test(token)) {
+    const envName = token.slice(2, -1);
+    token = process.env[envName];
+  } else if (token === '${JIRA_API_TOKEN}' || !token) {
+    token = process.env.JIRA_API_TOKEN;
+  }
+
+  if (!url || !email || !token) return null;
+  return { url, email, token };
+}
+
+function readForgeConfig() {
+  const configPath = path.join(process.cwd(), 'novaspec', 'config.yml');
+  const defaults = { type: 'auto', cli: 'auto' };
+  if (!fs.existsSync(configPath)) return defaults;
+  const text = fs.readFileSync(configPath, 'utf8');
+  return {
+    type: extractYamlScalar(text, 'forge', 'type') || 'auto',
+    cli: extractYamlScalar(text, 'forge', 'cli') || 'auto',
+  };
+}
+
+function extractYamlScalar(text, parent, key) {
+  // Minimal YAML reader for `parent: \n  key: value` blocks. Strips quotes.
+  const re = new RegExp(`^${parent}:\\s*$([\\s\\S]*?)(?=^\\S|\\Z)`, 'm');
+  const block = text.match(re);
+  if (!block) return null;
+  const lineRe = new RegExp(`^\\s+${key}:\\s*(.*)$`, 'm');
+  const match = block[1].match(lineRe);
+  if (!match) return null;
+  let value = match[1].trim();
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    value = value.slice(1, -1);
+  }
+  return value;
+}
+
 module.exports = { run };

package/lib/forge.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const { execSync } = require('child_process');
+
+function detectForge(cwd = process.cwd()) {
+  let remote = '';
+  try {
+    remote = execSync('git remote get-url origin', { cwd, stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim();
+  } catch (_) {
+    return null;
+  }
+
+  if (!remote) return null;
+  if (/github\.com[:/]/i.test(remote)) return 'github';
+  if (/gitlab[.-][\w.-]+[:/]|gitlab\.com[:/]/i.test(remote)) return 'gitlab';
+  if (/bitbucket\.org[:/]/i.test(remote)) return 'bitbucket';
+  return null;
+}
+
+function pickCli(forge, configCli) {
+  if (configCli && configCli !== 'auto') return configCli;
+  if (forge === 'github') return 'gh';
+  if (forge === 'gitlab') return 'glab';
+  return null;
+}
+
+function buildPrCommand({ forge, cli, title, body, base }) {
+  const resolvedCli = cli || pickCli(forge);
+  if (!resolvedCli) {
+    throw new Error(`No CLI configured for forge "${forge}". Set forge.cli in config.yml.`);
+  }
+
+  const q = (s) => `'${String(s ?? '').replace(/'/g, `'\\''`)}'`;
+
+  if (forge === 'github' || resolvedCli === 'gh') {
+    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`;
+  }
+  throw new Error(`Unknown forge: ${forge}`);
+}
+
+function reviewTerm(forge) {
+  // GitHub uses "PR" / "Pull Request"; GitLab uses "MR" / "Merge Request".
+  if (forge === 'gitlab') return 'MR';
+  return 'PR';
+}
+
+function checkCliAvailable(cli) {
+  try {
+    execSync(`${cli} --version`, { stdio: 'ignore' });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+module.exports = { detectForge, pickCli, buildPrCommand, reviewTerm, checkCliAvailable };