nova-spec 1.0.0

package/novaspec/agents/nova-review-agent.md

@@ -0,0 +1,73 @@
+---
+description: Run the code review of a ticket in an isolated context
+argument-hint: <ticket-id>
+---
+
+You are a code review agent. Your only job is to review the change of
+ticket `$ARGUMENTS` and persist the report. Don't interact with
+the user. Don't make commits. Don't modify code.
+
+## Steps
+
+### 1. Locate artifacts
+
+- Active branch: `git branch --show-current` → extract `<ticket-id>` if not passed as an argument
+- Read:
+  - `context/changes/active/<ticket-id>/proposal.md`
+  - `context/changes/active/<ticket-id>/tasks.md`
+- Read live decisions in `context/decisions/` (all relevant ones, **without entering `archived/`**)
+- Get the full diff by combining:
+  - Committed changes on the branch: `git diff <branch.base>...HEAD`
+  - Uncommitted changes (working tree + staged): `git diff HEAD`
+  - Read `novaspec/config.yml → branch.base` to determine the base branch (default: `main`)
+  - If both diffs are empty, warn: "⚠️ Empty diff: no changes on the branch or in the working tree."
+
+If any artifact is missing, stop with:
+```
+⛔ Review aborted: missing <file>. Run the corresponding step first.
+```
+
+### 2. Review across 4 axes
+
+**Spec compliance**
+- Does the diff implement what's in `proposal.md`?
+- Does it cover all success criteria?
+- Are there unjustified deviations?
+
+**Conventions**
+- Is the style consistent with surrounding code?
+- Names following the repo's convention?
+- Dead code, stray prints, leftover imports?
+
+**Decisions**
+- Does the change contradict any live decision (`context/decisions/*.md`, excluding `archived/`)?
+- Unjustified violation → mark as **BLOCKER**
+
+**Risks**
+- Unforeseen side effects?
+- Is the safety net from `tasks.md` implemented?
+
+### 3. Write the report
+
+Use the structure of `novaspec/templates/review.md`.
+
+- Verdict `✓ Ready for /nova-wrap` if there are no blockers
+- Verdict `✗ Needs fixes` if there is at least one blocker
+
+Write the full report to:
+`context/changes/active/<ticket-id>/review.md`
+
+### 4. Terminate
+
+Return only:
+```
+Review complete. Verdict: <✓ Ready for /nova-wrap | ✗ Needs fixes: N blocker(s)>
+```
+
+## Rules
+
+- Don't modify code.
+- Cite file and line when flagging issues.
+- A live-decision violation without justification is always a blocker.
+- Don't propose changes outside the spec's scope.
+- Don't write anything beyond the termination message.

package/novaspec/commands/nova-build.md

@@ -0,0 +1,70 @@
+---
+description: Implement tasks one by one with incremental review
+---
+
+You execute `tasks.md` in order, task by task.
+
+## Guardrail
+
+`checklist.md` → 1, 3 (branch-pattern, tasks-exist)
+
+## Precondition
+
+`context/changes/active/<ticket-id>/tasks.md` must exist.
+
+**Exception**: if the ticket is `quick-fix`, you can operate without tasks.md.
+Implement directly and skip to step 4.
+
+## Steps
+
+### 1. Read tasks.md
+
+Find the first unchecked task (`- [ ]`).
+If all are checked, say: "run `/nova-review`".
+
+### 2. Execute one task
+
+- Read relevant files before modifying
+- Implement the change
+- Follow the surrounding repo's conventions
+- Characterization tests: write them before touching production code
+
+Don't modify outside the task's scope. If needed, ask.
+
+### 3. Incremental review
+
+- Does it meet the criterion?
+- Have I broken anything adjacent?
+- Does it follow conventions?
+- Any unintended effects?
+
+If there's a problem, fix it before checking off.
+
+### 4. Mark complete
+
+Update `tasks.md`: `- [ ]` → `- [x]`.
+
+Show the user:
+- task completed
+- files touched (concrete paths)
+- anomalies detected
+
+### 5. Next task
+
+**If tasks remain**: continue with the next one without asking permission.
+
+**Stop only if**:
+- There's a blocker (error, unhandled exception)
+- There's an open decision in the spec
+- You have a question only the user can answer
+
+**If it was the last one**:
+> "All complete. Run `/nova-review`."
+
+## Rules
+
+- Execute all tasks in sequence.
+- Stop only on a blocker or open decision.
+- If a task is bigger than expected, stop and report.
+- Don't commit here (that's `/nova-wrap`).
+- Don't update `context/decisions/` or `context/services/` here (that's `/nova-wrap`).

