@bluestep-systems/bspecs 0.10.0

package/templates/claude/skills/spec-create/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: spec-create
+description: Start a new spec-driven feature. Creates requirements.md, then design.md, then tasks.md with explicit user approval between each phase. Use when the user wants to plan a new feature inside an existing component.
+---
+
+# /spec-create — Start a new feature spec
+
+A spec lives at `.claude/specs/<feature-name>/` and consists of three files: `requirements.md`, `design.md`, `tasks.md`. Each phase requires explicit user approval before moving to the next.
+
+## Prerequisite
+
+Read the `draft/README.md` of each component this feature will touch (see `CLAUDE.md` → "Reading module context — scoped to the task"). Read only the relevant components' READMEs, not the whole workspace. Those READMEs are your baseline for what each component does today — design decisions in Phase 2 should reference that knowledge, not re-derive it. If a relevant module's README is missing, ask the user to `/b6p-pull` it (or scaffold the README) before continuing.
+
+## Steps
+
+### Phase 0 — Setup
+
+1. Ask for:
+   - **Feature name** (kebab-case, e.g. `add-validation-on-intake`)
+   - **One-line description**
+2. Offer to **seed from a ClickUp ticket** if a ClickUp MCP is available — ask for the ticket URL or ID and fetch its description.
+3. Create `.claude/specs/<feature-name>/` directory.
+
+### Phase 1 — Requirements
+
+1. Copy `.claude/spec-templates/requirements.template.md` to `.claude/specs/<feature-name>/requirements.md`.
+2. Fill it in based on the user's description (and ClickUp ticket if provided).
+3. **STOP. Tell the user: "Requirements drafted at `.claude/specs/<feature-name>/requirements.md`. Review and approve before I proceed to design."**
+4. Wait for explicit approval ("approved", "ok", "next", etc.) before moving on.
+
+### Phase 2 — Design
+
+1. Copy `.claude/spec-templates/design.template.md` to `.claude/specs/<feature-name>/design.md`.
+2. Fill it in. **MUST include:**
+   - Which existing component(s) this touches
+   - **The required field "Does this require modifying the component on the platform?"** with answer Yes/No and details
+   - Approach summary
+   - Alignment with existing patterns from `.claude/instructions/bsjs-development.md`
+3. **STOP. Ask the user to approve design before tasks.**
+
+### Phase 3 — Tasks
+
+1. Copy `.claude/spec-templates/tasks.template.md` to `.claude/specs/<feature-name>/tasks.md`.
+2. Break the work into tasks. **Every task MUST start with a prefix:**
+   - `[PLATFORM]` for work done in the BlueStep UI (creating fields, queries, components, permissions, formula configs).
+   - `[CODE]` for work done in this workspace (TypeScript, static assets, README updates).
+3. Derive `[PLATFORM]` tasks from the **Platform-side impact** field of `design.md`. If the design says "yes, X needs to be created on the platform," there should be a `[PLATFORM]` task for each X. If the design says "no platform-side changes," there are no `[PLATFORM]` tasks (all tasks are `[CODE]`).
+4. **Order matters: `[PLATFORM]` tasks come before any `[CODE]` task that depends on them.** The ordering encodes the dependency — a `[CODE]` task that references a new field must come after the `[PLATFORM]` task that creates it.
+5. Each task MUST:
+   - Have the prefix `[PLATFORM]` or `[CODE]`
+   - Have a checkbox `[ ]`
+   - For `[CODE]`: reference specific file paths (e.g. `U######/IntakeForm/draft/scripts/validate.ts`)
+   - For `[PLATFORM]`: describe the artifact (e.g. "Create field `end_time` on form `Appointment`")
+   - NOT involve running `tsc`, editing `declarations/`, or creating B6P components locally
+6. **Fill in the `## Deployment` section** at the bottom: list every component whose `[CODE]` tasks touched it. One push per component.
+7. **STOP. Ask the user to approve tasks before implementation begins.**
+
+## After approval
+
+Tell the user to run `/spec-execute <feature-name> <task#>` to start implementing tasks one at a time.

