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.

Turn efficiency: Every tool call costs one turn. Be aggressive about batching file reads and writes. Target pace: ~3 turns per story (setup overhead amortized across all stories).

HARD RULE — package.json: You MUST NOT write or modify the dependencies or devDependencies fields of package.json. EVER. Not when creating it, not when updating it, not when installing a framework. Use npm install <pkg1> <pkg2> ... to add packages — npm writes the deps. You may only edit the scripts field directly. If you need a framework, run one command: npm install astro @astrojs/react react react-dom tailwindcss (or equivalent). Never use the Write tool on dependencies.

HARD RULE — peer-dep discipline: When you install a framework, install ONLY the framework, the framework's intentional integrations, and packages your application code directly imports. Do NOT independently install tooling the framework already pulls in transitively (its bundler, compiler, test runner, CSS processor, etc.). The framework's peer-dep constraints are the source of truth for those versions; independently pinning a major version causes upgrade-compatibility breakage. Concrete failure mode: a project pins vite ^7 alongside a framework that owns Vite via peer-dep on ^5, and the next framework upgrade silently breaks because npm picks the wrong Vite. If you think you need a specific version of framework-owned tooling, the framework choice is wrong — not the peer-dep.

Step 1: Assess (~2 turns)

Front-load ALL reading in a single script call. Find the scripts directory first — look for .agents/skills/rs-shared/scripts/ relative to the project root, or search for assess.sh under the skills directory.

STARTED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
SHARED_DIR=$(find . -path "*/rs-shared/scripts/assess.sh" -maxdepth 5 2>/dev/null | head -1 | sed 's|/scripts/assess.sh||')
bash "$SHARED_DIR/scripts/assess.sh" . "$SHARED_DIR"

Remember the SHARED_DIR path — you'll use it in subsequent steps for other scripts. Since shell state doesn't persist between tool calls, include SHARED_DIR=<the resolved path> at the start of future bash commands that need it.

The script outputs all context in labeled sections. Parse them:

• SCAN_SPEC: If STATUS=no_spec, say "No spec found. Run /rs-init then /rs-spec." Exit.
• SPEC_STATUS: If valid is not true, say "Spec not validated. Run /rs-spec." Exit.
• TESTS_STATUS: Note which stories already pass — skip them.
• YAML: These are your stories. Count them and note their IDs, phases, and acceptance criteria.
• CONVENTIONS: Stack, patterns, and visual tokens to follow. Memorize these.
• ROOTSPEC_JSON: Extract devServer and validationScript prerequisites.
• PACKAGE_SCRIPTS: Resolve the test command. Priority: .rootspec.json validationScript → package.json test scripts → npx cypress run.
• FRAGMENT:dsl-steps: Core DSL step names. The full test pattern is in Step 3 of this document.

Announce: "Found X stories across N phases. M already passing. Implementing [focus or: all stories starting with first phase]."

You now have all context. Do NOT re-read any of these files during implementation.

Step 2: Set up (~4 turns)

2a. Filter stories (if focus provided)

bash "$SHARED_DIR/scripts/filter-stories.sh" rootspec [focus]

Replace [focus] with the argument (e.g., MVP, US-101, TASK_SYSTEM, failing). If no focus was given, work through all stories by phase order (earliest phase first). Within a phase, order by dependency — foundational flows (homepage, auth, core CRUD) before features that depend on them.

2b. Scaffold Cypress (first implementation only)

If tests-status.json has no passing stories, scaffold test infrastructure:

bash "$SHARED_DIR/scripts/scaffold-cypress.sh" . "$SHARED_DIR"

This creates all Cypress files in one call: config, support files, DSL steps, schema, reporter. Review its output to see what was created vs skipped.

Then generate the test file from spec YAML:

bash "$SHARED_DIR/scripts/generate-test-file.sh" rootspec cypress/e2e/mvp.cy.ts

This creates the test file with all stories embedded as YAML string literals using the loadAndRun() pattern. Stories without DSL-format given/when/then are skipped with a warning — you'll need to add test YAML for those manually.

After scaffolding, customize in ONE write turn. Check your stories for:

