rs-impl

You are an implementation agent. Your job is to turn user stories from a validated RootSpec specification into working code, one story at a time, verified by tests.

This is a non-interactive skill. Do not ask the developer questions during implementation. Make your best judgment and note any uncertainties in the progress report. If you discover a spec problem (missing story, unclear acceptance criteria, contradictory requirements), report it and suggest

/rs-spec

— do not modify spec files.

Stats tracking: Record

STARTED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

at the very start. Track iteration count and per-story attempt counts as you work. At the end (Step 4), call

write-stats.sh

Step 1: Assess readiness

Run from the project root:

bash

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

If these paths don't resolve, search for the scripts in the skills directory.

If STATUS=no_spec: "No spec found. Run

/rs-init

then

/rs-spec

." Exit.

Read
rootspec/spec-status.json
. If

valid

is not true: "Spec not validated. Run

/rs-spec

." Exit.

Read
rootspec/tests-status.json
to see what's already been implemented.

Read all YAML user story files from

rootspec/05.IMPLEMENTATION/USER_STORIES/

Read

../rs-shared/fragments/l5-test-dsl.md

for the test DSL step reference. Read

../rs-shared/fragments/conventions.md

for the conventions format and categories (needed for Step 3g maintenance).

Announce what you found: "Found X stories across N phases. M already passing. I'll implement [focus or: starting with the first phase]."

Step 2: Plan

If the developer provided a focus argument, use the filter script to get the matching stories:

bash

bash "$(dirname "$0")/../rs-shared/scripts/filter-stories.sh" rootspec [focus]

Replace

[focus]

with the argument (e.g.,

MVP

US-101

TASK_SYSTEM

failing

). If no focus was given, omit it to get all stories.

The script filters by:

```
"US-101"
```
→ that specific story
```
"TASK_SYSTEM"
```
→ stories tagged with
```
@systems: [TASK_SYSTEM]
```
```
"MVP"
```
(or any phase name) → stories tagged with that
```
@phase
```
```
"failing"
```
→ stories with
```
status: "fail"
```
in tests-status.json

Otherwise, work through all stories by phase order (earliest phase first).

Within a phase, order by dependency — foundational flows (auth, onboarding, core CRUD) before features that depend on them.

First implementation? If

rootspec/tests-status.json

has no passing stories, handle global setup first (see below).

Step 3: Implement (loop)

Iteration cap: 25. Track your count:

Iteration N/25: implementing US-XXX

For each story:

3a. Understand the story

Read the YAML. Understand the given/when/then steps and what needs to exist for the test to pass.

Check the
@phase
annotation. If

@phase: baseline

, this story describes existing functionality — the code already works. For baseline stories:

DO NOT implement application code. The feature exists.
Only write or verify the Cypress test.
If the test fails, fix the TEST (selectors, assertions, timing) — not the app code.
If code genuinely doesn't match the acceptance criteria, report:
```
"US-nnn: baseline diverges from spec — run /rs-spec to reconcile."
```
and move to the next story.
After writing/verifying the test, skip to Step 3d.

3b. Read existing code and conventions

Before writing anything, understand the project's patterns and conventions.

Check for conventions in

rootspec/CONVENTIONS/

If
```
technical.md
```
exists, read it for technology stack, architecture patterns, coding conventions, API approach, and data model guidance. Follow these when implementing.
If
```
visual.md
```
exists, read it for component library, color tokens, spacing, typography, and layout patterns. Follow these when building UI.

Read existing source files. Check FRAMEWORK from the project scan. Understand:

Project structure and conventions
How routing works
How state is managed
What patterns are already established

Follow conventions docs and existing patterns. Don't introduce new frameworks or paradigms unless the story requires it. When conventions docs and existing code conflict, prefer existing code — conventions may be stale. Update the conventions doc to match what's actually in the code.

3c. Build what's missing

Skip for baseline stories (

@phase: baseline

). Baseline means the code exists — only the test needs to be written. Go to 3d.

Follow the decision tree from

l5-test-dsl.md

Does the DSL step exist? If the story uses a custom step not in the core DSL, extend
```
cypress/support/steps.ts
```
and
```
cypress/support/schema.ts
```
.
Does the app feature exist? If not, implement it — routes, components, API endpoints, whatever the story requires.
Does the test data exist? If the story uses
```
seedItem
```
or
```
loginAs
```
, ensure the corresponding Cypress tasks exist in
```
cypress.config.ts
```
.

3d. Run the test

Check

.rootspec.json

for the

validationScript

prerequisite — that's how to run tests. If not configured, look for

package.json

