nova-spec 1.0.0

package/novaspec/guardrails/checklist.md

@@ -0,0 +1,34 @@
+# Guardrails — Checklist
+
+**Execution order: 1 → 2 → 3 → 4 → 5 → 6**
+
+## 1. branch-pattern
+Verify the active ticket branch. Extract `<ticket-id>` from the current git branch.
+- Must follow the pattern `(feature|fix|arch)/<TICKET>-<slug>` from `novaspec/config.yml`.
+- ⛔ **Stop.** Run `/nova-start <TICKET>` first.
+
+## 2. proposal-exists
+Verify the spec is drafted.
+- `context/changes/active/<ticket-id>/proposal.md` must exist.
+- ⛔ **Stop.** Run `/nova-spec` first.
+
+## 3. tasks-exist
+Verify tasks. Quick-fix exception (`fix/` branch).
+- If **not quick-fix**: `context/changes/active/<ticket-id>/tasks.md` must exist.
+- If **quick-fix**: you can continue without `tasks.md`.
+- ⛔ **Stop.** Run `/nova-plan` first.
+
+## 4. all-tasks-done
+Verify tasks completed. Quick-fix exception without `tasks.md`.
+- If **tasks.md exists**: no `- [ ]` should remain.
+- ⛔ **Stop.** Run `/nova-build` first.
+
+## 5. review-approved
+Verify the review was approved.
+- `review.md` must exist with the line `✓ Ready for /nova-wrap`.
+- ⛔ **Stop.** Run `/nova-review` first.
+
+## 6. old-decision-archived
+Validate that superseded decisions are archived.
+- Files in `context/decisions/*.md` with `> Supersedes: X.md` imply that `X.md` lives in `context/decisions/archived/`, not at the root.
+- ⛔ **Stop.** Move the file to `archived/` with `git mv` and retry.

package/novaspec/skills/close-requirement/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: close-requirement
+description: Turn a vague ticket into a closed requirement with structured questions.
+---
+
+# Close requirement
+
+Transform a vague ticket into a requirement with closed decisions.
+
+## Prior context
+
+Read before asking:
+- `context/services/<service>.md`
+- 3-5 files from `context/decisions/` whose name is relevant to the ticket (never `archived/`)
+- Files from `context/gotchas/` if any are relevant
+
+## Steps
+
+### 1. Understand the ask
+
+What they want, what problem it solves, what's unclear.
+
+### 2. Clarifying questions
+
+Goal: force decisions, don't explore.
+
+- conversational tone, max 3 questions per turn
+- prefer trade-offs (A vs B) over open-ended
+- include a suggested default anchored in the code
+
+### Mandatory dimensions
+
+1. Shape of the solution
+2. Expected output
+3. Behavior (normal, edge, failure)
+4. Actor and context
+5. Scope
+6. Success criteria
+
+### 3. Iterate until closed
+
+Don't advance if there are open decisions.
+
+### 4. Confirm before drafting
+
+> "All clear. Should I draft the final requirement?"
+
+## Output
+
+Template: `novaspec/templates/proposal.md` (use it after confirmation)
+
+## Rules
+
+- Don't write code
+- Don't assume missing decisions
+- Don't draft if there are open decisions

