@webjsdev/cli 0.8.1

package/templates/.claude/hooks/guard-branch-context.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+#
+# guard-branch-context.sh - Claude Code PreToolUse hook
+#
+# Rules:
+#   - On main/master → ask (agent should create a feature branch first)
+#   - On any other branch → allow (feature branches are free to edit)
+#   - Bypass mode → allow everything
+
+INPUT=$(cat /dev/stdin)
+
+# Bypass mode - full autonomy
+SETTINGS="$HOME/.claude/settings.json"
+if [ -f "$SETTINGS" ]; then
+  BYPASS=$(jq -r '.skipDangerousModePermissionPrompt // false' "$SETTINGS" 2>/dev/null)
+  if [ "$BYPASS" = "true" ]; then
+    exit 0
+  fi
+fi
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  exit 0
+fi
+
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+[ -z "$BRANCH" ] && exit 0
+
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  jq -n --arg reason "You are on '$BRANCH'. Create a feature branch first (git checkout -b feature/<name>), or approve to edit on '$BRANCH'." '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "ask",
+      permissionDecisionReason: $reason
+    }
+  }'
+  exit 0
+fi
+
+exit 0

package/templates/.claude/hooks/nudge-uncommitted.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+#
+# Claude Code PostToolUse hook.
+#
+# After each Edit, Write, MultiEdit, or NotebookEdit, counts
+# uncommitted changes in the working tree. When the count
+# crosses a threshold (default 4, override with the
+# WEBJS_COMMIT_NUDGE_THRESHOLD env var), injects a reminder
+# into the model's context via hookSpecificOutput.
+#
+# Soft nudge. Does NOT block the edit. The goal is to keep
+# the agent honest about the "commit per logical unit" rule,
+# not to interrupt valid work.
+#
+# Skipped on main/master and outside a git work tree.
+
+set -e
+
+THRESHOLD="${WEBJS_COMMIT_NUDGE_THRESHOLD:-4}"
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  exit 0
+fi
+
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  exit 0
+fi
+
+# Read stdin so we don't break Claude Code's hook contract.
+cat /dev/stdin >/dev/null 2>&1 || true
+
+CHANGED=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+if [ -z "$CHANGED" ] || [ "$CHANGED" -lt "$THRESHOLD" ]; then
+  exit 0
+fi
+
+REASON="You have ${CHANGED} uncommitted changes on '${BRANCH}'. The webjs convention is small, focused commits per logical unit (one feature, one fix, one rename, one doc rewrite). Before continuing with more edits, group the current changes into a meaningful commit. See AGENTS.md \"Git workflow\" for the rule and the rationale. To raise the threshold for this hook in long-running tasks, set WEBJS_COMMIT_NUDGE_THRESHOLD."
+
+jq -n --arg ctx "$REASON" '{
+  hookSpecificOutput: {
+    hookEventName: "PostToolUse",
+    additionalContext: $ctx
+  }
+}'

package/templates/.claude/settings.json

@@ -0,0 +1,35 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/block-prose-punctuation.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/guard-branch-context.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/nudge-uncommitted.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/.claude.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}

package/templates/.cursor/hooks/nudge-uncommitted.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+#
+# Cursor afterFileEdit hook.
+#
+# Counterpart of .claude/hooks/nudge-uncommitted.sh. After each
+# file edit, counts uncommitted changes in the working tree.
+# When the count crosses a threshold (default 4, override with
+# WEBJS_COMMIT_NUDGE_THRESHOLD), injects a reminder via the
+# top-level additional_context field (snake_case, unlike Claude
+# Code's nested hookSpecificOutput.additionalContext).
+#
+# Soft nudge. Exit 0 always. Skipped on main/master and outside
+# a git work tree.
+
+set -e
+
+THRESHOLD="${WEBJS_COMMIT_NUDGE_THRESHOLD:-4}"
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  exit 0
+fi
+
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  exit 0
+fi
+
+cat /dev/stdin >/dev/null 2>&1 || true
+
+CHANGED=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+if [ -z "$CHANGED" ] || [ "$CHANGED" -lt "$THRESHOLD" ]; then
+  exit 0
+fi
+
+REASON="You have ${CHANGED} uncommitted changes on '${BRANCH}'. The webjs convention is small, focused commits per logical unit (one feature, one fix, one rename, one doc rewrite). Before continuing with more edits, group the current changes into a meaningful commit. See AGENTS.md \"Git workflow\" for the rule and the rationale. To raise the threshold for this hook in long-running tasks, set WEBJS_COMMIT_NUDGE_THRESHOLD."
+
+jq -n --arg ctx "$REASON" '{ additional_context: $ctx }'