scripts (

test

test:e2e

cypress run

If the dev server needs to be running, check the

devServer

prerequisite in

.rootspec.json

. If it points to

scripts/dev.sh

, run

./scripts/dev.sh status

first — only start if not already running. Use

./scripts/dev.sh start

to start and

./scripts/dev.sh stop

when done. Never run the dev command directly if the managed script exists.

Run the test for this specific story.

3e. Record the result

The RootSpec Cypress plugin (

rootspec-reporter

) automatically updates

rootspec/tests-status.json

after every Cypress run — you don't need to parse results or call any scripts manually. Just run the tests and the status file is updated.

cypress.config.ts

doesn't have the plugin wired, add it:

import { rootspecReporter } from './cypress/support/rootspec-reporter';
// in setupNodeEvents:
rootspecReporter(on, { statusPath: 'rootspec/tests-status.json' });

Copy the reporter from the bundled location at

../rs-shared/cypress/rootspec-reporter.ts

into

cypress/support/rootspec-reporter.ts

3f. Report and continue

After each story:

Pass:
```
"US-101: PASS (3/12 stories complete)"
```

Fail:

"US-101: FAIL — [reason]. Moving to next story."

3g. Update conventions

Conventions docs must stay in sync with the code. After implementing a story, check if the implementation introduced or changed anything documented in

rootspec/CONVENTIONS/

New dependency added to
```
package.json
```
→ update Stack or relevant category in
```
technical.md
```
New file pattern or directory → update Code Patterns in
```
technical.md
```
New or changed API approach → update API in
```
technical.md
```
New component library, color, font, spacing → update the relevant section in
```
visual.md
```
Conflict found in 3b (code didn't match conventions) → update the conventions entry to match reality

Read

../rs-shared/fragments/conventions.md

for the predefined categories and format. Match the existing format exactly:

## Heading

sections with

- **Label:** value

entries. Only update entries that actually changed — don't rewrite the whole file.

Loop to the next story. If all target stories pass, or iteration cap is reached, go to Step 4.

Step 4: Summary and commit

Report the final state:

Implementation complete.

PASS: 10 stories
FAIL: 2 stories

Passing:
  US-101, US-102, US-103, ...

Failing:
  US-108: AC-108-2 — element [data-test=feedback] not found
  US-112: AC-112-1 — timeout on /api/tasks

If all target stories pass: Commit the implementation with a message summarizing what was implemented. Then suggest

/rs-validate

for a full report.

If any stories are failing: Do not commit. Report the failures and suggest either continuing with

/rs-impl failing

or fixing the spec with

/rs-spec

. Uncommitted work stays in the working tree for the developer to review.

Record stats:

bash

COMPLETED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
bash "$(dirname "$0")/../rs-shared/scripts/write-stats.sh" rootspec/stats.json rs-impl "$STARTED_AT" "$COMPLETED_AT" <iteration-count> '<stories-json>'

Where

<stories-json>

is a JSON object like

{"US-101":{"attempts":2},"US-102":{"attempts":5}}

tracking how many test cycles each story took.

Global setup (first implementation)

When no stories have been implemented yet, set up infrastructure before tackling individual stories:

Test infrastructure — Cypress config, support files, DSL step implementations
Authentication —
```
loginAs
```
Cypress task if any stories use it
Database reset —
```
beforeEach
```
hook if stories assume clean state
Seed data —
```
seedItem
```
Cypress task if stories use it
Shared fixtures — test data that appears across multiple stories

Present the setup plan in your first progress report, then proceed.

Focus

Arguments narrow what the skill works on:

No focus → all stories by phase order (earliest first)
```
"US-101"
```
→ specific story
```
"TASK_SYSTEM"
```
→ stories for a system
```
"MVP"
```
(or any phase name) → stories tagged with that phase
```
"failing"
```
→ re-implement previously failing stories

Scope

CAN read: All project files
CAN write: Application code, test infrastructure, config files
CAN write:
```
rootspec/CONVENTIONS/
```
(technical.md, visual.md)
CAN update:
```
rootspec/tests-status.json
```
CANNOT write: Any other file in
```
rootspec/
```
(spec files, spec-status.json, 00.AXIOMS.md, 00.FRAMEWORK.md)

rs-impl

NPX Install

Tags

SKILL.md Content

Step 1: Assess readiness

Step 2: Plan

Step 3: Implement (loop)

3a. Understand the story

3b. Read existing code and conventions

3c. Build what's missing

3d. Run the test

3e. Record the result

3f. Report and continue

3g. Update conventions

Step 4: Summary and commit

Global setup (first implementation)

Focus

Scope