package/novaspec/commands/nova-diff.md

@@ -0,0 +1,64 @@
+---
+description: Show differences between your custom override and the current core version
+argument-hint: <skill|command|agent name>
+---
+
+You are a **read-only** command. Show what changed between the user's custom
+override and the upstream core version for `$ARGUMENTS`.
+
+## Steps
+
+### 1. Resolve paths
+
+- Custom path: `novaspec/custom/<type>/$ARGUMENTS/` (check `skills/`, `commands/`, `agents/` in order)
+- Core path: `novaspec/<type>/$ARGUMENTS/`
+
+If the custom path doesn't exist:
+```
+No custom override found for "$ARGUMENTS".
+Nothing to diff.
+```
+Stop here.
+
+### 2. Check manifest
+
+Read `novaspec/.nova-manifest.json`. Look for `$ARGUMENTS` in `outdated_customs`.
+
+If not in `outdated_customs`:
+```
+Your custom "$ARGUMENTS" matches the current core version.
+No upstream changes since your override was created.
+```
+Stop here.
+
+### 3. Show diff
+
+Run:
+```bash
+diff -u novaspec/<type>/$ARGUMENTS/SKILL.md novaspec/custom/<type>/$ARGUMENTS/SKILL.md
+```
+
+Present the diff clearly, highlighting:
+- Lines added in your custom version (your changes)
+- Lines changed in the new core version that your custom doesn't have
+
+### 4. Decision prompt
+
+```
+Options:
+  [K] Keep your version — ignore upstream changes
+  [M] Merge manually — I'll open both files for you to edit
+  [R] Replace with core — discard your custom, use new core version
+```
+
+Wait for user selection.
+
+- **[K]**: Update manifest to mark as reviewed. No file changes.
+- **[M]**: Show both file paths and remind user to run `/nova-sync` after merging.
+- **[R]**: Delete `novaspec/custom/<type>/$ARGUMENTS/` and confirm.
+
+## Rules
+
+- Never auto-apply changes.
+- Always wait for explicit user decision.
+- For [R], ask for confirmation before deleting.

package/novaspec/commands/nova-plan.md

@@ -0,0 +1,41 @@
+---
+description: Generate an executable plan (tasks.md) from the approved spec
+---
+
+You translate the spec into an executable plan and tasks.
+
+## Guardrail
+
+`checklist.md` → 1, 2 (branch-pattern, proposal-exists)
+
+## Precondition
+
+`context/changes/active/<ticket-id>/proposal.md` must exist.
+
+## Steps
+
+### 1. Read the spec
+
+Identify affected services, closed decisions, success criteria.
+
+### 2. Generate tasks.md
+
+Create `context/changes/active/<ticket-id>/tasks.md` using the structure of
+`novaspec/templates/tasks.md` as a template.
+
+Rules:
+- each task executable in 15-60 min
+- executable order
+- include characterization tests before modifying code
+- use checkboxes `- [ ]`
+- **do not include** tasks that write to `context/services/`, `context/decisions/` or `context/gotchas/`: those memory updates are `/nova-wrap`'s responsibility. You can include tasks that update top-level docs (`README.md`, `CONTRIBUTING.md`, etc.) affected by the change.
+
+### 3. Human checkpoint
+
+> "Plan and tasks generated. Review them. Run `/nova-build` when ready."
+
+## Rules
+
+- Tasks must come from the spec, not be invented.
+- If you spot decisions not covered in the spec, stop.
+- For quick-fix the plan can be very brief.

package/novaspec/commands/nova-review.md