package/templates/.cursor/hooks.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "hooks": {
+    "afterFileEdit": [
+      { "command": ".cursor/hooks/nudge-uncommitted.sh" }
+    ]
+  }
+}

package/templates/.cursorrules

@@ -0,0 +1,99 @@
+# Cursor Rules - webjs app
+
+You are working on a webjs app - an AI-first, no-build, web-components-first
+framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
+project-specific conventions before writing any code. When AGENTS.md doesn't
+cover what you need, the full hosted docs are at **https://docs.webjs.com**.
+
+## Persistence + scaffold rules (non-negotiable)
+
+- **Use Prisma + SQLite for data, never JSON files.** It's already wired up
+  (`prisma/schema.prisma`, `lib/prisma.server.ts`, `npm run db:migrate`). For ANY
+  data the app stores (todos, posts, messages, products, comments…),
+  define a Prisma model. NEVER create `data/*.json`, `db.json`, or any
+  JSON file as a fake database. NEVER use module-scope arrays / Maps as
+  a substitute. NEVER use localStorage for app data. `webjs check`'s
+  `no-json-data-files` rule will fail the build if you do.
+- **The scaffold is reference, not the final product.** Replace
+  `app/page.ts`, the example `User` model, the example users module, etc.
+  with the app the user actually asked for. Don't ship "Hello from
+  <app-name>" as the deliverable.
+- **Only three templates exist:** `webjs create <name>` (default
+  full-stack), `--template api`, `--template saas`. The CLI rejects any
+  other `--template` value. Pick:
+  - Any product UI (todo, blog, dashboard, marketplace, social…) → default
+  - HTTP/JSON API only, no UI → `--template api`
+  - Auth / login / signup / SaaS → `--template saas`
+
+## Before starting ANY work
+
+FIRST, before writing any code:
+1. Run `git branch --show-current` to check the branch.
+   - If on main/master: STOP. Ask the user which branch to use, or create
+     one with `git checkout -b feature/<name>`.
+   - If on a feature branch: verify it matches the current task. Ask if unsure.
+2. Sync with parent: `git fetch origin && git log HEAD..origin/main --oneline`
+   - If upstream has new commits: `git rebase origin/main` before starting.
+   - Resolve any conflicts before proceeding with the task.
+
+## Autonomous mode (sandbox / no-prompt mode)
+
+If running without interactive approval, auto-decide:
+- On main? Auto-create feature/<task-slug> branch
+- Parent has new commits? Auto-rebase before starting
+- Merge? Auto-merge in autonomous mode, delete feature branches after
+- Commit message? Auto-generate (meaningful, no AI attribution)
+- Tests failing? Fix them. Convention violations? Fix them.
+Quality bar stays the same - just no blocking on questions.
+
+## Mandatory workflow (never skip)
+
+1. TESTS: Server tests in test/<feature>/ (node:test), browser tests in
+   test/<feature>/browser/ (WTR + Playwright, real Chromium). Run `webjs test`
+   after every change. Never deliver code without passing tests.
+
+2. DOCS: Update AGENTS.md for API changes. Update docs/ and website/ if
+   they exist. The user should never have to ask for tests or docs.
+
+3. CONVENTIONS: Run `webjs check` and fix violations before committing.
+
+## Git rules
+
+- COMMIT AND PUSH PER LOGICAL UNIT, NOT AT THE END. One feature, one fix,
+  one rename, one doc rewrite per commit. Always `git push` after
+  committing. This is automatic.
+- HARD LIMIT: if you have 5+ unstaged files spanning different concerns,
+  commit before continuing. The Claude Code hook at
+  `.claude/hooks/nudge-uncommitted.sh` fires at threshold 4. Cursor users
+  should self-enforce the same rule. Batching multiple logical units into
+  one commit is the failure mode this rule exists to prevent.
+- Write meaningful commit messages: what changed and why, not "update files"
+- NEVER add "Co-Authored-By", "Generated by", "AI-assisted" or similar
+  attribution trailers to commits
+- NEVER use em-dashes (U+2014), a hyphen-as-pause (` - `), or a
+  semicolon-as-pause (` ; `) in commit messages or anywhere else.
+  Rewrite the sentence so no pause-punctuation crutch is needed.
+  Use a period, comma, colon, parentheses, or a restructured phrasing.
+  Plain hyphens stay fine in compound words, CLI flags, filenames,
+  and ranges. Semicolons stay fine inside code
+- Work on feature branches, not main
+- NEVER push directly to main - create a pull request
+- NEVER merge any branch without explicit user permission. Always ask:
+  "Ready to merge <branch> into <target>? Delete or keep <branch> after?"
+  Wait for approval AND the delete/keep preference before proceeding.
+  This applies to ALL merges, not just merges into main.
+- Run tests before every commit
+- Keep commits small and focused
+
+## Framework rules
+
+- No build step: source files are served as ES modules
+- **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server falls back to esbuild + inline sourcemap for those files (~3x wire bytes per request).
+- Web components with shadow DOM: use `static styles = css` not inline styles
+- One function per server action file (*.server.ts)
+- Components must call customElements.define('tag', Class)
+- Server-only code (@prisma/client, node:*, anything that needs Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap the access in a .server.{js,ts} file; the framework rewrites that import into an RPC stub for the browser. lib/ holds both server-only infra (lib/prisma.server.ts) and browser-safe utilities (lib/utils/cn.ts with cn); follow the same rule per file: if a lib/ file needs Node APIs, only import it from server-only files.
+- Directives are deliberately minimal: only `unsafeHTML`, `live`, and `repeat` ship. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported - use plain template-literal expressions (`class=${cond ? 'a' : 'b'}`, `${cond ? a : b}`) and lifecycle hooks (`this.query('#el')` in `firstUpdated`) instead.
+- **Progressive enhancement is the default.** Pages AND every web component are SSR'd to real HTML. Write components so the first paint is the right content (read SSR-meaningful defaults in `constructor()`, not `connectedCallback` - the server doesn't call lifecycle hooks). Initial data for components comes from the page function (server-side fetch + pass as attribute/property), NOT from `fetch` calls in `connectedCallback`. For write-paths, prefer `<form action=...>` + server action over `fetch` + click handler - the framework upgrades plain forms to partial-swap submissions automatically.
+- **Client navigation is auto-magic.** Real `<a href>` and `<form action>` get partial-swap behavior with no opt-in. Layouts persist across navigation - put shared chrome (sidenav, header) in `layout.ts`, page-specific content in `page.ts`. For validation errors, return 4xx HTML from a `route.ts` POST handler; the router renders it in place preserving the user's input. For non-layout swap regions, wrap in `<webjs-frame id="...">`. See "Client navigation patterns" in AGENTS.md.
+- See AGENTS.md for the complete directive decision guide

