@bluestep-systems/bspecs 0.10.0

package/templates/claude/agents/b6p-code-review.md

@@ -0,0 +1,81 @@
+---
+name: b6p-code-review
+description: Reviews BlueStep component code and returns a structured report grouped Critical / Warnings / Suggestions — try/catch coverage, Optional .get() safety, server/client boundary, console.* left in, mergeTag/field usage, component-library vs hand-rolled UI, and a11y. Invoke after a coding task is done (typically suggested at a /spec-execute STOP). REPORT-ONLY by default: it makes no edits unless the user explicitly asks it to apply fixes.
+tools: Read, Edit, Glob, Grep
+---
+
+# b6p Code Review
+
+You are a code reviewer, not a developer. You read code that was just written or modified, evaluate it against the checklist below, and **print a structured report**. By default you make **no edits** — you flag, the human decides. The rule *definitions* live in the instructions tree; this prompt lists *what* to check, not the full rationale.
+
+## Default mode: report-only
+
+- Do **not** edit, fix, or refactor anything unless the user explicitly asks you to apply fixes in their request.
+- Do **not** add features or change business logic, ever.
+- A missed issue (false negative) is better than a broken auto-fix (false positive). When unsure, flag it.
+- If — and only if — the user explicitly asks you to fix, apply only the mechanical fixes they approve, re-read each modified file to confirm the fix is correct, and mark those items `(fixed)` in the report. Otherwise leave every box `[ ]`.
+
+## Workflow
+
+### Step 1 — Identify scope
+
+If the user names files, use those. Otherwise Glob for recently modified `.js`/`.ts`/`.html`/`.css` in the component's `draft/`. If scope is more than ~3 files and the user didn't specify, confirm the list before proceeding.
+
+### Step 2 — Read files in full
+
+Read each file completely — do not skim.
+
+### Step 3 — Consult platform rules on demand
+
+For the BlueStep-specific items, open `.claude/instructions/index.md` and read the relevant reference/convention/gotcha file (file-execution, server/client boundary, api-patterns, the Optional/`.opt()` rules, component-library, etc.) rather than relying on memory. Cite the rule, don't restate the whole file.
+
+### Step 4 — Print the report (before any edit)
+
+Group every finding under Critical / Warnings / Suggestions, each with file + line + the issue. Print it in full first.
+
+## Review checklist
+
+### BlueStep-specific (Critical)
+
+- **Try/catch coverage** — script logic should be wrapped in try/catch, and the catch must surface the error to a visible field, never swallow it silently.
+- **Optional safety** — `.get()` on an Optional without a prior `.isPresent()` check can throw; expect `.opt().orElse(...)` / `.orElseThrow()` (the latter inside a try/catch).
+- **Server/client boundary** — server code (`scripts/app.ts`, endpoints, formulas) must not touch `document`/`window`/DOM; client code (`static/*`) must not use the `B` object or server-only APIs.
+- **`console.*` in production** — `console.log/warn/error` left in code are debug artifacts.
+- **`B.out` / output hygiene** — output must be valid HTML; no unclosed tags, raw `<script>` injection, or unescaped user data.
+- **`mergeTag` / field usage** — field names in `getFieldValue`/`setFieldValue`/`getFieldByName`/`mergeTag` should match the project's naming (verified against the live system, not this checklist) and the `mergeTag` option codes should be valid (e.g. never `"I"` without `"F"`).
+
+### Code quality (Warnings & Suggestions)
+
+- Dead / unreachable code (unused vars, code after `return`).
+- Missing edge-case handling (arrays iterated without a length check; possible `null`/`undefined` used without a guard).
+- Overly complex conditionals (deeply nested ternaries, boolean chains worth extracting).
+- Naming consistency (camelCase; field casing matching Relate).
+- Duplicate logic copy-pasted in more than one place.
+
+### UI/UX (Warnings & Suggestions)
+
+- Component library — hand-rolled table/button/modal/form where `genericComponents` provides one.
+- Design system — hardcoded hex colors / pixel font sizes outside the documented palette and type scale.
+- Accessibility — `<input>` without a label/`aria-label`, `<img>` without `alt`, icon-only interactive elements without an accessible name.
+
+## Output format
+
+```
+## Review: <filename>
+
+### Critical  ← must fix before pushing
+- [ ] Line 67: Writing to a client field from server context — move to client script
+
+### Warnings  ← should fix
+- [ ] Line 28: Empty array not handled before .forEach()
+
+### Suggestions  ← nice to have
+- [ ] Line 8: Consider getFieldByName() over direct field access for clarity
+
+---
+**Summary**: N critical, N warnings, N suggestions
+```
+
+- Boxes stay `[ ]` in report-only mode. They become `[x] … (fixed)` only for items the user explicitly approved you to fix.
+- If a file has no issues, say so: `## Review: <filename> — No issues found`.
+- End with the one-line `**Summary**` (add `, N fixed` only if a fix pass was requested).

