@cbnventures/nova 0.13.1 → 0.15.0

package/build/templates/generators/must-haves/agent-conventions/conventions/css.md

@@ -0,0 +1,188 @@
+# CSS Conventions
+
+Selectors: class-based. Indentation: 2-space. File naming: kebab-case (e.g., `user-profile.css`).
+
+## Documentation Style
+
+Section banners use JSDoc-style block comments with `=` borders:
+
+```css
+/**
+ * ============================
+ * Section Title
+ * ============================
+ */
+```
+
+Inline comments use `/* ... */` above the rule or declaration they describe.
+
+## Code Style
+
+### Class Naming
+
+Use kebab-case for class names. Names describe the component or element, not its appearance.
+
+```css
+/* BAD — camelCase, visual description */
+.userCard { ... }
+.redButton { ... }
+
+/* GOOD — kebab-case, semantic */
+.user-card { ... }
+.action-button { ... }
+.action-button-primary { ... }
+```
+
+### Property Ordering
+
+Group properties by category in this order:
+1. Positioning (`position`, `top`, `right`, `z-index`)
+2. Display and box model (`display`, `flex`, `width`, `margin`, `padding`)
+3. Typography (`font-size`, `line-height`, `color`, `text-align`)
+4. Visual (`background`, `border`, `border-radius`, `box-shadow`, `opacity`)
+5. Animation (`transition`, `animation`, `transform`)
+6. Miscellaneous (`cursor`, `pointer-events`, `overflow`)
+
+Blank line between each group.
+
+```css
+.user-card {
+  position: relative;
+  z-index: 1;
+
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  padding: 16px;
+
+  font-size: 14px;
+  line-height: 1.5;
+  color: var(--color-text);
+
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: 8px;
+
+  transition: box-shadow 200ms ease;
+}
+```
+
+### Custom Properties
+
+Use `--` prefix with namespace. Define at `:root` for globals, at component level for scoped values.
+
+```css
+/* GOOD — namespaced globals */
+:root {
+  --color-text: hsl(0 0% 13%);
+  --color-surface: hsl(0 0% 100%);
+  --color-border: hsl(0 0% 87%);
+  --spacing-sm: 8px;
+  --spacing-md: 16px;
+}
+
+/* GOOD — component-scoped */
+.user-card {
+  --card-padding: var(--spacing-md);
+
+  padding: var(--card-padding);
+}
+```
+
+### Selector Specificity
+
+Keep specificity low. Prefer class selectors. No ID selectors for styling. No `!important` except for utility overrides.
+
+```css
+/* BAD — ID selector */
+#main-header { ... }
+
+/* BAD — !important for regular styling */
+.header { color: red !important; }
+
+/* GOOD — class selectors only */
+.main-header { ... }
+.main-header-title { ... }
+```
+
+### Media Queries
+
+Mobile-first approach. Use `min-width` breakpoints. Colocate media queries with the component they modify.
+
+```css
+/* GOOD — mobile-first, colocated */
+.user-card {
+  padding: 8px;
+}
+
+@media (min-width: 768px) {
+  .user-card {
+    padding: 16px;
+  }
+}
+```
+
+### Units
+
+- `rem` for font sizes and spacing tied to text.
+- `px` for borders, shadows, and fixed dimensions.
+- `%` or viewport units for fluid layout.
+- No `em` for spacing (compounds unpredictably in nested contexts).
+
+### Nesting
+
+Use native CSS nesting for pseudo-classes, pseudo-elements, and direct modifiers. Do not nest deeper than 2 levels.
+
+```css
+/* GOOD — shallow nesting for modifiers */
+.action-button {
+  background: var(--color-surface);
+
+  &:hover {
+    background: var(--color-surface-hover);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--color-focus);
+    outline-offset: 2px;
+  }
+}
+
+/* BAD — too deep */
+.nav {
+  .nav-list {
+    .nav-item {
+      .nav-link { ... }
+    }
+  }
+}
+```
+
+### One Declaration per Line
+
+Each declaration goes on its own line. No single-line rule sets.
+
+```css
+/* BAD — single-line */
+.hidden { display: none; }
+
+/* GOOD */
+.hidden {
+  display: none;
+}
+```
+
+### Comment Placement
+
+Comments describe the purpose of a rule set or declaration group. Placement rules:
+- Comment sits above the rule set or declaration it describes.
+- Blank line before the comment (except at the start of a file).
+- No trailing comments (same-line comments after declarations).
+
+### No Stacked Comments
+
+One descriptive comment per rule set or declaration group. No consecutive comments without code between them.
+
+### Blank Lines between Rule Sets
+
+Separate each rule set with a blank line.