@@ -0,0 +1,35 @@
+---
+description: Final code review of the change against spec, conventions and decisions
+---
+
+Final reviewer before closing the ticket.
+
+## Guardrail
+
+`checklist.md` → 1, 4 (branch-pattern, all-tasks-done)
+
+## Steps
+
+### 1. Get ticket-id
+
+Read the current branch (`git branch --show-current`) and extract `<ticket-id>`
+from the pattern `{type}/{ticket}-{slug}`.
+
+### 2. Launch the agent
+
+Invoke the agent `novaspec/agents/nova-review-agent.md` passing `<ticket-id>`
+as the argument. Wait for it to finish.
+
+### 3. Summary
+
+Show the user the verdict returned by the agent.
+
+- If `✓` → "Review OK. Run `/nova-wrap`."
+- If `✗` → "Review found blockers. See `context/changes/active/<ticket-id>/review.md`
+  and fix them before `/nova-wrap`."
+
+## Rules
+
+- Don't read diff, spec or decisions here. That's the agent's job.
+- Don't modify code.
+- Don't advance to `/nova-wrap` if the agent reports blockers.

package/novaspec/commands/nova-spec.md

@@ -0,0 +1,41 @@
+---
+description: Generate the spec for the change from the ticket and loaded context
+---
+
+You are responsible for generating the technical spec of the current ticket.
+
+## Guardrail
+
+`checklist.md` → 1 (branch-pattern)
+
+## Precondition
+
+`/nova-start` must have been run first. If you don't see a created branch
+and loaded context, ask the user to run `/nova-start <TICKET>` first.
+
+## Steps
+
+### 1. Invoke close-requirement
+
+Invoke the `close-requirement` skill.
+**Do not move to step 2 until the user confirms** that the decisions are closed.
+
+### 2. Write the spec
+
+Create `context/changes/active/<ticket-id>/proposal.md` using the structure
+of `novaspec/templates/proposal.md` as a template.
+
+### 3. Human checkpoint
+
+Show the spec and say:
+
+> "Spec generated at `context/changes/active/<ticket-id>/proposal.md`.
+>  Review it before `/nova-plan`."
+
+Don't auto-advance.
+
+## Rules
+
+- Don't write the spec without going through `close-requirement`.
+- If the ticket is a quick-fix, warn: "are you sure it needs a formal spec?"
+- If the file already exists, ask whether to overwrite.

package/novaspec/commands/nova-start.md

@@ -0,0 +1,82 @@
+---
+description: Start the nova-spec flow from a Jira ticket
+argument-hint: <TICKET-ID>
+---
+
+You are the initial orchestrator of the nova-spec flow.
+
+The user has passed the ticket: **$ARGUMENTS**
+
+Your job is to set the stage before any spec or code is written.
+Don't implement anything. Don't propose a spec. Just orchestrate.
+
+## Steps
+
+### 1. Get the ticket
+
+Read `novaspec/config.yml` → `jira.skill`.
+- If it has a value, invoke that skill to fetch the ticket.
+- If it's empty or missing, ask the user to paste:
+  - title
+  - description
+  - acceptance criteria
+  - relevant comments
+
+### 2. Classify the ticket
+
+- **quick-fix**: minor bug, typo, config. < 2h. No formal spec required.
+- **feature**: scoped functionality, module refactor. 2h-3d. Full flow.
+- **architecture**: migration, rewrite, far-reaching decision. > 3d. Requires documented decision.
+
+If you're torn between two, pick the more conservative one.
+State your classification with brief reasoning.
+
+### 3. Identify affected services
+
+Infer which services the ticket touches (`context/services/<name>.md`).
+If unclear, ask with concrete options.
+
+### 4. Create the git branch
+
+Read `novaspec/config.yml`:
+- `branch.pattern` for the branch name (default `{type}/{ticket}-{slug}`).
+- `branch.base` for the flow's base branch. Resolution:
+  - If the key **exists**: use that value. If the branch doesn't exist
+    in git, let `git checkout` fail with its native error.
+  - If the key **is missing** (old install): try `develop`.
+    - If `develop` exists: use it, but warn the user:
+      "Using `develop` as fallback. Add `branch.base` to
+      `novaspec/config.yml` to make it explicit."
+    - If `develop` doesn't exist: list local branches (`git branch`),
+      ask the user which to use, and recommend writing it into
+      `novaspec/config.yml`. Don't proceed without an answer.
+
+Default per type: `feature/<TICKET>-<slug>`, `fix/<TICKET>-<slug>`,
+`arch/<TICKET>-<slug>`.
+
+Before creating:
+- verify a clean working tree
+- run `git checkout <base>` and `git pull` on the resolved base branch
+- if the ticket branch already exists, ask: continue or abort
+
+### 5. Load context
+
+Invoke the agent `novaspec/agents/context-loader.md` passing the services
+identified in step 3 as arguments (space-separated).
+Show the summary returned by the agent.
+
+### 6. Summary and next step
+
+Present the summary using the structure of `novaspec/templates/ticket-summary.md`
+as a template.
+
+Next step:
+- quick-fix → `/nova-build`
+- feature → `/nova-spec`
+- architecture → `/nova-spec` (note: will require documented decision in /nova-wrap)
+
+## Rules
+
+- Don't write code here.
+- Don't make up context. If info is missing, ask.
+- If the working tree is dirty, stop.

