spec-create git:20261103.5c82982A

Immutable. This exact content never changes and is served at /api/v1/blob/8d82481ba29f0c60.

---
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 (the project's `AGENTS.md` says how to read the workspace 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.

**Setup preflight.** Look at the working directory's rules file. Any of these means the folder is not ready: no `AGENTS.md` at all; an `AGENTS.md` with **no** `<!-- bluestep-tools rules-template N -->` marker (a file from before the marker — version 1); a marker **below** the one in `${CLAUDE_PLUGIN_ROOT}/skills/b6p-setup/templates/AGENTS.md.template`; or a `CLAUDE.md` holding real rules with no `AGENTS.md` beside it. In that case **invoke the `/b6p-setup` skill** (through the Skill tool, so its own tool allowances apply — never re-implement it from memory; its file is `${CLAUDE_PLUGIN_ROOT}/skills/b6p-setup/SKILL.md`) for its step 2, then continue with this request. It performs what has one correct answer and asks only what a file with the user's own lines raises — an old rules file with project rules, a populated `CLAUDE.md`, a folder with no BlueStep signal — and those questions are asked before this request goes on. If `b6p` is missing, or `$B6PT_TOKEN` is unset when a `[PLATFORM]` op needs it, run its step 1 first and hand over the commands only a person can run. Never drop the request: if the user would rather go on without setup, continue and say in the report that `/b6p-setup` is there when they want it. The one exception is the user answering "Not a BlueStep repo" or opting the plugin out — then this request ends with that answer, and say so.

## 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_PLUGIN_ROOT}/skills/spec-create/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_PLUGIN_ROOT}/skills/spec-create/spec-templates/design.template.md` to `.claude/specs/<feature-name>/design.md`.
2. **If the feature involves AI, agents, model calls, generation, or AI tools** — read `${CLAUDE_PLUGIN_ROOT}/skills/bluestep-reference/reference/ai-services.md` **before** choosing an architecture, and prefer the platform's tenant-metered `B.ai` over a third-party provider unless the design states a reason not to.
3. 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 the `bluestep-reference` skill's `bsjs-development.md` overview (`${CLAUDE_PLUGIN_ROOT}/skills/bluestep-reference/bsjs-development.md`)
4. **STOP. Ask the user to approve design before tasks.**

### Phase 3 — Tasks

1. Copy `${CLAUDE_PLUGIN_ROOT}/skills/spec-create/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`). When a `[CODE]` task reads an imported field, **name which query/record it reads the field through** (e.g. "read `end_time` via `appointments` (`Record_appointments`)"), so the scope is verifiable against `declarations/`.
   - For `[PLATFORM]`: describe the artifact (e.g. "Create field `end_time` on form `Appointment`"). For an **import** item (query/form/field), **state its scope explicitly** — either "current record" (valid **only** if the component has a primary form / record type attached) or the exact named query/queries it is imported on. Never write a bare "add the X import." See the `bluestep-reference` skill's `import-scope.md` (`${CLAUDE_PLUGIN_ROOT}/skills/bluestep-reference/reference/import-scope.md`) for current-record-vs-named-query scoping and the every-reachable-query rule.
   - NOT involve running `tsc`, editing `declarations/`, or creating B6P components locally
6. **Mark every task `[mechanical]`, `[routine]` or `[judgment]`.** The marker goes right after the prefix (e.g. `**7. [CODE] [mechanical]** Wire component #4 the same way as task 3 — files: …`). It says how much judgment the task needs, and `/spec-execute` picks the implementer's model tier from it:
   - `[mechanical]` — repeats a pattern already proven by an **earlier task in the same spec** (or an explicitly named pilot), makes **no new design decisions**, adds **no new imports or schema** — pure copy-adapt-verify. The first instance of any pattern is never `[mechanical]`.
   - `[routine]` — a known shape with new content: a new file or function following a pattern this project already uses, with no design choice left open.
   - `[judgment]` — a design choice, UI behaviour, a pattern's first instance, or anything the design left to the implementer.
   - `[PLATFORM]` tasks run in the main session; mark them anyway — there the marker is effort information for whoever does them.

   The user's tasks-phase review is the approval gate for the cheaper tiers — changing markers is part of reviewing tasks.md. When in doubt, mark up (`[routine]` over `[mechanical]`, `[judgment]` over `[routine]`); an unmarked task runs as `[judgment]`.
7. **Fill in the `## Deployment` section** at the bottom: list every component whose `[CODE]` tasks touched it. One push per component.
8. **STOP. Ask the user to approve tasks before implementation begins.**

## After approval

Tell the user to start implementing tasks one at a time. Present the first command on its own line as a **fenced code block** — with the real feature name and first task number filled in, e.g.

```
/spec-execute add-validation-on-intake 1
```

so the terminal UI renders a copy button. Do **not** bury the command in inline backticks inside a sentence (no copy button there).