package/novaspec/skills/jira-integration/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: jira-integration
+description: Read and create tasks in Jira via the REST API. Uses the project's config.yml (`jira` section).
+---
+
+# Jira Integration
+
+Read and create issues in Jira using Atlassian's REST API v3.
+
+## Required config in config.yml
+
+```yaml
+jira:
+  skill: jira-integration
+  url: https://your-org.atlassian.net   # no trailing slash
+  project: PROJ                          # default project key
+  email: you@email.com
+  token: ${JIRA_API_TOKEN}               # reference to env variable
+  done_transition_id: "41"               # find it via GET /rest/api/3/issue/<TICKET>/transitions
+```
+
+Get the token at: https://id.atlassian.com/manage-profile/security/api-tokens
+
+## How to use this skill
+
+When the user asks to read or create Jira tasks:
+
+1. **Read the config**: read the project's `config.yml` and extract the `jira` section.
+2. **Resolve the token**: if the value starts with `${`, read the corresponding env variable (e.g. `$JIRA_API_TOKEN`).
+3. **Build Basic Auth credentials**: `base64(email:token)`.
+4. **Call the API** with `curl` for the requested operation.
+
+## Operations
+
+### Read a ticket
+
+```bash
+curl -s \
+  -H "Authorization: Basic <BASE64>" \
+  -H "Accept: application/json" \
+  "https://<url>/rest/api/3/issue/<TICKET_KEY>"
+```
+
+Show the user: key, summary, status (status.name), description, assignee.
+
+### List tickets in a project (recent open ones)
+
+```bash
+curl -s \
+  -H "Authorization: Basic <BASE64>" \
+  -H "Accept: application/json" \
+  "https://<url>/rest/api/3/search?jql=project=<PROJECT>+AND+statusCategory!=Done+ORDER+BY+created+DESC&maxResults=20&fields=summary,status,assignee,priority"
+```
+
+### Create a ticket
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Basic <BASE64>" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  "https://<url>/rest/api/3/issue" \
+  -d '{
+    "fields": {
+      "project": { "key": "<PROJECT>" },
+      "summary": "<TITLE>",
+      "description": {
+        "type": "doc", "version": 1,
+        "content": [{"type": "paragraph", "content": [{"type": "text", "text": "<DESCRIPTION>"}]}]
+      },
+      "issuetype": { "name": "<TYPE>" }
+    }
+  }'
+```
+
+### Transition ticket to Done
+
+```bash
+AUTH=$(echo -n "<email>:<token>" | base64)
+curl -s -X POST \
+  -H "Authorization: Basic $AUTH" \
+  -H "Content-Type: application/json" \
+  "https://<url>/rest/api/3/issue/<TICKET-ID>/transitions" \
+  -d "{\"transition\": {\"id\": \"<done_transition_id>\"}}"
+```
+
+Use `done_transition_id` from `config.yml`. To find your transition IDs:
+```bash
+curl -s -H "Authorization: Basic <BASE64>" "https://<url>/rest/api/3/issue/<ANY-TICKET>/transitions"
+```
+
+## Notes
+
+- If `token` is not in config.yml, ask the user to set it.
+- If the project is not specified in the request, use the `project` from config.yml.
+- On HTTP errors (401, 403, 404), show Jira's error message but never expose the token.

package/novaspec/skills/update-service-context/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: update-service-context
+description: Update context/services/<svc>.md when service behavior changes.
+---
+
+# Update `context/services/<svc>.md`
+
+## When to update
+
+- Add/remove responsibilities
+- Modify public contracts
+- Change integrations
+- Introduce new dependencies
+- Change observable behavior
+
+**Don't** for internal changes with no external impact.
+
+## Steps
+
+### 1. Check if it exists
+
+The file lives at `context/services/<svc>.md`.
+
+If it doesn't exist, ask whether to create it (recommended).
+
+### 2. Identify changes
+
+Compare previous state vs new.
+
+### 3. Template
+
+Use this basic structure (keep the file ≤80 lines; replace, don't accumulate):
+
+```
+# <svc>
+
+## What it does
+## Public interfaces
+## Dependencies
+## Last update: YYYY-MM-DD — <ticket>
+```
+
+### 4. Propose diff
+
+```
+## Proposed changes
+- [before] ...
+- [after] ...
+```
+
+> "Apply, adjust, or cancel?"
+
+Only write after confirmation.
+
+## Rules
+
+- Don't make up responsibilities
+- If it's internal with no impact, don't update
+- Short file (≤80 lines)
+- Don't repeat decisions here; reference `context/decisions/<file>.md` if applicable

package/novaspec/skills/write-decision/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: write-decision
+description: Create a file in context/decisions/ when a real technical decision with an alternative is made.
+---
+
+# Write decision
+
+Create an atomic markdown file under `context/decisions/`. No numbering, no frontmatter, concept-name.
+
+## When to create
+
+- **Yes**: choice between real technical alternatives with trade-off, change of an established pattern, new dependency, decision another dev (or you in 6 months) should know.
+- **No**: bug fixes, cosmetic refactor, already-documented patterns, claims with no alternative explored.
+
+Default: **don't write**. Most tickets don't generate a decision.
+
+## Steps
+
+### 1. Filename
+
+`<concept-kebab-case>.md`. Examples: `symlinks-vs-copy.md`, `guardrails-per-step.md`. **Do not** use `NNNN-` numbering. The name is the index.
+
+### 2. Does it supersede a previous decision?
+
+If yes:
+- The new file starts with a line `> Supersedes: <old-file>.md`.
+- Run `git mv context/decisions/<old-file>.md context/decisions/archived/<old-file>.md`.
+
+### 3. Ask for the data
+
+> I need:
+> 1. Concept-name for the file
+> 2. Decision (one line)
+> 3. Discarded alternatives and why (brief)
+> 4. Consequences / accepted cost
+> 5. Does it supersede an existing decision? (file name)
+
+### 4. Structure
+
+```
+# <Concept title>
+
+[> Supersedes: <old-file>.md   ← only if applicable]
+
+**Date**: YYYY-MM-DD
+
+## Decision
+<one line>
+
+## Discarded alternative
+<what and why>
+
+## Why
+<the real argument>
+
+## Accepted cost
+<what we lose>
+```
+
+### 5. Confirm before saving
+
+Only write after confirmation.
+
+## Rules
+
+- Don't make up alternatives.
+- Fits on a screen or atomicity fails (split into two files).
+- One fact, one file. Never update with new info — create another file with supersede.
+- Never write directly into `context/decisions/archived/`.

package/novaspec/templates/commit.md

@@ -0,0 +1,6 @@
+<type>(<scope>): <summary>
+
+<optional body>
+
+Refs: <TICKET-ID>
+Decisions: <context/decisions/<file>.md if applicable>

package/novaspec/templates/pr-body.md

@@ -0,0 +1,20 @@
+## Ticket
+<link to Jira>
+
+## Summary
+<what changes and why>
+
+## Spec
+context/changes/archive/<ticket-id>/proposal.md
+
+## Decisions
+- context/decisions/<file>.md (if applicable)
+
+## Manual verification
+<steps from tasks.md or the spec>
+
+## Checklist
+- [x] Spec archived
+- [x] Services updated (if applicable)
+- [x] Decision created (if applicable)
+- [x] Review without blockers

package/novaspec/templates/proposal.md

@@ -0,0 +1,49 @@
+<!-- Keep this spec ≤ 60 lines. Bullets and tables, not prose. It's loaded on every nova-build turn. -->
+# <TICKET-ID>: <title>
+
+## Story
+As <actor>, I want <capability>, so that <outcome>.
+
+## Goal
+<what becomes possible>
+
+## Context
+<problem and why it matters>
+
+## Scope
+### In scope
+- <items>
+
+### Out of scope
+- <items>
+
+## Closed decisions
+- <list>
+
+## Expected behavior
+- Normal: <...>
+- Edge cases: <...>
+- Failure: <...>
+
+## Expected output
+<...>
+
+## Success criteria
+- <observables>
+
+## Architectural impact
+- Affected services: <list>
+- Referenced decisions: <list or "none">
+- Requires a new decision?: yes | no | maybe
+
+## Verification without automated tests
+### Manual flow
+1. <reproducible steps>
+
+### What to check
+- Logs: <...>
+- DB: <...>
+- API/UI: <...>
+
+## Risks
+- <risk>: <mitigation>

package/novaspec/templates/review.md

@@ -0,0 +1,22 @@
+# Review: <TICKET-ID>
+
+## Spec compliance
+- [✓/✗] <criterion>: <detail>
+
+## Conventions
+- <findings or "no issues">
+
+## Decisions
+- <conflicts or "no conflicts">
+
+## Risks
+- <risks or "none">
+
+## Blockers
+- <must be resolved before /nova-wrap>
+
+## Suggestions
+- <optional improvements>
+
+## Verdict
+✓ Ready for /nova-wrap

package/novaspec/templates/status-report.md

@@ -0,0 +1,8 @@
+## Status of ticket <TICKET-ID>
+
+Title    : <title>
+Branch   : <current git branch>
+Step     : <step>
+Progress : <N completed> / <M total> tasks  ← only if step is "do"
+Next     : <next command>
+Archived : context/changes/archive/<ticket-id>/    ← only if step is "archived"

package/novaspec/templates/tasks.md

@@ -0,0 +1,24 @@
+# Plan + tasks: <TICKET-ID>
+
+## Strategy
+<2-3 lines on how to approach the change>
+
+## Files to touch
+- `<path>`: <what changes>
+
+## New files
+- `<path>`: <what it contains>
+
+## Safety net
+- Reversibility: <feature flag | toggle | how to revert>
+- What can break: <specific>
+- Rollback plan: <steps>
+
+## Characterization tests (or verification)
+Before modifying existing code:
+- [ ] Test for <behavior> (or reproducible manual steps)
+- [ ] Test for <edge case>
+
+## Tasks (15–60 min)
+- [ ] 1. <concrete task> — <file(s)>
+- [ ] 2. <concrete task> — <file(s)>

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "nova-spec",
+  "version": "1.0.0",
+  "description": "Spec-Driven Development framework for Claude Code and OpenCode",
+  "bin": {
+    "nova-spec": "./bin/nova-spec.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "novaspec/",
+    "AGENTS.md"
+  ],
+  "scripts": {
+    "test": "echo \"No automated tests — use smoke test in CLAUDE.md\""
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Adansuku/nova-spec"
+  },
+  "keywords": [
+    "claude-code",
+    "opencode",
+    "ai-coding",
+    "spec-driven-development",
+    "jira",
+    "workflow"
+  ]
+}