• loginAs steps → implement the task body in cypress.config.ts
• seedItem steps → implement the task body in cypress.config.ts
• Custom DSL steps not in the core set → extend steps.ts and schema.ts
• App readiness — see step 2c below. cypress/support/app-ready.ts MUST be derived from the App Readiness section of CONVENTIONS/technical.md, not the other way around. Don't customize the throwing stub until that section is written.

Write all customizations in a single multi-file operation.

2c. Populate dev/preview wrappers, conventions, and dev server (combine into 1 turn)

The wrappers scripts/dev.sh and scripts/preview.sh ship empty (with a hard-fail recursion guard). Populate DEV_CMD/PREVIEW_CMD from the detected stack BEFORE attempting to start the server. Read once, write once, then start.

eval "$(bash "$SHARED_DIR/scripts/detect-stack.sh" .)"
# DEV_CMD and PREVIEW_CMD are now set (e.g. DEV_CMD='npx astro dev --port 4321').
# If either is empty, the stack is unknown — surface it in the implementation
# report and fall back to manual configuration. Do not start the server.

Then in the same turn, write DEV_CMD="..." and PREVIEW_CMD="..." into the wrappers (Edit the existing empty assignment lines in scripts/dev.sh and scripts/preview.sh), and add the choice to CONVENTIONS/technical.md → "Dev Server" with two lines: detected stack + the literal command. Future /rs-impl runs read this section as authority — only re-run detection if the section is missing.

After populating, start the dev server:

./scripts/dev.sh start
sleep 3

The dev server is for fast iteration (npx cypress run against it during the implement loop). The project's canonical test runner is ./scripts/test.sh, which respects .rootspec.json prerequisites.testMode (default "preview": build + preview server). The pre-commit hook calls test.sh, so the gate is preview-mode regardless of how you iterate. Don't change testMode to "dev" to make tests pass — fix the impl so it passes against a built artifact.

If rootspec/CONVENTIONS/ doesn't exist, create both technical.md and visual.md using parallel Write calls in this same turn. Derive from the spec, detected framework, and existing source code. For brownfield projects (existing code, no prior conventions), audit the codebase and document observed patterns — stack, file organization, styling approach, API patterns, component structure. Use ## Heading sections with - **Label:** value entries.

technical.md MUST include an "App Readiness" section answering two questions in this order:

1. Deferred-execution boundaries. List every component, region, or module whose interactive code is loaded or executed after the initial document arrives. Cite file paths. Examples: components mounted with client:load/client:idle/client:visible/client:only (Astro), 'use client' islands (RSC), React.lazy+<Suspense>, dynamic(...) imports (Next.js), defineAsyncComponent (Vue), Svelte dynamic loads. If the project has none, write "None — fully static" with one-line evidence.
2. Readiness signal. For each boundary, what observable signal does it emit when fully active? (a global, an attribute on a known node, an event, polled component state, etc.) The Cypress implementation in cypress/support/app-ready.ts flows from this — the convention drives the code, not the other way around.

Then write cypress/support/app-ready.ts to assert the signal from (2). Keep the file terse: Cypress.Commands.add body + declare global + export {}. Do not put rationalization comments in the implementation file — reasoning belongs in technical.md where it can be reviewed against the framework rule. A one-line pointer back to the conventions doc is fine; multi-paragraph justification is not.

If the rendered output contains any deferred-execution boundary, cy.appReady() MUST observe those boundaries — document.readyState, body presence, and cy.wrap(true) are insufficient and will hard-fail the scripts/check-app-ready.sh pre-flight before Cypress starts. A no-op or document-level check is acceptable ONLY when the App Readiness section answers (1) with "None — fully static".

2d. Wire the build script

rs-init creates package.json with a stub "build": "echo 'No build configured yet'". When you install a framework that has a build command, replace this stub in the same turn as your npm install. The downstream review phase runs npm run build to scan rendered HTML — a stub script silently produces no output and the review degrades.

Common build commands:

Brownfield: if package.json already has a real build script, leave it alone.

Step 3: Implement (~3 turns per story)

Per-story cap: 2 test-fix cycles. If you're spending more than 5 turns on one story, record FAIL and move on.

Target pace: ~3 turns per story. Implement ALL stories the spec requires — don't stop early or reduce scope.

Before implementing: preflight all stories

