mcpField
R
rs-init

rs-init

github.com/rootspecDevelopment060 installsUpdated 27w ago
Repository

About rs-init

A setup skill for developers initializing RootSpec in a project. It scans the repository, bootstraps specification files and prerequisites, adapts detected project tooling, and verifies the result before handing off to `/rs-spec`.

Key features

  1. 01Scan project and spec state
  2. 02Bootstrap RootSpec files and scripts
  3. 03Detect and configure prerequisites
  4. 04Wire up the Cypress reporter
  5. 05Verify initialization

Use cases

  1. 01Initialize RootSpec in a new project
  2. 02Resume an incomplete initialization
  3. 03Configure prerequisites in an existing setup

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/rootspec/rootspec --skill rs-init

After installing, type/rs-initin Claude Code to confirm it loaded.

Details

From the project README

You are setting up a project to use RootSpec. Start by telling the developer what you're about to do:

"I'll set up RootSpec for this project — create the spec directory, copy the framework files, and configure prerequisites (dev server, test runner, etc.). This takes a minute or two."

Step 1: Scan the project

Understand what exists. Run these from the project root:

bash "$(dirname "$0")/../rs-shared/scripts/scan-spec.sh" .
bash "$(dirname "$0")/../rs-shared/scripts/scan-project.sh" .

If these paths don't resolve, find the scripts by searching for scan-spec.sh in the skills directory.

Based on the output, determine the situation:

  • Fresh init — no .rootspec.json, no rootspec/ directory. Most common case.
  • Partial init — some files exist but others are missing (interrupted previous init).
  • Re-init — .rootspec.json exists. If the version is behind the bundled framework, suggest /rs-update instead. Otherwise, ask the developer what they want to update. Do NOT overwrite existing spec files (01-05). You may update 00.AXIOMS.md and 00.FRAMEWORK.md to the latest bundled versions if the developer confirms.
  • Already initialized — everything exists. Tell the developer and suggest /rs-spec instead.

Report what you found before proceeding.

Step 2: Bootstrap the project

Run the bootstrap script to create the spec directory, base files, prerequisites, and .rootspec.json:

bash "$(dirname "$0")/../rs-shared/scripts/bootstrap-init.sh" . "$(dirname "$0")/../rs-shared"

If this path doesn't resolve, find the script by searching for bootstrap-init.sh in the skills directory.

This creates everything needed for a greenfield project: rootspec/ with framework files, scripts/dev.sh, scripts/test.sh, .githooks/pre-commit, scripts/release.sh, Cypress reporter, .rootspec.json, and package.json. Files that already exist are skipped.

Step 3: Detect and adapt prerequisites

Run the detection script to check what the bootstrap created vs what the project already had:

bash "$(dirname "$0")/../rs-shared/scripts/detect-prerequisites.sh" .

The script outputs DEV_SERVER=, PRE_COMMIT_HOOK=, RELEASE_SCRIPT=, VALIDATION_SCRIPT= lines with detected paths or none.

Read ../rs-shared/fragments/prerequisites.md for the full reference on what each prerequisite is.

Package.json rule: NEVER write the dependencies or devDependencies sections of package.json directly. Always use npm install <pkg> or npm install --save-dev <pkg> to add packages — npm manages the dependency tree. You may edit the scripts section directly (e.g., to add dev:start).

Report what was detected. For brownfield projects, adapt the bootstrap defaults:

  • Dev server — scripts/dev.sh and scripts/preview.sh ship with empty DEV_CMD/PREVIEW_CMD and a recursion guard. They will hard-fail until populated. Do not set them here — /rs-impl runs detect-stack.sh and writes the framework binary in based on the detected stack (or the captured-original from the project's pre-bootstrap package.json, preserved in .rootspec.json prerequisites.detected). Mention this in the handoff: "Run /rs-impl to populate dev/preview wrappers and create conventions."
  • Existing prerequisites — if the project already had a dev server, test runner, etc., update .rootspec.json to point to them instead of the bootstrap defaults.
  • Package.json scripts — add dev:start, dev:stop, dev:restart entries if not already present. The dev, preview, and start scripts MUST go through ./scripts/dev.sh / ./scripts/preview.sh. bootstrap-init.sh writes them this way for greenfield; for brownfield, rewrite any existing dev/preview/start script to route through the wrapper. (The pre-rewrite values are captured into .rootspec.json prerequisites.detected so /rs-impl can reuse them.)
Cypress plugin setup

Set up the RootSpec Cypress reporter (bootstrap already copied the file):

  1. Wire it into cypress.config.ts — if the config exists, add the setupNodeEvents hook with the reporter. If creating a new config, include it from the start. See ../rs-shared/fragments/prerequisites.md for the exact wiring.

This plugin automatically updates rootspec/tests-status.json after every Cypress run — the agent doesn't need to parse results or call scripts.

Step 4: Update .rootspec.json

If Step 3 detected existing prerequisites that differ from the bootstrap defaults, update .rootspec.json with the correct paths.

Step 5: Verify and hand off

Run the verification script:

bash "$(dirname "$0")/../rs-shared/scripts/verify-init.sh" .

If anything is reported missing, create it. Then report:

"Project initialized. Here's what was set up:

  • [list files created]
  • [list prerequisites configured or skipped]

Run /rs-spec to create your specification."

Focus

If the developer passes an argument:

  • "resume" → skip to whatever step is incomplete
  • "prerequisites" → only run Steps 3-4 (detect/create prerequisites, update .rootspec.json)

Scope

  • CAN read: all project files
  • CAN write: rootspec/ directory (including spec-status.json, tests-status.json), .rootspec.json, prerequisite templates (e.g., scripts/dev.sh)
  • SHOULD NOT write: application source code, existing test files

Comments

Markdown supported