package/build/templates/generators/must-haves/agent-conventions/conventions/docker.md

@@ -0,0 +1,131 @@
+# Docker Conventions
+
+Base images: pinned tags. Instructions: one logical step per `RUN`. File naming: kebab-case (e.g., `api-gateway.Dockerfile`).
+
+## Documentation Style
+
+Box-style `####` banners with padded titles:
+
+```dockerfile
+############################
+#### Step 1: Base Image ####
+############################
+```
+
+## Code Style
+
+### Pin Base Image Tags
+
+Always use specific version tags. Never use `latest` or bare image names.
+
+```dockerfile
+# BAD — unpinned
+FROM node
+FROM node:latest
+
+# GOOD — pinned to specific version
+FROM node:22.14.0-alpine
+FROM postgres:17.4-alpine
+```
+
+### Multi-Stage Builds
+
+Use named stages. Keep the final image minimal — copy only what's needed from build stages.
+
+```dockerfile
+# GOOD — named stages, minimal final image
+FROM node:22.14.0-alpine AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22.14.0-alpine AS runtime
+WORKDIR /app
+COPY --from=build /app/build ./build
+COPY --from=build /app/package.json ./
+RUN npm ci --omit=dev
+USER node
+EXPOSE 3000
+CMD ["node", "build/index.js"]
+```
+
+### Layer Caching Order
+
+Order instructions from least-changing to most-changing. Copy dependency manifests before source files so dependency layers cache independently.
+
+```dockerfile
+# BAD — source copy before dependency install
+COPY . .
+RUN npm ci
+
+# GOOD — dependency files first, then source
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+```
+
+### HEALTHCHECK Directive
+
+Always include a `HEALTHCHECK` instruction for services that accept connections.
+
+```dockerfile
+# GOOD — explicit health check
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD ["wget", "--spider", "--quiet", "http://localhost:3000/health"]
+```
+
+### Non-Root User
+
+Always switch to a non-root user before `CMD`/`ENTRYPOINT`. Create the user if the base image doesn't provide one.
+
+```dockerfile
+# GOOD — official Node image includes "node" user
+USER node
+
+# GOOD — create user when base image has none
+RUN addgroup --system appgroup && adduser --system --ingroup appgroup appuser
+USER appuser
+```
+
+### .dockerignore
+
+Always maintain a `.dockerignore` alongside the Dockerfile. At minimum, exclude version control, dependencies, build output, and environment files.
+
+```
+.git
+node_modules
+build
+dist
+.env
+.env.*
+*.log
+```
+
+### RUN Instruction Style
+
+Combine related commands in a single `RUN` with `&&`. Each logical step (install, configure, build) gets its own `RUN`. Clean up caches in the same layer they're created.
+
+```dockerfile
+# BAD — separate layers for related commands
+RUN apt-get update
+RUN apt-get install -y curl
+RUN rm -rf /var/lib/apt/lists/*
+
+# GOOD — combined, cleanup in same layer
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends curl \
+  && rm -rf /var/lib/apt/lists/*
+```
+
+### Comment Placement
+
+Comments describe the process/intent. Placement rules:
+- Comment sits above the instruction it describes.
+- Blank line before the comment (except at the start of a stage).
+- No trailing comments (same-line comments after instructions).
+
+### No Stacked Comments
+
+One descriptive comment per instruction block. No consecutive comments without instructions between them.