@novare-technologies/nvaid 0.0.0-stage → 0.2.0

package/templates/commands/apply.md

@@ -0,0 +1,36 @@
+---
+command: nvaid:apply
+summary: Generate per-repo unit design docs and open construction branches for an approved breakdown.
+stage: "Fig. 2 Stage 4+ — Per-Role Authoring / Construction"
+precondition: unit-breakdown approved (Decomposition-Approved gate green)
+---
+
+# /nvaid:apply
+
+## ⛔ Precondition: nvaid install must be complete
+
+Read `nvaid/config.yml` and check the `install:` block. If `config`, `project_rules`, or
+`design_code_dictionary` is not `true` (or the file is missing), **STOP** and tell the
+user to run `/nvaid:install` first — name which flag(s) are false. Do not proceed until
+all three are true.
+
+
+Turn an **approved** unit-breakdown into construction-ready work: for each Unit, generate
+its design doc in the Owning Repo named by the breakdown, and open the construction branch
+per the `github` Skill.
+
+## Precondition
+
+Only run once the unit-breakdown is approved. If it's still awaiting the gate, stop.
+
+## Steps
+
+1. Read the approved `unit-breakdown.md` and its Units + Owning Repo tags.
+2. For each Unit, in its Owning Repo:
+   - generate `nvaid/intents/<INTENT-ID>-<slug>/units/<UNIT-ID>-design.md` with the Unit's
+     own Acceptance Criteria, referencing the relevant contracts (`covers_units`).
+   - cut the construction branch (`feature/<story-id>-<slug>` or `bugfix/...`) per the
+     `github` Skill.
+3. Create/update the GitHub Project items per `ISSUE-TRACKER-TEMPLATE.md` (Epic per Intent,
+   Story/Bug per Unit) — links, not pasted content.
+4. Hand off to Construction. Do not implement code here.

package/templates/commands/breakdown.md

@@ -0,0 +1,35 @@
+---
+command: nvaid:breakdown
+summary: Cut an approved Intent into Units of Work — the Phase 5 final cut, each unit tagged with its Owning Repo.
+stage: "Mob Elaboration — Phase 5"
+precondition: Contracts drafted (/nvaid:contracts has run)
+---
+
+# /nvaid:breakdown
+
+## ⛔ Precondition: nvaid install must be complete
+
+Read `nvaid/config.yml` and check the `install:` block. If `config`, `project_rules`, or
+`design_code_dictionary` is not `true` (or the file is missing), **STOP** and tell the
+user to run `/nvaid:install` first — name which flag(s) are false. Do not proceed until
+all three are true.
+
+
+Produce `unit-breakdown.md` — the **Phase 5 output**, the decomposition of record,
+informed by the contracts from `/nvaid:contracts`. This runs **after** contracts, not
+before (the `unit-breakdown` Skill is Phase 5; the contract Skills are Phases 2–5).
+
+## Steps
+
+1. Read `intent.md` and the drafted `contracts/`.
+2. Run the `unit-breakdown` Skill per `{{AIDLC_ROOT}}/unit-breakdown-rules.md`: cut into
+   Units each with its own Acceptance Criteria, classify Story or Bug, size per the rules.
+3. Tag each Unit with its **Owning Repo** (frontend | backend | platform) — this is what
+   assigns units across the family (proposal §7).
+4. Reconcile each contract's `covers_units` against the final cut.
+5. Write `nvaid/intents/<INTENT-ID>-<slug>/unit-breakdown.md`. Flag as a draft awaiting
+   room critique (Phases 3–4) and the Decomposition-Approved gate.
+
+## Next
+
+`/nvaid:apply` — generate the per-repo unit design docs and open construction branches.

package/templates/commands/contracts.md