package/templates/.editorconfig

@@ -0,0 +1,18 @@
+# EditorConfig - consistent formatting across editors and AI agents
+# https://editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

package/templates/.env.example

@@ -0,0 +1,27 @@
+# webjs environment variables
+# Copy to .env and fill in your values: cp .env.example .env
+#
+# Opinionated defaults: set these and the framework auto-configures.
+
+# ── Server ──────────────────────────────────────────────────────────
+PORT=3000
+
+# ── Auth (required for authentication) ──────────────────────────────
+# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+AUTH_SECRET=
+
+# ── OAuth providers (optional - enable the ones you need) ───────────
+# AUTH_GOOGLE_ID=
+# AUTH_GOOGLE_SECRET=
+# AUTH_GITHUB_ID=
+# AUTH_GITHUB_SECRET=
+
+# ── Redis (production scaling) ──────────────────────────────────────
+# Set this and cache, sessions, rate limiting, and pub/sub all
+# automatically use Redis. Without it, everything uses in-memory
+# defaults (great for development).
+# REDIS_URL=redis://localhost:6379
+
+# ── Database ────────────────────────────────────────────────────────
+# Used by Prisma. SQLite for dev, PostgreSQL/MySQL for production.
+DATABASE_URL=file:./dev.db

package/templates/.gemini/hooks/nudge-uncommitted.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+#
+# Gemini CLI AfterTool hook.
+#
+# Counterpart of .claude/hooks/nudge-uncommitted.sh. After each
+# write_file or replace, counts uncommitted changes in the working
+# tree. When the count crosses a threshold (default 4, override
+# with the WEBJS_COMMIT_NUDGE_THRESHOLD env var), injects a
+# reminder via hookSpecificOutput.additionalContext (same shape
+# as Claude Code).
+#
+# Soft nudge. Does NOT block the edit (exit 0). Skipped on
+# main/master and outside a git work tree.
+
+set -e
+
+THRESHOLD="${WEBJS_COMMIT_NUDGE_THRESHOLD:-4}"
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  exit 0
+fi
+
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  exit 0
+fi
+
+cat /dev/stdin >/dev/null 2>&1 || true
+
+CHANGED=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+if [ -z "$CHANGED" ] || [ "$CHANGED" -lt "$THRESHOLD" ]; then
+  exit 0
+fi
+
+REASON="You have ${CHANGED} uncommitted changes on '${BRANCH}'. The webjs convention is small, focused commits per logical unit (one feature, one fix, one rename, one doc rewrite). Before continuing with more edits, group the current changes into a meaningful commit. See AGENTS.md \"Git workflow\" for the rule and the rationale. To raise the threshold for this hook in long-running tasks, set WEBJS_COMMIT_NUDGE_THRESHOLD."
+
+jq -n --arg ctx "$REASON" '{
+  hookSpecificOutput: {
+    additionalContext: $ctx
+  }
+}'