package/templates/claude/skills/spec-execute/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: spec-execute
+description: Execute one task from a feature spec. By default delegates implementation to the b6p-task-implementer subagent (isolated context); pass --inline to implement in the main session. Updates the task checkbox when done. Use after `/spec-create` has produced an approved tasks.md.
+---
+
+# /spec-execute — Execute one task from a spec
+
+## Steps
+
+1. **Parse `$ARGUMENTS`** for feature name, task number, and an optional `--inline` flag (e.g. `add-validation-on-intake 3` or `add-validation-on-intake 3 --inline`). The flag may appear anywhere; strip it before reading the feature/task. If feature or task is missing, ask.
+   - **Default (no flag):** a `[CODE]` task is implemented by delegating to the `b6p-task-implementer` subagent, so the heavy declaration/source reads stay out of this session (see step 5).
+   - **`--inline`:** implement the task directly in this session — for trivial one-liners where spinning a fresh context isn't worth the re-read.
+2. **Load context:**
+   - Read `.claude/specs/<feature>/requirements.md`
+   - Read `.claude/specs/<feature>/design.md`
+   - Read `.claude/specs/<feature>/tasks.md`
+   - Identify the task at the given number
+
+   - Read the `draft/README.md` of the component(s) this task touches, if not already in context. (Don't pre-load READMEs for unrelated components.)
+3. **Check the task's prefix:**
+   - **`[PLATFORM]`** — STOP, do NOT touch code. Tell the user:
+     > Task <N> is a `[PLATFORM]` task: <description>. It must be done in the BlueStep UI. When it's complete, tell me and I'll mark it `[x]`, or call `/spec-execute <feature> <N+1>` to skip to the next task.
+   - **`[CODE]`** — proceed to step 4.
+   - **No prefix** — this is an older spec from before the convention. Warn the user once: "Task <N> has no `[PLATFORM]`/`[CODE]` prefix — treating as `[CODE]`. Consider updating the spec." Then proceed to step 4.
+4. **Verify prerequisites are done.** Scan tasks.md for any earlier `[PLATFORM]` task that is still `[ ]` (not checked). If any unchecked `[PLATFORM]` task exists *before* the requested task, STOP and tell the user:
+   > Task <N> may depend on `[PLATFORM]` task <earlier_N>: <description>. That platform work is not marked done yet. Confirm it's complete (I'll mark it `[x]`) or pick a different task.
+5. **Implement exactly one task.** No scope creep — touch only the files the task references, do not start the next task, apply rules from `CLAUDE.md` (no `tsc`, no `.writable()`, no editing `declarations/`, no new components locally).
+
+   **Default — delegate to the `b6p-task-implementer` subagent:**
+   - Spawn the `b6p-task-implementer` subagent (via the Task/Agent tool) and give it the feature name and this task number. It reads the spec, the component's `declarations/`, and the relevant `instructions/` files in its **own** context, implements the one task, and returns a structured summary — keeping that bulk out of this session.
+   - When it returns, show the user its summary and the **git diff** of what changed (`git diff` / `git status` for the touched files) so the change is reviewable here.
+   - The subagent does **not** mark the checkbox or chain other agents — the steps below (verify, mark, README sync, STOP) stay in this session.
+
+   **`--inline` — implement here:** do the edits directly in this session (the prior behavior), then continue to 5.5.
+
+5.5. **Verify IDE diagnostics.** Before marking the task done, check the most recent `ide_diagnostics` blocks injected by the `PostToolUse` hook after each `Edit`/`Write` (these fire on the subagent's edits too). Also weigh anything the subagent listed under **Flags for the human**.
+   - If any entry has `severity: "Error"` in a file this task touched: **STOP.** Fix the error and re-verify before continuing. Do not mark the task done with pending errors.
+   - `Warning` / `Information` entries (including spell-checker) can be ignored **unless** they point to a real problem — review before dismissing.
+   - If an `Error` cannot be reproduced or looks like a false positive, report it explicitly: "The IDE reports `<error>` but I think it's a false positive because `<reason>` — should I continue?"
+6. **Mark the task done:** update `.claude/specs/<feature>/tasks.md` — change `[ ]` to `[x]` for the completed task.
+7. **Check the affected module's `draft/README.md`:**
+   - If this task changed behavior that the README describes (Overview, Behavior, Fields used, External dependencies), update the README in the same change so the platform doc stays in sync.
+   - If the change is internal-only (refactor, comment, log message) and doesn't alter documented behavior, leave the README alone.
+   - When unsure, ask the user: "This task changed `<what>` — should I reflect it in `draft/README.md`?"
+8. **STOP. Tell the user: "Task <N> done. Review and approve before /spec-execute <feature> <N+1>."** Do not auto-continue. In the same message, surface the implementer's summary + diff (default path) and offer the optional, user-invoked follow-ups — these never fire automatically:
+   - `@b6p-commenter` — update the component's `draft/README.md` from the new code.
+   - `@b6p-code-review` — a BlueStep-aware, report-only review of the change.
+
+## When the user says a `[PLATFORM]` task is done
+
+If the user comes back and says "I did task <N> on the platform", just edit `tasks.md` to mark it `[x]`. No code changes, no push. The task is closed.

package/templates/claude/skills/spec-status/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: spec-status
+description: Show progress of all feature specs in `.claude/specs/`. Use when the user wants a summary of what's in flight.
+---
+
+# /spec-status — Show progress across all active specs
+
+## Steps
+
+1. List directories under `.claude/specs/`.
+2. For each feature, read `.claude/specs/<feature>/tasks.md`.
+3. Count `[x]` (done) and `[ ]` (pending) checkboxes.
+4. Print a summary, e.g.:
+
+```
+add-validation-on-intake   3 / 7 tasks done
+refactor-merge-renderer    1 / 5 tasks done
+```
+
+5. If a spec has no `tasks.md` yet, mark it as "in design".

package/templates/claude/skills/task-comment/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: task-comment
+description: Draft a standardized implementation comment for a ClickUp task after a fix or feature is shipped. Handles both org-propagated (component-based) and direct (code-only) changes.
+---
+
+# /task-comment — Draft a ClickUp implementation comment
+
+## Steps
+
+1. **Ask the user to paste the ClickUp task link or ID.**
+   - Use the ClickUp MCP to fetch the task (`clickup_get_task`) and read its name, description, list, and status.
+
+2. **Infer the change type from the task name prefix:**
+   - Starts with `Bug -` or `Bug —` → type = **Fix**
+   - Starts with `Feature -` or `Feature —` → type = **Feature**
+   - Anything else → type = **Update**
+
+3. **Derive the summary** from the task name and description — one sentence capturing what the bug/issue/feature was. Do not ask the user for this.
+
+4. **Ask one question:**
+   > Does this change need to be propagated to other orgs? (yes / no)
+
+5. **Collect the remaining details based on the answer:**
+
+   **If yes (propagated — component change):**
+   - Component name (e.g. `Audits`, `Appointments`)
+   - Affected file(s): path(s) relative to the component (e.g. `draft/scripts/utils/entryHelper.ts`)
+   - Orgs deployed to (comma-separated list)
+   - What changed and why (free-form, 1–4 sentences)
+
+   **If no (direct — code/API/formula fix):**
+   - What changed mechanically (1–3 sentences)
+   - Root cause, if known (1–2 sentences, or "N/A")
+   - Net effect / user-visible outcome (1 sentence)
+   - Any caveats or known limitations (optional)
+
+6. **Produce the formatted comment. Do not post it — print it directly in your response (NOT in a code block) so the user can copy the rich text and paste it into ClickUp with bold formatting intact.**
+
+---
+
+## Output formats
+
+ClickUp does not render markdown. Use `**bold**` only for structural labels — ClickUp will receive the bold formatting when the user copies and pastes rich text from the response. Body text stays plain.
+
+The comment always has three sections separated by blank lines: **Summary**, **Change**, and (if propagated) **Components**.
+
+### Propagated (yes)
+
+**Summary:** <one sentence derived from the task name/description>
+
+**<Type> implemented**
+
+<What changed and why>
+
+**Component:** <ComponentName>
+
+<ComponentName>
+<file/path.ts>
+
+**Deployed to:** <Org1>, <Org2>, <Org3>.
+
+---
+
+- `<Type>` = Fix / Feature / Update (from step 2)
+- If multiple files, list each on its own line under the component name
+- If only one org, write "**Deployed to:** <Org>." (no comma)
+
+### Direct (no)
+
+**Summary:** <one sentence derived from the task name/description>
+
+**<Type> shipped (<YYYY-MM-DD>)**
+
+<What changed mechanically>
+
+**Root cause:** <root cause, if provided>
+
+**Net effect:** <user-visible outcome>
+
+**Caveat:** <caveat, if provided>
+
+---
+
+- `<Type>` = Fix / Feature / Update (from step 2)
+- Omit the **Root cause:** line if the user said N/A
+- Omit the **Caveat:** line if none provided
+- Use today's date for `<YYYY-MM-DD>`
+
+---
+
+## Notes
+
+- Never post to ClickUp automatically. Always print the comment directly in the response (no code block) so the user can copy rich text and paste it into ClickUp with bold formatting intact.
+- Do not add a greeting, sign-off, or closing line.
+- Keep the tone matter-of-fact. No "Great news!" or "Happy to report".
+- If the task name has no recognizable prefix, default to **Update** and don't ask the user to clarify.

package/templates/claude/spec-templates/design.template.md

@@ -0,0 +1,36 @@
+# Design — [Feature Name]
+
+**Status:** Drafting | Approved | Superseded
+
+## Component(s) affected
+
+Which existing components this feature touches.
+
+- `U######/ComponentName` — what changes
+
+## Platform-side impact
+
+**Does this change require modifying the component on the BlueStep platform? (Yes / No)**
+
+- If **Yes**: list what must be created or changed on the platform (new fields, new queries, new component-level config, permission changes, etc.). These must happen on the platform first; then we pull and proceed.
+- If **No**: confirm the work is fully inside `draft/scripts/` of existing component(s).
+
+## Approach
+
+High-level summary of how this will be implemented. Reference existing patterns from `.claude/instructions/bsjs-development.md` where applicable.
+
+## Data flow
+
+How data moves through the change. Which fields are read; which are written. Which queries are used.
+
+## Edge cases
+
+- ...
+
+## Alignment with existing patterns
+
+Which patterns from `bsjs-development.md` are being applied. If a new pattern is introduced, justify it.
+
+## Risks
+
+What could go wrong; what's the rollback if a push breaks the platform side.

package/templates/claude/spec-templates/requirements.template.md

@@ -0,0 +1,26 @@
+# Requirements — [Feature Name]
+
+**Status:** Drafting | Approved | Superseded
+
+## Context
+
+What problem is this solving? Who asked for it? (Link to ClickUp ticket if relevant.)
+
+## User stories
+
+- As a [role], I want [capability], so that [outcome].
+- ...
+
+## Acceptance criteria
+
+- [ ] Criterion 1 (observable from the user's perspective)
+- [ ] Criterion 2
+- [ ] ...
+
+## Out of scope
+
+What this feature explicitly does NOT include.
+
+## Open questions
+
+- ...

package/templates/claude/spec-templates/tasks.template.md

@@ -0,0 +1,37 @@
+# Tasks — [Feature Name]
+
+**Status:** Drafting | Approved | In progress | Complete
+
+Each task must reference specific file paths or platform artifacts and be small enough to ship as one coherent unit. Tasks must NOT involve:
+
+- Running `tsc` locally
+- Editing `declarations/` or any `.d.ts` file
+- Creating new B6P components locally (those go on the platform first)
+
+## Task prefix convention
+
+Every task starts with one of two prefixes that says **where** the work happens:
+
+- `[PLATFORM]` — done in the BlueStep UI (creating a field, query, formula, component-level config, permissions, etc.). **Not executable by `/spec-execute`** — the user does these manually. Must be listed before any `[CODE]` task that depends on them, so the ordering encodes the dependency.
+- `[CODE]` — done in this workspace (TypeScript, static assets, README updates). **Executable by `/spec-execute`**.
+
+If the design says "no platform-side changes needed," every task is `[CODE]` and the prefix is still required (no implicit type).
+
+## Tasks
+
+- [ ] **1. [PLATFORM]** [Short description, e.g. "Create field `appointment_end_time` on form `Appointment`"]
+- [ ] **2. [CODE]** [Short description] — files: `U######/Component/draft/scripts/foo.ts`
+- [ ] **3. [CODE]** [Short description] — files: `U######/Component/draft/scripts/bar.ts`, `U######/Component/draft/README.md`
+
+(Repeat as needed. Keep tasks small enough that one `/spec-execute` invocation covers exactly one.)
+
+## Deployment
+
+Once all `[CODE]` tasks above are checked, push the affected components back to the platform. Use `/b6p-push` or run manually:
+
+- `U######/<ComponentName>` — `npx b6p push --file "U######/<ComponentName>/draft/scripts/app.ts"`
+- (List every component touched by `[CODE]` tasks. One push per component.)
+
+## Verification
+
+How to confirm the feature works once deployed (UI flow to exercise, expected log output, query to run on the platform, etc.).

package/templates/module/README.md.template

@@ -0,0 +1,46 @@
+# [Component displayName]
+
+<!--
+This README documents what the component does today. It lives at
+draft/README.md inside the component folder so it ships to the BlueStep
+platform on push, which means anyone who pulls the component gets the doc.
+
+This file is NOT for planning new work — use `/spec-create` for that
+(specs live under .claude/specs/<feature-name>/).
+
+When `/b6p-pull` scaffolds this file, it infers what it can from the
+component's code (app.ts), metadata (draft/info/metadata.json), and
+static assets (for MergeReports). Sections it cannot infer are left
+empty or marked "TODO" — fill them in before editing code.
+-->
+
+## Overview
+
+[One paragraph: what this component does and why it exists.]
+
+## Type
+
+[Endpoint | MergeReport | Post-Save | OnDemand | Scheduled | Formula]
+
+[For Endpoint: list paths, allowed methods, auth model.]
+[For MergeReport: list pages/sections rendered, whether it owns frontend.]
+[For Post-Save: list the form(s) that trigger it.]
+[For Scheduled: list the cron cadence and what it does.]
+
+## Fields used
+
+| FID     | Display name | Form     | Access       |
+|---------|--------------|----------|--------------|
+| fid_xxx | …            | FormName | read / write |
+
+## Behavior
+
+[Bulleted description of what the component does at runtime. One bullet per coherent behavior.]
+
+## External dependencies
+
+[Outbound HTTP endpoints, other B6P components this one calls or expects.]
+
+## Edge cases / known gotchas
+
+[Anything non-obvious that future-you or another dev should know before editing.]

package/templates/root/.gitignore.template

@@ -0,0 +1,14 @@
+# Dependencies
+node_modules/
+
+# Environment
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+*.swp
+*.swo

package/templates/root/.prettierrc.template

@@ -0,0 +1,8 @@
+{
+  "printWidth": 120,
+  "tabWidth": 2,
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": false,
+  "bracketSpacing": true
+}

package/templates/root/CLAUDE.md.template

@@ -0,0 +1,157 @@
+# {{CLIENT_NAME}} — {{PROJECT_NAME}}
+
+**Scaffolded:** {{SCAFFOLD_DATE}}
+
+## Project description
+
+{{PROJECT_DESCRIPTION}}
+
+## Workspace model
+
+This workspace is a **local copy** of components that live on the BlueStep platform. The platform is the source of truth.
+
+- A project may span **one or more Unit folders** (`U######/`). Unit folders are created by `b6p pull` — never by hand.
+- Each Unit folder contains one or more **components** of any type (MergeReport, Endpoint, Formula, OnDemand, Scheduled, Post-Save). A single project mixes types freely.
+- New B6P **components** are created on the platform, never locally. Inside an existing component, creating new `.ts` files locally is fine.
+- Sync with the platform via `b6p pull "<DAV URL>"` (first pull or re-sync) and `b6p push --file "<component-path>/..."` (deploy). See the Sync workflow section below for the exact invocation.
+
+## Critical rules (always apply)
+
+1. **NEVER** edit `declarations/`, `B.d.ts`, `scriptlibrary.d.ts`, `Globals.d.ts` — platform-generated. _(enforced by hook)_
+2. **NEVER** use `.writable()`. Field writability is configured on the platform, not requested in code.
+3. **NEVER** run `tsc` locally. Compilation is handled by the platform on push. _(enforced by hook)_
+4. **NEVER** create new B6P components locally. Create them on the platform first, then pull.
+5. **ALWAYS** invoke `b6p` as `npx b6p` — it resolves the project's local `@bluestep-systems/b6p-cli` cross-platform, with no global install or shell/PATH detection. Run `npm install` first if `node_modules` is missing.
+6. In **MergeReports**: frontend (HTML/CSS/JS) lives in `static/`, NOT in `scripts/`.
+7. The workspace is a local copy — the platform is source of truth.
+8. **NEVER** fabricate query/form/field references. They must exist in the **specific component's** `declarations/index.d.ts` before use. Form-field imports are per-component — a field visible in component A is not visible in component B unless B's import config was updated on the platform and B was pulled. If missing, update that component's import config on the platform and pull it.
+
+## Module structure
+
+```
+<project-root>/
+├── U######/                       ← Unit folder (created by `b6p pull`, one per unit)
+│   └── ComponentName/             ← any component type — read metadata.json to identify
+│       ├── declarations/          ← platform-generated, DO NOT EDIT
+│       └── draft/
+│           ├── README.md          ← what this module does today — read before editing
+│           ├── scripts/           ← TypeScript source (BsJs)
+│           ├── objects/           ← legacy: imports.ts may exist in older modules
+│           ├── static/            ← MergeReport only: HTML, CSS, client JS
+│           └── info/              ← config.json, metadata.json, permissions.json
+└── U######/                       ← another unit, more components — same shape
+```
+
+Component type is encoded in `draft/info/metadata.json` (and the matching `config.json`). When you need to know whether a component is an Endpoint, MergeReport, etc., read those — don't infer from folder names.
+
+**Two distinct docs, by lifecycle:**
+
+- `<Component>/draft/README.md` — describes what the module **does today**. Lives inside `draft/` so it ships to the platform on push; anyone who pulls the module gets the doc. Scaffolded automatically by `/b6p-pull` when missing; if you change documented behavior, update the README in the same change.
+- `.claude/specs/<feature>/` — describes what you are about to **change or add** (requirements → design → tasks). Per feature, not per component. Created by `/spec-create`.
+
+## The `B` object (platform API)
+
+| Namespace     | Purpose                                       |
+|---------------|-----------------------------------------------|
+| `B.net`       | Outbound HTTP (`B.net.fetch()`)               |
+| `B.util`      | Utilities (logging, parsing, formatting)      |
+| `B.io`        | I/O, WebSocket push (`B.io.sendMessage()`)    |
+| `B.db`        | Database access                               |
+| `B.time`      | Date/time — use this instead of native `Date` |
+| `B.queries`   | Query objects defined on the platform         |
+| `B.exports`   | Cross-formula data sharing                    |
+| `B.user`      | Current user (null in scheduled/cron scripts) |
+| `B.commit()`  | Force a mid-script transaction commit         |
+
+Full API patterns: read `.claude/instructions/bsjs-development.md` when writing or reviewing BsJs (load on demand — it is not auto-imported).
+
+## Reading module context — scoped to the task
+
+**Read `draft/README.md` only for the component(s) the current task touches** — not every component in the workspace. A workspace can hold dozens of components totalling thousands of lines of README; loading all of them into every session is wasteful and slow.
+
+When a task names (or clearly implies) one or more components, read those READMEs before suggesting or implementing anything. Each module's `draft/README.md` describes what the module does today; it was scaffolded by `/b6p-pull` from the code, so treat it as the source of truth for current behavior. If you're unsure which component a request maps to, ask — don't pre-load everything to be safe.
+
+To discover which components exist without reading their READMEs, list the `U######/*/` directories or read a single `draft/info/metadata.json`.
+
+If the component a task touches has no `draft/README.md` (or it's empty boilerplate), ask the user to run `/b6p-pull <DAV URL>` against that component to scaffold one. Don't proceed to edit code in a module whose README is missing.
+
+## Documentation and planning workflow
+
+Two distinct artifacts, separated by lifecycle:
+
+- **`<Component>/draft/README.md`** — what the module **does today**. Read it for the component(s) a task touches (see "Reading module context" above). Update only when documented behavior changes. Ships to the platform on push, so other devs who pull the module get the doc.
+- **`.claude/specs/<feature>/`** — what we're about to **change or add** (requirements → design → tasks). Per feature, not per component. Created by `/spec-create`. Archived/deleted when the feature is done.
+
+## Skill quick reference
+
+Available skills (full docs in `.claude/skills/<name>/SKILL.md`):
+
+| Skill | When the user wants to… |
+|---|---|
+| `/b6p-pull <DAV URL>` | Bring a component down from the platform (first pull or re-sync) |
+| `/b6p-push <component>` | Send local changes back to the platform |
+| `/b6p-audit <component>` | Compare local vs. platform, see what diverged (read-only) |
+| `/spec-create <feature-name>` | Plan a new feature (requirements → design → tasks) |
+| `/spec-execute <feature> <task#>` | Implement one specific task from a spec |
+| `/spec-status` | Show progress across all in-flight specs |
+| `/bug-fix` | Quick workflow for clearly-scoped bugs (no full 3-phase spec) |
+
+### Mandatory routing rule (spec-driven changes)
+
+**Before editing any TypeScript or static file under `U######/<Component>/draft/`**, you MUST route through one of these workflows — never edit directly because the user asked "change X":
+
+1. If the user describes a **feature** (new behavior, anything that requires designing): require `/spec-create` first. If a spec already exists for it (`.claude/specs/<feature>/tasks.md`), use `/spec-execute`.
+2. If the user describes a **bug** (incorrect existing behavior): require `/bug-fix` first.
+3. If the user explicitly says "this is trivial, just do it" or similar (typo fix, log message, comment, rename of a local variable): you may skip the workflow, but say what you're about to do and wait for "ok" before touching files.
+
+The point: the spec/bug workflow exists so changes are reviewed and traceable. Skipping it loses the value of the system. Ask once if a request is ambiguous; never assume.
+
+### Soft routing (everything else)
+
+For sync, status, and audit operations, infer naturally from what the user asks and propose the matching skill. Examples:
+
+- "pulleamelo" / "trae el módulo X" → suggest `/b6p-pull <URL>` (ask for URL if not provided).
+- "pushea esto" / "subilo" → `/b6p-push <component>`.
+- "¿cambió algo en la plataforma?" / "¿esto está sincronizado?" → `/b6p-audit <component>`.
+- "¿cómo van los specs?" / "¿qué tengo en curso?" → `/spec-status`.
+
+You don't need explicit confirmation to invoke these — they're either read-only or already have their own internal confirmation steps.
+
+## Sync workflow (b6p CLI internals)
+
+The skills above wrap these commands. You can run them directly if you need to, but prefer the skills for guidance and consistency.
+
+`b6p` ships as a devDependency of this project (`@bluestep-systems/b6p-cli`). Invoke it with `npx b6p`, 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.
+
+- **Pull (DAV URL required):** `npx b6p --yes pull "<DAV URL>"`. The DAV URL is copied from the component's page in the BlueStep platform UI — `b6p pull` does not accept display names. First pull creates the `U######/` folder and the component skeleton.
+- **Push (file-driven):** `npx b6p --yes push --file "U######/<Component>/draft/scripts/app.ts"`. `--file` lets the CLI derive the destination from local metadata.
+- **Audit (read-only):** `npx b6p --yes --json audit --file "U######/<Component>/draft/scripts/app.ts"`. Lists files that differ between local and platform.
+- Always pass `--yes` so the CLI does not show interactive prompts that Claude cannot answer.
+- Both pull and push verify per-file integrity and only transfer files whose content changed.
+- If `npx b6p` cannot be resolved, run `npm install` in the project root (see the "Install dependencies" section of the project's `README.md`). For other errors, the VS Code b6p extension is an equivalent fallback.
+
+## Self-improvement
+
+If you discover a B6P rule or pattern that is not documented here:
+
+1. Apply it for the current task.
+2. Capture the rule in the right place:
+   - A must-always rule → the Critical rules list in this `CLAUDE.md`.
+   - High-frequency platform/BsJs material → the matching overview (`.claude/instructions/b6p-platform.md` or `bsjs-development.md`).
+   - A single-topic detail or sharp edge → a new or existing atomic file under `.claude/instructions/{reference,conventions,gotchas}/`, and add (or update) its one-line entry in `.claude/instructions/index.md` so it's discoverable.
+3. Note in your response: "Added rule: <description>".
+
+## Deep reference
+
+The deep platform and BsJs reference lives under `.claude/instructions/`. None of it is auto-imported — read on demand, only when the task needs it, so it doesn't sit in context every session.
+
+**For any platform or BsJs detail, consult `.claude/instructions/index.md` first.** The index is the manifest of single-topic files (`reference/`, `conventions/`, `gotchas/`), each with a one-line "load when…" trigger; open it to pick the right file, then read just that file. It also gives a `grep -ri "<term>" .claude/instructions/` route for term-level lookups.
+
+The two on-demand overviews come first for high-frequency material:
+
+- `.claude/instructions/bsjs-development.md` — BsJs/TypeScript patterns, the `B` API, TS narrowing pitfalls. Read when writing or reviewing component code.
+- `.claude/instructions/b6p-platform.md` — platform architecture and concepts (Relate/Connect/Manage, component types, sync model, declarations). Read when a task hinges on platform behavior.
+
+Reach past the overviews into the indexed atomic files when you need a specific topic the overview only summarizes.
+
+The critical rules above (declarations, `.writable()`, `tsc`, `npx b6p`, per-component imports) are the must-always-apply subset — you don't need the deep files to honor them.

package/templates/root/README.md.template

@@ -0,0 +1,58 @@
+# {{CLIENT_NAME}} — {{PROJECT_NAME}}
+
+{{PROJECT_DESCRIPTION}}
+
+## Layout
+
+A project is a collection of B6P components, organised by Unit. `b6p pull "<DAV URL>"` creates the `U######/` folder and the component skeleton on first pull — you do not create Unit folders by hand. A single project commonly spans multiple Unit folders, and each Unit folder holds components of different types (Endpoint, MergeReport, Formula, etc.).
+
+## Prerequisites
+
+### Install dependencies (one-time)
+
+The `b6p` CLI ships as a dev dependency of this project (`@bluestep-systems/b6p-cli`). `bspecs` runs `npm install` for you when it scaffolds the project, so this is usually already done. If that install was skipped or failed (most often because `GITHUB_TOKEN` was not set in the scaffolding shell), run it yourself:
+
+```bash
+npm install
+```
+
+The b6p skills (`/b6p-pull`, `/b6p-push`, `/b6p-audit`) then invoke it as `npx b6p …`, which resolves `node_modules/.bin/b6p` cross-platform — no global install and no shell/PATH detection.
+
+`npm install` needs a `~/.npmrc` granting access to the `@bluestep-systems` scope on GitHub Packages (a PAT with `read:packages`, exposed as `GITHUB_TOKEN`). The project's `.npmrc` maps the scope; the token is read from your environment.
+
+### Configure platform credentials (one-time)
+
+Set your BlueStep platform credentials once per machine:
+
+```bash
+npx b6p auth set
+```
+
+Without this, the first `npx b6p pull` will prompt for credentials interactively, which Claude Code cannot answer — the call will hang. Run `auth set` before invoking `/b6p-pull`.
+
+The **VS Code b6p extension** (`bsjs-push-pull`, published in the Marketplace) is an equivalent fallback for pull/push when the CLI is not available.
+
+The DAV URL passed to `b6p pull` is copied from the component's page in the BlueStep platform UI; `b6p pull` does **not** accept display names.
+
+## Daily workflow
+
+1. **Pull a component:** `/b6p-pull <DAV URL>` (Claude skill — also scaffolds `draft/README.md` from metadata + code when missing) or `npx b6p pull "<DAV URL>"`. The Unit folder is created automatically if it does not exist yet.
+2. **Read the component's `draft/README.md`** before editing.
+3. **Edit code** under `U######/<component>/draft/scripts/` — never `declarations/`.
+4. **Push back:** `/b6p-push <component>` (Claude skill) or `npx b6p push --file "U######/<component>/draft/scripts/app.ts"`.
+
+## New feature workflow
+
+Use Claude skills for spec-driven development:
+
+- `/spec-create <feature>` — generate requirements/design/tasks with approval gates.
+- `/spec-execute <feature> <task#>` — implement one task.
+- `/spec-status` — see progress.
+- `/bug-fix` — shorter workflow for bug fixes.
+
+## Configuration
+
+- `CLAUDE.md` — main Claude context (critical rules, workspace model, API summary).
+- `.claude/instructions/` — deep technical reference.
+- `.claude/hooks/` — automatic guardrails (block edits to `declarations/`, block `tsc`, auto-format).
+- `.claude/skills/` — slash commands you can invoke (`/b6p-pull`, `/spec-create`, etc.).

package/templates/root/package.json.template

@@ -0,0 +1,15 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.0.0",
+  "description": "{{PROJECT_DESCRIPTION}}",
+  "private": true,
+  "scripts": {
+    "b6p": "b6p"
+  },
+  "devDependencies": {
+    "@bluestep-systems/b6p-cli": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}