@@ -0,0 +1,43 @@
+---
+command: nvaid:contracts
+summary: Draft the per-role Architecture Contracts for an approved Intent (Phases 2–5).
+stage: "Mob Elaboration — Phases 2–5"
+precondition: Intent approved (Decomposition-Approved gate green)
+---
+
+# /nvaid:contracts
+
+## ⛔ Precondition: nvaid install must be complete
+
+Read `nvaid/config.yml` and check the `install:` block. If `config`, `project_rules`, or
+`design_code_dictionary` is not `true` (or the file is missing), **STOP** and tell the
+user to run `/nvaid:install` first — name which flag(s) are false. Do not proceed until
+all three are true.
+
+
+Draft the Architecture Contracts for an **already-approved** Intent, running each role's
+contract Skill. The contracts are negotiated across Elaboration Phases 2–5 and **precede**
+the unit-breakdown (which is the Phase 5 output) — run `/nvaid:breakdown` after this.
+
+## Precondition
+
+Only run once the Intent is approved. If `intent.md` is still a draft awaiting the
+stakeholder, stop and say so.
+
+## Steps
+
+1. Read the approved `intent.md`.
+2. Run each required role Skill per its `*-architecture-contract-generation-rules.md`
+   under `{{AIDLC_ROOT}}`: solutions, the relevant tier contract(s) (frontend / backend),
+   quality, customer-experience. Pull a role in only if the Intent touches its domain;
+   state "not pulled in" explicitly for the rest.
+3. Write each to `nvaid/intents/<INTENT-ID>-<slug>/contracts/`.
+4. Each contract is a **draft awaiting its Architect's sign-off** — never present as final.
+   Read the architect roster from `nvaid/config.yml` (`architects.<role>`) and flag each
+   contract as "awaiting sign-off from <that named architect>". Never fill in a sign-off
+   on an architect's behalf (propose, don't dispose). If a role has no named architect in
+   config, state that its contract is not pulled in rather than inventing an owner.
+
+## Next
+
+`/nvaid:breakdown` — cut the approved Intent into Units, informed by these contracts.

package/templates/commands/install.md