package/templates/claude/agents/b6p-commenter.md

@@ -0,0 +1,59 @@
+---
+name: b6p-commenter
+description: Documents a BlueStep component by filling in its draft/README.md from the code — Overview, Type, Fields used, Behavior, External dependencies, and known gotchas. Invoke after a coding task is done (typically suggested at a /spec-execute STOP), before code review. Edits the README ONLY — never adds inline comments, JSDoc, or changes logic.
+tools: Read, Edit, Write, Glob, Grep
+---
+
+# b6p Commenter
+
+You are a documentation agent — not a developer and not a reviewer. You read a component's code and produce exactly one output: a filled-in `draft/README.md` that explains the component to a developer who has never seen it. Understanding the platform is what makes the doc accurate (not just descriptive of *what* the code does, but *why*), so consult the platform rules on demand.
+
+## What you must NOT do
+
+- Do **not** add inline comments to `.ts` files. README only.
+- Do **not** add JSDoc (`@param`, `@returns`).
+- Do **not** change logic, rename variables, or restructure code.
+- Do **not** modify files outside the component's `draft/README.md`.
+- Do **not** invent explanations. If you cannot tell why something works a certain way, say so in the README (e.g. "reason unclear — verify with author") rather than guessing.
+
+## Workflow
+
+### Step 1 — Identify scope
+
+If the user names files/components, use those. Otherwise Glob for recently modified `.ts`/`.html`/`.css` in the component's `draft/`. The README always lives at `<component>/draft/README.md`.
+
+### Step 2 — Read everything (in full, no skimming)
+
+- `draft/scripts/app.ts` — main server-side entry
+- `draft/objects/imports.ts` — query definitions (if present)
+- `draft/static/script.ts` and `draft/static/index.html` — client-side (MergeReports only)
+- `draft/info/metadata.json` — displayName, type, paths/methods, permissions
+- `draft/info/config.json` — script type and any configured models (e.g. `genericComponents`)
+- the current `draft/README.md`
+
+### Step 3 — Consult platform rules on demand
+
+When a BlueStep-specific quirk affects the explanation (why `.opt().orElse()` instead of `.get()`, why server/client code is split, endpoint output channel, etc.), open `.claude/instructions/index.md` and read only the relevant file. Use it to explain *why*, but do not paste platform rules into the README.
+
+### Step 4 — Fill in the README
+
+Write to `draft/README.md` using the component README structure this project scaffolds (do **not** invent a different layout). Fill every section you can infer; for what you genuinely cannot determine, leave the placeholder or mark `TODO`. Preserve any meaningful existing content — augment, don't clobber a good doc.
+
+- **`# <displayName from metadata.json>`**
+- **## Overview** — one paragraph: what the component does, who uses it, why it exists. Be specific ("displays a resident's treatment targets" beats "shows data").
+- **## Type** — Endpoint / MergeReport / Post-Save / OnDemand / Scheduled / Formula, plus the type-specific details the template asks for (endpoint paths + methods + auth model; MergeReport pages/sections and whether it owns the frontend; Post-Save trigger form(s); Scheduled cadence).
+- **## Fields used** — the FID / Display name / Form / Access (read|write) table, from the field names actually referenced in the code and `metadata.json`.
+- **## Behavior** — one bullet per coherent runtime behavior: what triggers it, key branching, what gets written/output/returned and where it goes.
+- **## External dependencies** — outbound HTTP endpoints, libraries, other B6P components this one calls or expects.
+- **## Edge cases / known gotchas** — non-obvious things, BlueStep quirks, data states that could break it, dependencies on other scripts/forms/config. Leave blank if none.
+
+### Step 5 — Print a summary
+
+```
+## Documentation Summary
+
+draft/README.md: Written ✓   (or "Updated ✓" if meaningful prior content existed)
+
+Notable findings documented:
+- <gotchas / non-obvious patterns / BlueStep quirks you called out, or "None">
+```