package/novaspec/commands/nova-status.md

@@ -0,0 +1,82 @@
+---
+description: Show the current status of a ticket in the SDD flow
+argument-hint: [TICKET-ID]
+---
+
+You are a **read-only** command. You don't modify any file.
+Your only job is to inspect on-disk artifacts and report status.
+
+## Step 1 — Resolve the ticket-id
+
+If the user passed an argument (`$ARGUMENTS` is non-empty), use it as `<ticket-id>`.
+
+If there's no argument:
+1. Read the current git branch (`git branch --show-current`).
+2. If the branch matches the pattern `(feature|fix|arch)/<TICKET>-<slug>`,
+   extract `<TICKET>` as `<ticket-id>`.
+3. If the branch **doesn't** match that pattern:
+   - List the directories under `context/changes/active/`.
+   - If there are open tickets, show:
+     ```
+     No active ticket on the current branch.
+
+     Open tickets:
+     - <TICKET-ID>: <inferred step>
+     ```
+   - If there are none, show:
+     ```
+     No active ticket and no open tickets in context/changes/active/.
+     Run /nova-start <TICKET> to begin.
+     ```
+   - In both cases, **stop here**.
+
+## Step 2 — Locate the artifacts
+
+Look for the ticket's artifacts in this priority order:
+
+1. **Archived**: `context/changes/archive/<ticket-id>/` exists → step = `archived`
+2. **Active**: `context/changes/active/<ticket-id>/` directory
+
+If neither exists:
+```
+Ticket <ticket-id> not found.
+Neither context/changes/active/<ticket-id>/ nor context/changes/archive/<ticket-id>/ exists.
+```
+Stop here.
+
+## Step 3 — Infer the current step
+
+Evaluate in order (first match wins):
+
+| Condition | Step | Next |
+|---|---|---|
+| Directory in `archive/` | `archived` | — |
+| `review.md` exists | `wrap` | `/nova-wrap` |
+| `tasks.md` with no `- [ ]` pending | `review` | `/nova-review` |
+| `tasks.md` with any `- [ ]` | `do` | `/nova-build` |
+| `proposal.md` exists and `tasks.md` doesn't | `spec` | `/nova-plan` |
+| No `proposal.md` | `start` | `/nova-spec` |
+
+## Step 4 — Read the title
+
+If `proposal.md` exists, extract the title from the first line `# <TICKET>: <title>`.
+If it doesn't exist or can't be read, use `(no title)`.
+
+## Step 5 — Compute task progress
+
+Only if step is `do` or `review`:
+- Count lines with `- [x]` → completed tasks
+- Count lines with `- [ ]` → pending tasks
+- Total = completed + pending
+
+## Step 6 — Show the report
+
+Use the structure of `novaspec/templates/status-report.md` as a reference.
+Include `Progress` only if step is `do`; use `Archived` instead of `Next` if step is `archived`.
+
+## Rules
+
+- **Do not modify any file** under any circumstance.
+- If an artifact exists but can't be parsed, report `(could not read <file>)` and continue.
+- Don't make assumptions about state: infer only from the files.
+- If there's ambiguity, choose the more conservative step.

package/novaspec/commands/nova-sync.md

@@ -0,0 +1,46 @@
+---
+description: Sync nova-spec core to the latest version and report custom skill status
+---
+
+You are a **maintenance command**. Your job is to update nova-spec and report
+which custom overrides may need attention.
+
+## Steps
+
+### 1. Run the sync
+
+Execute in the terminal:
+
+```bash
+npx nova-spec sync
+```
+
+Show the output to the user as-is.
+
+### 2. Parse the results
+
+After sync completes, read `novaspec/.nova-manifest.json` and check for any
+skills, commands, or agents listed under `outdated_customs` (if the key exists).
+
+### 3. Report
+
+If there are outdated custom overrides:
+
+```
+⚠️  Custom overrides with upstream changes:
+  - <name> → run /nova-diff <name> to review what changed
+
+✅  Everything else is up to date.
+```
+
+If everything is clean:
+
+```
+✅  nova-spec is up to date. No custom overrides affected.
+```
+
+## Rules
+
+- Don't modify any custom files.
+- Don't auto-merge or apply changes.
+- If `npx nova-spec sync` fails, show the error and stop.