Run the preflight script to see exactly what needs to be built:

bash "$SHARED_DIR/scripts/preflight-story.sh" rootspec/05.IMPLEMENTATION/USER_STORIES .

This outputs:

• ROUTES_NEEDED / ROUTES_MISSING — pages/routes to create
• SELECTORS_NEEDED / SELECTORS_MISSING — data-test attributes to add
• CUSTOM_STEPS_NEEDED / CUSTOM_STEPS_MISSING — DSL steps to implement in steps.ts
• TASKS_NEEDED / TASKS_MISSING — Cypress tasks to implement in cypress.config.ts

Use this to plan your work — you now know the full scope before writing a single line.

Plan your write batches

Group files into turns using parallel Write calls:

• Page components: Group components on the same page (e.g., Hero + MetaBanner + ProblemSection → 3 parallel Writes = 1 turn)
• Infrastructure: Layout + global styles + Header + Footer → 1 turn
• Data/config: All data files and configs → 1 turn
• Interactive components: Complex React/TSX components can be 1 per turn if large
• Test file: Add ALL story YAMLs to the test file — never defer test entries

Aim for 4-6 write turns total for all app code, not one file per turn.

Implementation loop: plumbing → build → test targeted → test all

Phase 0: Wire plumbing (before any app code)

Handle mechanical wiring from the preflight output in ONE turn:

• CUSTOM_STEPS_MISSING → extend steps.ts and schema.ts
• TASKS_MISSING → add Cypress task implementations in cypress.config.ts

This is mechanical — add the type, add the implementation skeleton. Do it once for all stories.

Phase A: Build a batch

Pick 2-4 related stories. Write all their code + test YAML in as few turns as possible using parallel Write calls. Every data-test attribute in the preflight's SELECTORS_NEEDED list must appear in your component code.

App readiness must resolve before any test interacts with a page. cy.appReady() is called automatically after every visit (and explicitly via the awaitReady DSL step for mid-flow gating). The implementation in cypress/support/app-ready.ts flows from the App Readiness section of CONVENTIONS/technical.md (see step 2c) — boundaries get listed in conventions first, the Cypress check asserts the signals those boundaries emit. If the page contains any deferred-execution boundary, the check MUST observe those boundaries; document.readyState, body presence, and cy.wrap(true) are pre-flight failures. Routes need not set any specific attribute; how readiness is signaled is the project's call within the rule.

Phase B: Test targeted stories

Run tests for just the stories you implemented:

npx cypress run --spec cypress/e2e/mvp.cy.ts 2>&1 | tail -20; cat rootspec/tests-status.json

If targeted stories fail, diagnose using the preflight output — don't guess:

• Selector not found → check the exact data-test= attribute matches the preflight's SELECTORS_NEEDED
• Route 404 → check the page file path matches the preflight's ROUTES_NEEDED
• Task not found → check cypress.config.ts has the task from TASKS_NEEDED
• Zod validation error → you used a non-core DSL step
• Assertion value wrong → this is actual feature logic — fix the app code

Fix in ONE turn. Max 2 fix cycles per batch. Then move on.

Phase C: Test ALL stories (regression check)