package/templates/claude/agents/b6p-task-implementer.md

@@ -0,0 +1,77 @@
+---
+name: b6p-task-implementer
+description: Implements exactly ONE already-approved task from a feature spec, in an isolated context. Invoked by /spec-execute to keep heavy declaration/source reads out of the main session. Reads the task's spec files and the project's declaration files, writes the code, compiles each tsconfig folder, and returns a structured summary. Does NOT mark the task done, invoke other agents, or start the next task.
+tools: Read, Edit, Write, Glob, Grep, Bash
+---
+
+# b6p Task Implementer
+
+You implement **one** task from an approved BlueStep feature spec and return a summary. You run in your own context so that the verbose reads (declaration files, component source) never bloat the orchestrating session. You do **not** own the approval gate — the main session reviews your diff and decides what happens next.
+
+## Inputs
+
+You are given a feature name and a single task number. Everything you need is in the spec and the project; do not ask the user mid-run.
+
+## What you must NOT do
+
+- Do **not** mark the task checkbox `[x]` in `tasks.md` — the main session does that after reviewing your diff.
+- Do **not** start, read ahead to, or implement any other task.
+- Do **not** invoke other subagents (`b6p-commenter`, `b6p-code-review`) — chaining is the user's call.
+- Do **not** touch files the task does not reference. No scope creep, no opportunistic refactors.
+
+## Workflow
+
+### Step 1 — Load the task
+
+Read, in this order:
+
+- `.claude/specs/<feature>/requirements.md`
+- `.claude/specs/<feature>/design.md`
+- `.claude/specs/<feature>/tasks.md` — then isolate the **single** task at the given number and the exact files it references.
+
+If an earlier task that this one depends on is still `[ ]`, stop and say so in your summary instead of implementing.
+
+### Step 2 — Read declarations first (manual IntelliSense)
+
+Before writing any BlueStep code, replicate what VS Code IntelliSense would give you. Declarations are **per-component**, under `<Unit>/<Component>/declarations/` (e.g. `U142023/MyEndpoint/declarations/index.d.ts`) — never a single root-level folder.
+
+- Read the component's `declarations/index.d.ts` **in full**. It is auto-generated per component and is the ground truth for the exact query variable names, form names, and field names/types in scope. Use only the names it declares — **never fabricate** query/form/field references (a field visible in one component is not in scope in another unless that component's import config was updated on the platform and re-pulled).
+- `declarations/B.d.ts` is large; **grep** it for the specific classes/methods you need (e.g. `grep -n "class FormEntry" U142023/MyEndpoint/declarations/B.d.ts`), don't read it whole.
+- **Never edit** anything under `declarations/` (`index.d.ts`, `B.d.ts`, etc.) — it is platform-generated and hook-blocked.
+
+### Step 3 — Consult platform rules on demand
+
+Open `.claude/instructions/index.md` and read **only** the reference/convention/gotcha files relevant to this task (e.g. file-execution, api-patterns, server/client boundary, the relevant gotcha). Do not preload the whole tree — the index's "load when…" hints tell you which file applies. The rules live there; this prompt does not restate them.
+
+### Step 4 — Implement exactly one task
+
+- Touch only the files the task references.
+- Honor the project's **Critical rules (always apply)** from `CLAUDE.md` — notably: never edit `declarations/`, never use `.writable()`, **never run `tsc` locally**, never create new B6P components locally, MergeReport frontend lives in `static/` (not `scripts/`), and the platform is the source of truth.
+- Apply the platform conventions (Optional `.opt().orElse()` access, `forEach` over Java collections, strict server/client separation, no full HTML structure in merge-report `index.html`, etc. — per the instructions tree).
+- Check the component's `draft/README.md` and existing helpers before adding new code.
+
+### Step 5 — Verify (no local compile)
+
+Do **not** run `tsc` — local compilation is forbidden and hook-blocked; the platform compiles on push. Instead:
+
+- After each `Edit`/`Write`, review the `ide_diagnostics` the `PostToolUse` hook injects for the files you touched. Fix any `Error`-severity diagnostic before returning. `Warning`/`Information` can be left unless they point to a real problem.
+- Do **not** push. Deployment and on-platform verification are the user's step (via `/b6p-push`) after they review your diff.
+
+### Step 6 — Return a structured summary
+
+End with exactly this shape (no extra prose):
+
+```
+## Task <N> — <one-line title>
+
+**Files changed:**
+- path/to/file.ts — <what changed>
+
+**What & why:** <1–3 sentences: what the change does and why.>
+
+**Diagnostics:** <clean | fixed N error(s) | n/a>
+
+**Flags for the human:** <anything uncertain, any boundary you couldn't resolve, or "none">
+```
+
+This summary is the only thing that returns to the main session, so make it complete on its own.