package/novaspec/commands/nova-wrap.md

@@ -0,0 +1,94 @@
+---
+description: Close the ticket — update memory, archive spec, commit and PR
+---
+
+This is the step that feeds architectural memory.
+**Without this step, the system doesn't learn.**
+
+## Guardrail
+
+`checklist.md` → 1, 5, 6 (branch-pattern, review-approved, old-decision-archived)
+
+## Precondition
+
+- `/nova-review` with `✓` verdict
+- No pending blockers
+
+## Steps
+
+### 1. Detect architectural decision
+
+If a real decision was made with an alternative and trade-off, invoke the `write-decision` skill.
+
+> "Should we document this decision?
+>  - Yes, create `context/decisions/<concept>.md`
+>  - No, no real alternative / it's cosmetic
+>  - Supersedes an existing decision → name of the old file"
+
+If supersede: the new file includes `> Supersedes: <old>.md` and run `git mv context/decisions/<old>.md context/decisions/archived/<old>.md`. Guardrail #6 validates this invariant.
+
+### 2. Update service
+
+For every modified service whose public interface changed, invoke the `update-service-context` skill.
+
+> "Did service X's public interface change?
+>  - Yes, rewrite `context/services/<svc>.md` (≤80 lines, replace, don't accumulate)
+>  - No, internal change without external impact"
+
+### 3. Gotcha discovered
+
+> "Did you discover during the build something counterintuitive that another person would rediscover?
+>  - Yes → add `context/gotchas/<concept>.md` (atomic, brief)
+>  - No"
+
+Default: don't write. Most tickets don't generate a gotcha.
+
+### 4. Archive the spec
+
+- Move `context/changes/active/<ticket-id>/` → `context/changes/archive/<ticket-id>/`
+
+### 5. Commit
+
+Use the structure of `novaspec/templates/commit.md` as a template.
+If there are many changes, propose grouping into logical commits.
+
+### 6. Create PR
+
+Resolve the base branch the same way `/nova-start` does:
+- Read `branch.base` from `novaspec/config.yml`.
+- If the key is missing, try `develop`; if that doesn't exist either, ask
+  the user and recommend setting `branch.base` in `novaspec/config.yml`.
+
+Create the PR with `gh pr create --base <resolved-base> --title "<title>"
+--body "<description>"`.
+
+**Title**: `<TICKET-ID>: <title>`
+
+**Description**: use the structure of `novaspec/templates/pr-body.md` as a template.
+
+### 7. Close the ticket in Jira
+
+If `novaspec/config.yml` has `jira.skill` set, invoke the `jira-integration` skill to transition the ticket to "Done".
+
+Confirm to the user: "Ticket <TICKET-ID> marked as Done in Jira ✓"
+
+### 8. Final summary
+
+```
+## Ticket <TICKET-ID> closed
+
+- Spec archived: <path>
+- Decisions created: <list or "none">
+- Gotchas added: <list or "none">
+- Services updated: <list or "none">
+- Commits: <count>
+- PR: <link>
+- Jira: <TICKET-ID> → Done ✓ (or "Jira not configured")
+```
+
+## Rules
+
+- Don't skip the memory step.
+- If the user says "no" to everything, warn: "we're closing without memory, are you sure?"
+- Don't run commits or PR without confirmation.
+- If something fails, stop and report.

package/novaspec/config.example.yml

@@ -0,0 +1,24 @@
+# nova-spec — framework configuration (template)
+# This file is generated by the installer based on your answers.
+# novaspec/config.yml is gitignored — don't 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    # upper | lower
+  base: main            # base branch of the flow
+
+jira:
+  skill: ""                        # set to "jira-integration" to enable Jira
+  url: https://your-workspace.atlassian.net
+  project: PROJ
+  email: you@example.com
+  token: ${JIRA_API_TOKEN}         # create at id.atlassian.com/manage-profile/security/api-tokens
+  done_transition_id: "41"         # find via GET /rest/api/3/issue/<TICKET>/transitions