package/templates/.gemini/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "AfterTool": [
+      {
+        "matcher": "write_file|replace",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".gemini/hooks/nudge-uncommitted.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/.github/copilot-instructions.md

@@ -0,0 +1,85 @@
+# GitHub Copilot Instructions: webjs app
+
+You are working on a webjs app, an AI-first, no-build, web-components-first
+framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
+project-specific conventions. When AGENTS.md doesn't cover what you need,
+the full hosted docs are at **https://docs.webjs.com**.
+
+## Persistence + scaffold rules (non-negotiable)
+
+- **Use Prisma + SQLite for data, never JSON files.** It's already wired up
+  (`prisma/schema.prisma`, `lib/prisma.server.ts`, `npm run db:migrate`). For ANY
+  data the app stores (todos, posts, messages, products, comments…),
+  define a Prisma model. NEVER create `data/*.json`, `db.json`, or any
+  JSON file as a fake database. NEVER use module-scope arrays / Maps as
+  a substitute. NEVER use localStorage for app data. `webjs check`'s
+  `no-json-data-files` rule will fail the build if you do.
+- **The scaffold is reference, not the final product.** Replace
+  `app/page.ts`, the example `User` model, the example users module, etc.
+  with the app the user actually asked for. Don't ship "Hello from
+  <app-name>" as the deliverable.
+- **Only three templates exist:** `webjs create <name>` (default
+  full-stack), `--template api`, `--template saas`. The CLI rejects any
+  other `--template` value. Pick:
+  - Any product UI (todo, blog, dashboard, marketplace, social…) → default
+  - HTTP/JSON API only, no UI → `--template api`
+  - Auth / login / signup / SaaS → `--template saas`
+
+## Before starting ANY work
+
+FIRST, before writing any code:
+1. Check `git branch --show-current`.
+   - If on main/master: create a feature branch before editing.
+   - If on a feature branch: verify it matches the task at hand.
+2. Sync: `git fetch origin && git rebase origin/main` if behind.
+
+## Autonomous mode
+
+If running without interactive approval (sandbox, auto-approve, etc.):
+- On main? Auto-create feature/<task-slug> branch
+- Parent behind? Auto-rebase. Merge? Auto-merge + delete feature branches.
+- Auto-generate meaningful commit messages. Fix tests and violations.
+
+## Mandatory workflow
+
+Every code change must include:
+1. Commit and push PER LOGICAL UNIT, not at the end. One feature, one fix,
+   one rename, one doc rewrite per commit. Always `git push` after
+   committing. Don't accumulate changes. If you have 5+ unstaged files
+   spanning different concerns, commit before continuing. The Claude Code
+   hook at `.claude/hooks/nudge-uncommitted.sh` enforces threshold 4 for
+   Claude users; Copilot users should self-enforce the same rule. Automatic.
+2. Server tests in test/<feature>/*.test.ts (node:test for actions, queries, utilities)
+3. Browser tests in test/<feature>/browser/*.test.js (WTR + Playwright, real Chromium)
+4. Documentation updates (AGENTS.md for API, docs/ for user guides)
+5. Convention validation: `webjs check` must pass
+
+## Git rules
+
+- Commit after each logical unit of work
+- Meaningful commit messages: what changed and why
+- NEVER add Co-Authored-By or AI attribution trailers to commits
+- Work on feature branches, create PRs, never push directly to main
+- NEVER merge any branch without explicit user permission. Always ask:
+  "Ready to merge <branch> into <target>? Delete or keep <branch> after?"
+  Wait for approval AND the delete/keep preference. Applies to ALL merges.
+- Run `webjs test` before every commit
+
+## Code patterns
+
+- **Erasable TypeScript only.** Node 24+ strips types via `module.stripTypeScriptTypes` (whitespace replacement, byte-exact position preservation, no sourcemap). The scaffold's tsconfig.json sets `erasableSyntaxOnly: true`, so the TS compiler rejects `enum`, `namespace` with values, constructor parameter properties, legacy decorators with `emitDecoratorMetadata`, and `import = require`. Use erasable equivalents: `const X = { ... } as const` plus a derived union type instead of `enum`; explicit fields plus constructor body assignments instead of parameter properties. If `erasableSyntaxOnly` is disabled and non-erasable syntax is used, the dev server falls back to esbuild + inline sourcemap for those files (~3x wire bytes per request).
+- Tagged template: html`<div>${value}</div>` with css`...` for styles
+- Components: extend WebComponent, declare `static properties` (and `static styles` for shadow-DOM components), call `Class.register('tag-name')` at the bottom of the file. The tag name is the argument to `.register()`, not a static field.
+- Server actions: *.server.ts files with one exported async function each
+- Directives: webjs ships only `unsafeHTML`, `live`, and `repeat`. Lit's `classMap` / `styleMap` / `ref` / `when` / `choose` / `guard` are NOT exported - use plain template-literal expressions and lifecycle hooks instead.
+- Context: import { createContext, ContextProvider, ContextConsumer } from '@webjsdev/core/context'
+- Task: import { Task, TaskStatus } from '@webjsdev/core/task'
+- Routing: file-based under app/ (page.ts, layout.ts, route.ts, middleware.ts)
+
+## What NOT to do
+
+- Don't introduce build tools or bundlers in the critical path
+- Server-only code (@prisma/client, node:*, anything needing Node APIs) goes only in .server.{js,ts} files, route.ts handlers, or middleware.ts. Never in pages, layouts, or components. Wrap in a .server.{js,ts} file; the framework rewrites that import to an RPC stub for the browser. lib/ holds both server-only infra (lib/prisma.server.ts) and browser-safe utilities (lib/utils/cn.ts with cn); apply the same rule per file.
+- Don't use inline style="..." on components (use static styles = css`...`)
+- Component state lives in signals from @webjsdev/core. Module-scope signals share state across components; instance signals (created in the constructor) carry component-local state. Reactive properties (static properties + declare) are for HTML attributes and .prop=${...} hydration.
+- Don't skip tests or documentation updates

package/templates/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Summary
+
+<!-- What does this PR do? 1-3 bullet points. -->
+
+## Test plan
+
+- [ ] Unit tests added/updated (`webjs test` passes)
+- [ ] E2E tests added/updated for user-facing changes (`webjs test --e2e` passes)
+- [ ] `webjs check` passes (no convention violations)
+
+## Documentation
+
+- [ ] AGENTS.md updated (if API surface changed)
+- [ ] Docs updated (if docs/ exists and feature is documented)

package/templates/.hooks/pre-commit

@@ -0,0 +1,48 @@
+#!/bin/bash
+#
+# pre-commit hook - blocks commits on main/master.
+#
+# No AI agent, no editor, no human can commit to main directly.
+# Create a feature branch first. This is git-level enforcement.
+#
+# To bypass in emergencies: git commit --no-verify
+
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null)
+
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  echo ""
+  echo "ERROR: Cannot commit directly to '$BRANCH'."
+  echo ""
+  echo "Create a feature branch first:"
+  echo "  git checkout -b feature/<name>"
+  echo ""
+  echo "To bypass (emergencies only): git commit --no-verify"
+  echo ""
+  exit 1
+fi
+
+# webjs test + webjs check on every commit. Tool-agnostic enforcement:
+# fires regardless of which agent (Claude, Cursor, Windsurf, Copilot,
+# human) is making the commit. Skipped if the CLI is not yet installed
+# (fresh clone before npm install).
+if command -v webjs >/dev/null 2>&1 || [ -x "node_modules/.bin/webjs" ]; then
+  echo "Running webjs test..."
+  if ! npx --no-install webjs test; then
+    echo ""
+    echo "ERROR: webjs test failed. Fix tests before committing."
+    echo "To bypass (emergencies only): git commit --no-verify"
+    echo ""
+    exit 1
+  fi
+
+  echo "Running webjs check..."
+  if ! npx --no-install webjs check; then
+    echo ""
+    echo "ERROR: webjs check failed. Fix convention violations before committing."
+    echo "To bypass (emergencies only): git commit --no-verify"
+    echo ""
+    exit 1
+  fi
+fi
+
+exit 0

package/templates/.opencode/plugins/nudge-uncommitted.ts

@@ -0,0 +1,62 @@
+/**
+ * OpenCode commit-frequency nudge plugin.
+ *
+ * Counterpart of the Claude Code, Gemini CLI, and Cursor hooks in
+ * `.claude/hooks/`, `.gemini/hooks/`, and `.cursor/hooks/`. After
+ * each edit/write tool call, counts uncommitted changes in the
+ * working tree. When the count crosses a threshold (default 4,
+ * override with the WEBJS_COMMIT_NUDGE_THRESHOLD env var), appends
+ * a reminder to the tool result so the agent sees it on the next
+ * turn.
+ *
+ * Soft nudge by design. Does NOT block the edit. The goal is to
+ * keep the agent honest about the "commit per logical unit" rule,
+ * not to interrupt valid work.
+ *
+ * Skipped on main/master (different guard rules cover that) and
+ * outside a git work tree.
+ *
+ * Auto-discovered by OpenCode at startup. No opencode.json entry
+ * needed. Lives in .opencode/plugins/ at the project root.
+ *
+ * Docs: https://opencode.ai/docs/plugins/
+ */
+import type { Plugin } from "@opencode-ai/plugin";
+
+export const NudgeUncommitted: Plugin = async ({ $ }) => {
+  const THRESHOLD = Number(process.env.WEBJS_COMMIT_NUDGE_THRESHOLD ?? 4);
+
+  return {
+    "tool.execute.after": async (input, output) => {
+      if (input.tool !== "edit" && input.tool !== "write") return;
+
+      let branch = "";
+      try {
+        branch = (await $`git symbolic-ref --short HEAD`.text()).trim();
+      } catch {
+        return; // not in a git work tree
+      }
+      if (branch === "main" || branch === "master") return;
+
+      let changed = 0;
+      try {
+        const out = (await $`git status --porcelain`.text()).trim();
+        changed = out === "" ? 0 : out.split("\n").length;
+      } catch {
+        return;
+      }
+      if (changed < THRESHOLD) return;
+
+      const reason =
+        `[webjs] You have ${changed} uncommitted changes on '${branch}'. ` +
+        `The webjs convention is small, focused commits per logical unit ` +
+        `(one feature, one fix, one rename, one doc rewrite). Before ` +
+        `continuing with more edits, group the current changes into a ` +
+        `meaningful commit. See AGENTS.md "Git workflow" for the rule ` +
+        `and the rationale. To raise the threshold for this hook in ` +
+        `long-running tasks, set WEBJS_COMMIT_NUDGE_THRESHOLD.`;
+
+      output.output = output.output ? `${output.output}\n\n${reason}` : reason;
+    },
+  };
+};