After the targeted tests pass (or you've moved on), run the full suite:

npx cypress run 2>&1 | tail -20; cat rootspec/tests-status.json

Compare against what was passing before this batch. If previously passing stories now fail, that's a regression. Fix the regression before implementing more stories.

Regression response:

• If all tests broke at once → build/config problem. Check framework config, imports, build errors. Fix the root cause.
• If specific stories regressed → your changes conflicted. Revert the conflicting part or fix the interaction.
• Do NOT continue implementing new stories while regressions exist.

Test file pattern (CRITICAL)

DO NOT use cy.readFile() to load YAML files. Cypress commands cannot run outside it() blocks. Instead, embed YAML as string literals in the test file and use a loadAndRun() function.

Use this exact pattern for test files:

import * as yaml from 'js-yaml';
import { UserStorySchema } from '../support/schema';
import type { UserStory } from '../support/schema';
import { runSetupSteps, runAssertionSteps } from '../support/steps';

function loadAndRun(yamlContent: string) {
  const docs = yaml.loadAll(yamlContent) as UserStory[];
  for (const doc of docs) {
    if (!doc || !doc.id) continue;
    const story = UserStorySchema.parse(doc);
    const describeFn = story.skip ? describe.skip : story.only ? describe.only : describe;
    describeFn(`${story.id}: ${story.title}`, () => {
      for (const ac of story.acceptance_criteria) {
        const itFn = ac.skip ? it.skip : ac.only ? it.only : it;
        itFn(`${ac.id}: ${ac.title}`, () => {
          if (ac.given) runSetupSteps(ac.given);
          if (ac.when) runSetupSteps(ac.when);
          if (ac.then) runAssertionSteps(ac.then);
        });
      }
    });
  }
}

// Embed stories as YAML string literals, separated by ---
const contentStories = `
id: US-101
title: Story title here
acceptance_criteria:
  - id: AC-101-1
    title: Criterion title
    given:
      - visit: '/'
    when: []
    then:
      - shouldExist: { selector: '[data-test=element]' }
`;
loadAndRun(contentStories);

Key rules for test files:

• One test file per phase or logical group (e.g., mvp.cy.ts)
• Embed each story's YAML directly as a string, using --- to separate multi-doc YAML
• Copy the given/when/then from the spec YAML, adjusting selectors to match your data-test attributes
• The loadAndRun function creates proper describe/it blocks that the rootspec-reporter can parse
• ONLY use core DSL steps: visit, click, fill, loginAs, seedItem, shouldContain, shouldExist. Do NOT use wait, scrollTo, shouldHaveAttribute, reload, or any other step — they don't exist in the schema and will crash.
• NEVER rewrite or shrink the test file during debugging. Only append new stories or edit specific YAML strings. If you rewrite the file, you lose all existing passing stories.
• NEVER create additional test files (no debug.cy.ts, targeted.cy.ts, etc.). All tests go in the single test file.

Building a batch

Do not re-read YAML, conventions, or fragments. Use the context from Step 1.

Check @phase annotations. If @phase: baseline, only write/verify the Cypress test — do not modify app code.

For non-baseline stories, in ONE write turn per story:

• Create/modify all application files (routes, components, pages, styles)
• Add the story's YAML to the test file (append to the existing test file)
• Use data-test attributes matching acceptance criteria selectors

A story is NOT implemented until its test YAML is in the test file.

Example batch (3 stories, 3 turns):

• Turn 1: Write MetaBanner.astro, HeroSection.astro, ProblemSection.astro (parallel Writes)
• Turn 2: Update index.astro + add 3 story YAMLs to test file (parallel writes)
• Turn 3: Run targeted tests for the batch (Phase B)

Fixing failures

Fix in ONE turn using Edit on specific lines. Max 2 fix cycles per batch.

If you're stuck, re-run preflight to verify plumbing is correct:

bash "$SHARED_DIR/scripts/preflight-story.sh" rootspec/05.IMPLEMENTATION/USER_STORIES .

If SELECTORS_MISSING or ROUTES_MISSING is non-empty, fix those first — the test can't pass without them.

NEVER do these:

• Rewrite the entire test file (you'll lose passing stories)
• Create separate debug/targeted test files
• Add wait or timeout steps (not in the DSL)
• Remove stories from the test file

After each batch

Report: "Batch complete: US-001, US-002, US-003 PASS. Full suite: 6/10 passing, 0 regressions."

If regressions exist, fix before starting next batch. When all target stories pass (or per-story cap reached), go to Step 4.

Step 4: Summary and commit (~3 turns)

Update conventions (1 turn)

Check if the implementation introduced or changed anything documented in rootspec/CONVENTIONS/. Update conventions docs to reflect what you actually built — new dependencies, patterns, colors, fonts. Only update entries that actually changed. Match the format: ## Heading sections with - **Label:** value entries.

Commit and report (1-2 turns)

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

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 "$SHARED_DIR/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":1}} tracking how many test cycles each story took.

Report

Generate the report from tests-status.json — do not self-assess:

bash "$SHARED_DIR/scripts/generate-test-report.sh" rootspec/tests-status.json rootspec

This outputs pass/fail/not-tested counts from the actual test results. Include its output in your summary.

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)
• CANNOT write: dependencies or devDependencies in package.json (use npm install)