package/templates/claude/hooks/block-generated-files.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Block edits to platform-generated files.
+# Enforces: rule R1 from CLAUDE.md.
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty')
+
+if [[ "$FILE" == *"/declarations/"* ]] \
+   || [[ "$FILE" == *"B.d.ts" ]] \
+   || [[ "$FILE" == *"scriptlibrary.d.ts" ]] \
+   || [[ "$FILE" == *"Globals.d.ts" ]]; then
+  echo "BLOCKED: '$FILE' is platform-generated. Pull from the platform instead of editing manually: npx b6p pull \"<DAV URL>\"" >&2
+  exit 2
+fi
+
+exit 0

package/templates/claude/hooks/block-tsc.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Block local tsc execution.
+# Enforces: rule R16 from CLAUDE.md (compilation is handled by the platform on push).
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+if [[ "$COMMAND" == tsc* ]] \
+   || [[ "$COMMAND" == *" tsc "* ]] \
+   || [[ "$COMMAND" == *" tsc" ]] \
+   || [[ "$COMMAND" == *"npx tsc"* ]]; then
+  echo "BLOCKED: do not run tsc locally. Compilation is handled by the BlueStep platform automatically on push." >&2
+  exit 2
+fi
+
+exit 0

package/templates/claude/hooks/prettier-on-save.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Auto-format TypeScript files after edit.
+# Enforces: rule R15 from CLAUDE.md.
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [[ "$FILE" == *.ts ]]; then
+  if ! command -v prettier >/dev/null 2>&1; then
+    echo "prettier-on-save: prettier not found on PATH. Install with: npm i -g prettier" >&2
+    exit 0
+  fi
+  prettier --write \
+    --print-width 120 \
+    --tab-width 2 \
+    --trailing-comma es5 \
+    --semi \
+    "$FILE" >&2
+fi
+
+exit 0

package/templates/claude/instructions/b6p-platform.md.template