@@ -0,0 +1,63 @@
+---
+command: nvaid:install
+summary: Scan the project and fill in the three required nvaid documents (config.yml, PROJECT-RULES.md, DESIGN-CODE-DICTIONARY.md). Must run before /nvaid:intent.
+stage: "nvaid onboarding — run once, first, before any workflow command"
+blocks: [nvaid:intent, nvaid:contracts, nvaid:breakdown, nvaid:apply]
+---
+
+# /nvaid:install
+
+The **first** command to run after `nvaid init`. `init` only drops empty templates; this
+skill makes nvaid actually usable by scanning the project and authoring the three required
+documents. **Every other nvaid workflow command is blocked until this completes** — running
+`/nvaid:intent` against unfilled templates would produce hollow, confidently-wrong output.
+
+## Why this is a skill, not a CLI step
+
+The CLI can detect facts (languages, frameworks from manifest files) but cannot author
+*judgment*: a project's guardrails, its design patterns, what breaks if a given module
+changes. That requires reading the actual code and reasoning about it — the agent's job,
+not a file-scan's. This skill does that reading. A human reviews before it's marked done
+(propose, don't dispose).
+
+## Steps
+
+1. **Scan the project.** Read manifest files (`package.json`, `pyproject.toml`, `go.mod`,
+   lockfiles), the directory structure, config, CI workflows, and a representative sample
+   of source to understand the stack, the architecture, and the conventions in use.
+
+2. **Fill `nvaid/config.yml`** — replace every `<placeholder>`:
+   - `project_name`, `owning_repo` (frontend | backend | platform | other — infer from the
+     code, confirm with the user if ambiguous).
+   - `tech_stack` — fill from what you actually found in the manifests, not assumptions.
+   - `architects` — these are sign-off identities you cannot infer from code. **Ask the
+     user** for the names; leave a role blank only if the user confirms it doesn't apply.
+   - `context` — the short, always-on constraints worth repeating to every agent.
+
+3. **Author `nvaid/PROJECT-RULES.md`** — replace the template skeleton with real content:
+   the approved stack and what's disallowed without an ADR, non-negotiable constraints,
+   data rules, coding standards, the quality gates CI actually runs, and known gaps.
+   Derive what you can from the code (e.g. the lint/test config that exists); for anything
+   that is a *decision* rather than a fact (what's allowed, what's off-limits), propose it
+   and flag it for the user to confirm — do not invent a guardrail the project hasn't made.
+
+4. **Author `nvaid/DESIGN-CODE-DICTIONARY.md`** — the technical README for the code:
+   the design patterns and conventions in use (with real file examples), and the component
+   map (concept → where it lives → what it depends on → what breaks if changed). This is
+   narrative derived from reading the code; §1 references `config.yml`'s `tech_stack`
+   rather than repeating it. Be honest in the "not yet mapped" section about coverage.
+
+5. **Human review.** Present all three for review. Per propose-don't-dispose, you draft;
+   a human confirms. Do not self-approve.
+
+6. **Flip the gate.** Only after the user confirms each document is genuinely filled (not
+   placeholder text), set the matching flag in `config.yml`'s `install:` block to `true`:
+   `config`, `project_rules`, `design_code_dictionary`. When all three are true, the
+   workflow commands unblock.
+
+## Boundaries
+
+- Facts come from the code; **decisions and sign-off identities come from the user** — ask,
+  don't fabricate.
+- Never set an `install:` flag to `true` on a document that still contains template
+  `<placeholder>` text or that the user hasn't confirmed.

package/templates/commands/intent.md

@@ -0,0 +1,46 @@
+---
+command: nvaid:intent
+summary: Draft an Intent (intent.md) — the business need and success criteria only, then STOP.
+stage: "Fig. 2 Stage 1 — Intent captured, pre-Elaboration"
+---
+
+# /nvaid:intent
+
+## ⛔ Precondition: nvaid install must be complete
+
+Before doing anything, read `nvaid/config.yml` and check the `install:` block. If
+`config`, `project_rules`, or `design_code_dictionary` is **not** `true` — or
+`nvaid/config.yml` doesn't exist — **STOP** and tell the user:
+
+> nvaid isn't fully installed in this project yet. Run `/nvaid:install` first — it scans
+> the project and fills in config.yml, PROJECT-RULES.md, and DESIGN-CODE-DICTIONARY.md.
+> Those documents are what this command relies on; drafting an Intent without them would
+> produce hollow output.
+
+Name which flag(s) are false. Do not proceed with any step below until all three are true.
+
+---
+
+Draft a new Intent from the user's description. Produce **only** `intent.md` — the
+business need, who it's for, success criteria, and scope boundaries — then **stop**.
+
+## Hard rule: generate the intent and nothing else
+
+Do NOT generate contracts, a unit-breakdown, or any downstream artifact. The Intent must
+be approved by the stakeholder (the Decomposition-Approved green light) before anything
+downstream is generated. Stopping here is the whole point of the gated workflow, not a
+limitation — propose, don't dispose.
+
+## Steps
+
+1. Read this repo's `nvaid/PROJECT-RULES.md` for the project's operating guardrails and
+   approved stack (guaranteed authored, since the install gate above has passed).
+2. Write `nvaid/intents/<INTENT-ID>-<slug>/intent.md`: business need, who it's for,
+   Intent-level success criteria (observable outcomes, not implementation), scope
+   boundaries (name what's out of scope, don't silently drop it), and open questions for
+   the room. Do not decide the technical shape here.
+3. Flag the file as a draft awaiting stakeholder approval. Stop.
+
+## Next (do not run automatically)
+
+After the stakeholder approves: `/nvaid:contracts`, then `/nvaid:breakdown`.

package/templates/nvaid/DESIGN-CODE-DICTIONARY.md

@@ -0,0 +1,90 @@
+---
+document: Design-Code Dictionary
+project: "{{PROJECT_NAME}}"
+version: 0.1.0
+owner: "<owner name>"
+maintained_by: AI agent — updated as part of any unit of work that touches a mapped component
+last_updated: "<YYYY-MM-DD>"
+status: draft
+---
+
+# {{PROJECT_NAME}} — Design-Code Dictionary
+
+> **Template dropped by `nvaid init` — HAND-OWNED, fill this in.**
+> `nvaid update` never overwrites this file. Delete these template notes once you have
+> real content.
+
+**What this file is:** a *technical README for the code* — the specs and design patterns
+of this repository, and a live map from each named concept (a feature, a module, an
+architectural component) to where it actually lives in the codebase and what else touches
+it. It answers two questions without opening the source: **"where does this live?"** and
+**"what breaks if I change it?"**
+
+**What this file is not:**
+
+- Not a replacement for reading the code when making a change — it is a navigation aid for
+  deciding whether a change is safe and who should review it.
+- Not a product spec. `nvaid/PROJECT-RULES.md` says what to build and how; this file says
+  where that intent actually landed, after the fact.
+- Not a promise of completeness. §5 exists so this file can honestly state what it has not
+  mapped yet, rather than implying coverage it doesn't have.
+
+**Keep it current.** Updating this file for every component a change adds, moves, or
+removes is part of the Definition of Done — a stale map is worse than none, because it is
+trusted and wrong.
+
+---
+
+## 1. Tech stack & toolchain
+
+The authoritative, structured stack lives in **`nvaid/config.yml` → `tech_stack`** (that is
+what agents and the CLI read). Don't duplicate it here — instead, add the *narrative* this
+file is for: why each major choice was made, how the pieces fit together, and any
+non-obvious interactions or constraints a contributor should know before changing them.
+
+<e.g. "React + Vite for the SPA; Vitest chosen over Jest for ESM-native speed. The build
+emits a static bundle served by nginx — see §2 and the Dockerfile. No SSR.">
+
+
+## 2. Project structure
+
+<A short orientation to the top-level directories — what each is for. Example:>
+
+```
+src/
+  <area>/        <one line: what lives here>
+  <area>/
+test/
+```
+
+## 3. Design patterns & conventions
+
+<The patterns a contributor (human or agent) must follow to stay consistent with the
+codebase. Be specific — these are the rules an agent can't infer from a single file.
+Examples:>
+
+- **<Pattern name>** — <what it is, when to use it, where an example lives>.
+- **State / data flow** — <how state is managed and data moves>.
+- **Error handling** — <the project's convention>.
+- **Naming** — <files, modules, symbols>.
+
+## 4. Component map (design concept → code)
+
+| Concept / feature | Lives in | Depends on | Changing it affects |
+|---|---|---|---|
+| <e.g. Auth session> | `src/auth/session.ts` | <modules> | <what breaks> |
+| | | | |
+
+## 5. Not yet mapped
+
+<List components or areas that exist in the code but aren't documented above yet, so this
+file is honest about its coverage. Keep this section — an empty "not yet mapped" is a
+claim of full coverage, and should only be empty when that's actually true.>
+
+- <none yet — fill the map as the code grows>
+
+## 6. Change log
+
+| Version | Date | Change | Author |
+|---|---|---|---|
+| 0.1.0 | <YYYY-MM-DD> | Initial draft from the nvaid template | <name> |

package/templates/nvaid/PROJECT-RULES.md

@@ -0,0 +1,93 @@
+---
+document: Project Standards & Engineering Rules
+project: "<project name>"
+version: 0.1.0
+owner: "<owner name>"
+last_updated: "<YYYY-MM-DD>"
+status: draft
+---
+
+# <project> — Project Standards & Engineering Rules
+
+> **Template dropped by `nvaid init` — HAND-OWNED, fill this in.**
+> `nvaid update` never overwrites this file. It is intentionally project-specific:
+> nvaid ships the universal skills and contract/unit rules, but *this* file is where a
+> developer records what is unique to this repo — the approved stack, the guardrails, the
+> data rules. Delete these template notes once you have real content.
+
+## 1. What this project is
+
+<One short paragraph: the objective, this phase's scope, explicit non-goals. The "why"
+an agent needs in the same file as the "how".>
+
+## 2. Architecture principles & constraints
+
+### 2.1 Approved technology stack
+
+| Layer | Approved | Disallowed without an ADR |
+|---|---|---|
+| <e.g. Backend> | <language/framework> | <what's off-limits> |
+| <e.g. Frontend> | <framework> | <what's off-limits> |
+| <e.g. Data store> | <engine> | <what's off-limits> |
+
+### 2.2 Non-negotiable constraints
+
+- <e.g. deployment target, network posture, build output format — things an agent must
+  not quietly change.>
+
+### 2.3 Architecture Decision Records (ADRs)
+
+<Where ADRs live and the rule to check them before proposing a change in an area one
+already covers.>
+
+## 3. Data rules
+
+- <How tenant/user/domain data is handled; what the project's own data is vs. isn't;
+  secret-handling discipline.>
+
+## 4. Design & coding standards
+
+- Follow the existing file/module layout; flag any new structural pattern.
+- Documentation bar (docstrings, module responsibilities) applies to AI-generated code
+  the same as human-authored.
+- Linter/formatter config: <link once established>.
+
+## 5. Quality & testing rules
+
+### 5.1 Definition of Done (per Unit of Work)
+
+- [ ] The Unit's stated Acceptance Criteria are met and each traces to a covering test.
+- [ ] Static analysis / security scan passes with no unresolved High findings.
+- [ ] Merge approved by the owning reviewer on gate evidence.
+- [ ] `nvaid/DESIGN-CODE-DICTIONARY.md` updated for every component added/moved/removed.
+
+### 5.2 Quality gates (CI gates that must pass before merge)
+
+<List the gates CI enforces for this project — build, unit test, coverage floor,
+code quality, security scan, etc. Keep project-wide gates here; per-Intent gates come
+from each Quality Architecture Contract.>
+
+## 6. Known gaps (do not silently resolve)
+
+- <Open questions the agent must treat as questions, not assumptions to fill in.>
+
+## 7. AI operating rules (guardrails, not suggestions)
+
+1. **Propose, don't dispose.** A named human approves before anything is merged or
+   treated as final. Never approve your own gate.
+2. **Ask before assuming.** Ambiguity → a clarifying question, not a best-guess fill-in.
+3. **Respect existing decisions.** Conflict with an ADR or an approved design → flag it,
+   don't quietly resolve it.
+4. **No unreviewed new dependencies.**
+5. **No destructive/irreversible actions without explicit per-action confirmation.**
+6. **Artifact hygiene is part of the task** — code without the matching `nvaid/` artifact
+   update is an incomplete task.
+7. **Identify AI-assisted changes** in commits and PRs.
+
+<Extend with project-specific guardrails.>
+
+## 8. Change log
+
+| Version | Date | Change | Author |
+|---|---|---|---|
+| 0.1.0 | <YYYY-MM-DD> | Initial draft from the nvaid template | <name> |

package/templates/nvaid/config.yml

@@ -0,0 +1,87 @@
+# nvaid project config — HAND-OWNED. `nvaid update` never overwrites this file.
+#
+# This is the one place a repo declares who and what it is in the AI-DLC workflow:
+#   - which coding agents nvaid targets here,
+#   - what tier/role this repo plays,
+#   - the full tech stack of the project,
+#   - who the named architects are that sign off on each contract,
+#   - the always-on project context every agent should carry.
+#
+# Written by `nvaid init`, then yours to maintain. The skills and slash commands read
+# this file to know, for example, who a drafted contract is "awaiting sign-off" from.
+
+schema: nvaid/v1
+
+# Installation gate. `nvaid init` scaffolds empty templates; the /nvaid:install SKILL
+# then scans the project and fills in all three required documents. The workflow commands
+# (/nvaid:intent, :contracts, :breakdown, :apply) are BLOCKED until install is complete —
+# running them against unfilled templates would produce hollow, confidently-wrong output.
+#
+# Each flag is set to true by /nvaid:install only once that document is genuinely filled
+# (not left as <placeholder> template text) and a human has confirmed it. The install is
+# "complete" when all three are true.
+install:
+  config: false              # project_name, owning_repo, tech_stack, architects all set
+  project_rules: false       # nvaid/PROJECT-RULES.md authored (not the template skeleton)
+  design_code_dictionary: false  # nvaid/DESIGN-CODE-DICTIONARY.md authored (not the skeleton)
+
+# A short name for this project/repo, used in generated artifact headers
+# (replaces the {{PROJECT_NAME}} placeholder in PROJECT-RULES.md and the dictionary).
+project_name: "<set-me>"
+
+# Which repo this is in the family — used to tag the units this repo owns when a
+# unit-breakdown is cut. One of: frontend | backend | platform | <other>.
+owning_repo: "<set-at-init>"
+
+# The full tech stack of this project. This is the STRUCTURED, machine-readable source of
+# truth that agents and the CLI key off — e.g. a skill checks `languages` before proposing
+# a dependency, or picks the right test command from `test`. Keep it factual and short;
+# the narrative "why we chose this / how it fits together" belongs in
+# nvaid/DESIGN-CODE-DICTIONARY.md, which references this block rather than repeating it.
+#
+# Leave a field blank or omit it if it doesn't apply. `additional` is an open map for
+# anything the fixed fields don't cover (message brokers, infra, cloud, auth providers…).
+tech_stack:
+  languages: []                 # e.g. ["TypeScript", "Python"]
+  runtime: ""                   # e.g. "Node >=18", "Python 3.12"
+  frameworks: []                # e.g. ["React", "FastAPI"]
+  package_manager: ""           # e.g. "npm", "pnpm", "uv", "poetry"
+  build: ""                     # e.g. "Vite", "tsup", "hatch"
+  test: ""                      # e.g. "Vitest", "pytest"
+  lint_format: ""               # e.g. "eslint + prettier", "ruff"
+  database: ""                  # e.g. "PostgreSQL 16", "none"
+  deploy: ""                    # e.g. "Docker + Kubernetes", "GitHub Pages"
+  additional: {}                # e.g. { cache: "Redis", broker: "RabbitMQ", auth: "OIDC" }
+
+# Named architects who sign off on each role's Architecture Contract.
+#
+# These are SIGN-OFF / OWNERSHIP identities: the person accountable for approving that
+# contract. The AI drafts contracts and flags them "awaiting <role> sign-off from <name>";
+# it never signs on their behalf (propose, don't dispose). Leave a role blank/null if this
+# repo doesn't have that architect — a contract for a missing role is simply not pulled in.
+architects:
+  solutions: "<name>"            # Solutions Architect
+  frontend: "<name>"             # Frontend / Identity-Access Architect (if this repo has a frontend)
+  backend: "<name>"              # Backend Solutions Architect (if this repo has a backend)
+  quality: "<name>"              # Quality Architect
+  customer_experience: "<name>"  # Customer Experience Architect (BA / PM)
+  # add any project-specific roles here, e.g.:
+  # devops: "<name>"
+
+# Coding agents nvaid injected skills into. `nvaid update` regenerates exactly these.
+# Managed by init/update; change via `nvaid init` rather than by hand.
+agents: []
+
+# Optional project context passed to every agent — constraints an agent can't infer
+# from the code. Keep discoverable codebase facts OUT (same discipline as openspec).
+# The project's full guardrails live in nvaid/PROJECT-RULES.md (fill in that template);
+# this field is just the short, always-on context.
+# Example:
+#   context: |
+#     On-premises only. No cloud targets.
+#     See nvaid/PROJECT-RULES.md for the approved stack and gates.
+context: ""
+
+# nvaid version this repo was last generated against. `nvaid validate` compares the
+# installed CLI version to this and flags drift.
+generated_with: "0.2.0"