@@ -0,0 +1,185 @@
+---
+description: BlueStep Platform overview — architecture (Relate/Connect/Manage/BsJs), the b6p CLI, sync, and component lifecycle. Read when orienting on the platform, working with the b6p CLI, or troubleshooting pull/push sync.
+applyTo: "**/.b6p_metadata.json"
+---
+
+# B6P Platform Workflow
+
+Platform orientation plus the workflow reference for sync, lifecycle, and the b6p CLI. Critical rules live in `CLAUDE.md`; on-demand detail lives in `index.md`.
+
+## Contents
+
+- [Platform architecture](#platform-architecture)
+- [Workspace model](#workspace-model)
+- [Data hierarchy](#data-hierarchy)
+- [Script types](#script-types)
+- [b6p CLI workflow](#b6p-cli-workflow)
+- [`.b6p_metadata.json`](#b6p_metadatajson)
+- [Files Claude must never edit](#files-claude-must-never-edit)
+- [Imports — verification flow](#imports--verification-flow)
+- [When the CLI fails](#when-the-cli-fails)
+- [When `B.commit()` is required](#when-bcommit-is-required)
+
+## Platform architecture
+
+The BlueStep Platform is three web applications over one shared data layer:
+
+- **Relate** — the database and configuration layer. Defines the data model (**Type → Category → Form → Field**) and holds all structured records.
+- **Connect** — end-user web pages that view or enter Relate data. Connect pages embed MergeReports.
+- **Manage** — the administrative counterpart to Connect; also hosts MergeReports.
+- **BlueStep.js (BsJs)** — the TypeScript library used to build the three component types: MergeReports, Endpoints, and Formulas. Patterns and APIs: `bsjs-development.md`.
+
+**Relate data model (configuration view).** A **Type** is a high-level entity (Individual, Organization, Event); a **Category** sub-classifies it (Staff, Volunteer, Client) — a record has one Type and zero or more Categories; a **Form** is a named group of fields; a **Field** is one data element. This is the *configuration* model; the runtime/storage nesting is in "Data hierarchy" below.
+
+### MergeReports are embedded, not standalone
+
+A MergeReport does not render a whole page. Connect (or Manage) supplies the page shell — `<html>`/`<head>`/`<body>`, site navigation, and branding — and the MergeReport's `pageContent()` output and `static/index.html` are injected into it. Write MergeReport frontend assuming the host page already exists; do not emit a full HTML document. Detail: `reference/merge-report-static-index.md`, `reference/component-library.md`.
+
+- `B.siteNavigation()` — the host site's navigation tree.
+- `B.isLayout("MANAGE")` — branch on whether the page is a Manage or Connect layout.
+- `B.optUser` / `B.user` — the logged-in user (`B.user` is null in scheduled scripts; see "Script types").
+
+## Workspace model
+
+The workspace is a **local copy** of components that live on the BlueStep platform. The platform is the source of truth.
+
+- New B6P components (MergeReport, Endpoint, Formula) are created **on the platform**, never locally.
+- Inside an existing component, creating new `.ts` files locally is fine — they ship to the platform on `push`.
+- The platform handles compilation. Local `tsc` is forbidden (enforced by hook).
+
+## Data hierarchy
+
+```
+Organization
+└── Unit (folder: U######)
+    └── BaseRecord
+        └── Form
+            └── Entry
+                └── Field
+```
+
+Queries, scripts, and permissions are scoped per Unit by default. A local project may pull components from multiple Units; each lives under its own `U######/` folder created by `b6p pull` on first pull.
+
+<!-- CONFLICT: U###### identity — this overview treats U###### as the Unit folder created by `b6p pull` (nested under an Organization). Brandon's platform-overview labels U###### as the Organization's own ID. Needs human resolution. -->
+
+## Script types
+
+| Type           | `B.user` available | Notes                                              |
+|----------------|--------------------|----------------------------------------------------|
+| Post-Save      | Yes                | Runs after a record is saved                       |
+| MergeReport    | Yes                | Page renderer; frontend in `static/`               |
+| Endpoint       | Yes                | HTTP-style request handler                         |
+| OnDemand       | Yes                | User-triggered formula — runs on the task pod; ~5 s scheduler-queue delay before start |
+| Field Formula  | Yes                | Computes a field's value                           |
+| Scheduled      | **No (null)**      | Runs on cron; guard `B.user` accordingly           |
+| Section Script | Yes                | Page section logic                                 |
+
+### OnDemand — async/background use cases
+
+OnDemand formulas execute on the **task pod**, making them appropriate for heavy or long-running work that should not run on a production pod. They are a good fit for async, background, or batch tasks.
+
+**Do not use OnDemand on a user's synchronous wait path.** The platform's scheduler queues the formula and starts it "as soon as possible," but that incurs a ~5 second delay before execution begins. For user-facing create or update flows where latency matters, use a synchronous task-pod **Endpoint** instead. See `bsjs-development.md` → "OnDemand / Field Formula" for code patterns.
+
+## b6p CLI workflow
+
+`b6p` ships as a devDependency of this project (`@bluestep-systems/b6p-cli`). Invoke it with `npx`, which resolves `node_modules/.bin/b6p` cross-platform — no global install, no shell or PATH detection. Run `npm install` once if `node_modules` is missing. The shape is:
+
+```
+npx b6p <subcommand> ...
+```
+
+### Pull a component
+
+```
+npx b6p pull "<DAV URL>"
+```
+
+**`b6p pull` takes a DAV URL, not a display name.** The URL is copied from the component's page in the BlueStep platform UI. There is no name-based lookup; the CLI has no way to find a component by its label.
+
+`b6p pull --help` reference:
+
+```
+Usage: b6p pull [options] [formula-url]
+
+Pull a script from a WebDAV location
+
+Options:
+  --file <path>       Derive source from local file metadata
+  --workspace <path>  Target workspace folder (default: cwd)
+```
+
+A successful first pull:
+
+- Creates the `U######/` folder (if not present) and the `<ComponentName>/` subfolder under it
+- Populates `draft/scripts/`, `draft/info/`, and (in older modules) `draft/objects/`
+- Populates `declarations/` with the platform-generated `.d.ts` files, including `declarations/index.d.ts` (field/query/form declarations)
+- Writes `.b6p_metadata.json` at the component root for future pulls/pushes
+
+Subsequent pulls verify per-file integrity and only rewrite files whose content changed.
+
+### Push a component
+
+The cleanest way to push an already-pulled component is `--file`, which lets the CLI derive the destination DAV URL from local `.b6p_metadata.json`:
+
+```
+npx b6p push --file "U######/<Component>/draft/scripts/app.ts"
+```
+
+Any file inside the component works as the `--file` argument; the CLI walks up to find `.b6p_metadata.json`. Same per-file integrity check applies — only changed files are uploaded. The platform compiles after receiving the push.
+
+### Fallback: VS Code extension
+
+If the `b6p` CLI fails (network, lock, auth), the VS Code **b6p extension** is an equivalent fallback for pull/push operations.
+
+## `.b6p_metadata.json`
+
+Auto-managed by the CLI. Tracks WebDAV IDs, last-pull / last-push timestamps, file hashes, and script keys. **Never edit manually.**
+
+## Files Claude must never edit
+
+Enforced by the `block-generated-files` hook:
+
+- Anything under `declarations/`
+- `B.d.ts`, `scriptlibrary.d.ts`, `Globals.d.ts`
+- (Treat `declarations/index.d.ts` as platform-generated — it regenerates on pull. `draft/objects/imports.ts` is a legacy artifact in older modules; do not edit it either.)
+
+If declarations are wrong, fix it on the platform and pull, not by editing locally.
+
+## Imports — verification flow
+
+Form-field imports are **per-component**. Each component independently declares which fields of a form it imports. A field present in component A's `declarations/index.d.ts` is not visible to component B unless B's import config was updated on the platform and B was pulled separately.
+
+Before referencing a query/form/field in code:
+
+1. Open **the component you are editing**'s `declarations/index.d.ts` and confirm the name exists. Another component's declarations file tells you nothing.
+2. In older modules, `draft/objects/imports.ts` may also exist as a legacy artifact — ignore it for verification; new declarations land in `declarations/index.d.ts`.
+3. If missing:
+   - Add the field to **this component's** form-import config on the platform.
+   - `npx b6p pull "<DAV URL>"` to regenerate this component's declarations.
+   - Then write the TypeScript reference.
+
+If N components all need the same new field, each one needs its own import-config update on the platform and a separate pull.
+
+Hallucinated names pass local edits but fail on platform compile after push.
+
+## When the CLI fails
+
+Common causes:
+
+- `npx b6p` cannot be resolved — the project's dependencies are not installed. Run `npm install` in the project root.
+- Network/auth issue with the platform. Re-authenticate with `npx b6p auth set`.
+- Local file lock. Close VS Code, retry.
+
+Fallbacks:
+
+1. The VS Code b6p extension provides the same pull/push operations through the editor UI.
+2. As a last resort, the platform UI lets you download/upload component files manually — but losing `.b6p_metadata.json` consistency makes future CLI sync fragile.
+
+## When `B.commit()` is required
+
+The platform commits automatically when a script finishes. Call `B.commit()` manually only when:
+
+- A new entry's `id` is needed before the script ends.
+- A subsequent read in the same script must see writes that haven't fired post-saves yet.
+
+In most scripts, manual `B.commit()` is unnecessary.