Skip to content

nddipiazza/robos / plugins/robos/skills/e2e-driven-dev

e2e-driven-dev

Verified

Execute task development using an End-to-End Driven Development (EDD) workflow on localhost (Docker/Xvfb) where text-narrated E2E tests, structured step proofs, on-screen text narration, and video walkthroughs validate feature implementation.

E2E-Driven Development (EDD) Skill

Perform feature development or bug fixing on a generic task using an End-to-End Driven Development (EDD) methodology. In this workflow, development begins by creating a text-narrated E2E test scenario that records video with clear on-screen text narration cards and WebVTT step descriptions. The test serves as both the executable specification and the user-facing verification artifact.

[!IMPORTANT]

  • Zero VM Requirement: E2E testing and demonstration recording run entirely on localhost using isolated Docker containers (./scripts/e2e-container.sh) or local virtual framebuffers (Xvfb) and headless test runs. Never rely on slow QEMU virtual machines or SSH deployment for E2E-driven development feedback loops.
  • Text-Only Step Narration: Verification videos use on-screen text narration cards, element callout badges, and WebVTT captions explaining each step. No audio voice narration is needed. Pacing is fast, responsive, and continuous.

When to Use

Use this skill when:

  • The user requests building a new feature, flow, or bug fix using E2E-driven development (/e2e-driven-dev or /do-e2e-driven-dev).
  • You need to deliver visual proof of feature completion accompanied by step-by-step text narration, synced captions, and scenario step logs.
  • Implementing UI/UX workflows across any RobOS app (dev-central, git-projects, task-board, robos-desktop, etc.).

Input

$ARGUMENTS — <app-id> "<task description or acceptance criteria>"

Examples:

  • robos-desktop "Pin and unpin applications from taskbar and resize dock"
  • dev-central "Add sprint filter dropdown and show active sprint summary"
  • git-projects "Add git worktree creation modal with branch selection"
  • task-board "Add swimlane grouping by priority with drag-and-drop"

Workflow: The 5-Phase EDD Cycle

┌────────────────────────────────────────────────────────┐
│ 1. Spec & Script Design                                │
│    Define user story & text-narrated test script (cues)│
└──────────────────────────┬─────────────────────────────┘
                           │
┌──────────────────────────▼─────────────────────────────┐
│ 2. Create Narrated E2E Test (Red Phase)                │
│    Write test in packages/robos-test/demos/<slug>-demo.js│
│    Run test -> verify it fails on missing feature      │
└──────────────────────────┬─────────────────────────────┘
                           │
┌──────────────────────────▼─────────────────────────────┐
│ 3. Implement Feature (Green Phase)                     │
│    Implement IPC handlers, preload APIs, renderer UI   │
└──────────────────────────┬─────────────────────────────┘
                           │
┌──────────────────────────▼─────────────────────────────┐
│ 4. Run Isolated Narrated E2E & Produce Video Artifact  │
│    Execute demo-runner in Docker / local Xvfb          │
│    Record WebM + on-screen text narration + WebVTT     │
└──────────────────────────┬─────────────────────────────┘
                           │
┌──────────────────────────▼─────────────────────────────┐
│ 5. Structured Verification Report                      │
│    Present final video, VTT transcript, and step logs  │
└────────────────────────────────────────────────────────┘

Detailed Procedures

Phase 1 — Spec & Script Design

  1. Analyze Requirements: Extract the user journey, UI controls, backend/IPC operations, and acceptance criteria.
  2. Design Test Script Cues with Targeted Text Narration Callouts: Every web element interaction (button press, text input, textarea edit, dropdown select, hover) MUST include targeted visual callouts explaining what the test is doing:
    • target: CSS selector for the targeted web element (e.g. '#sprint-filter', 'button.btn-primary', 'textarea#issue-desc').
    • action: Interaction type ('click', 'type', 'hover', 'select').
    • value: (Optional) String to type into input/textarea or option value to select.
    • callout: (Optional) Concise explanation displayed in the floating callout directly adjacent to the element.
    • narration: Text explanation describing the purpose and outcome of the step.
    • minHold: Display duration (1500–3500ms) providing ample time to observe the on-screen action and text callout.

[!CAUTION]

THE CARDINAL LAW OF E2E DEMOS: 100% VISUAL GROUNDING

NEVER write a narration or click action that refers to a concept, file, or feature unless that exact item is rendered and visually visible on screen!

  1. No Phantom Narrations: If the narration talks about topology.yaml or teams.yaml, the UI MUST be rendering that file or a dedicated card for it—NEVER point to an unrelated search bar or generic table while narrating about a different concept.
  2. Explicit View / Tab Activation First: Before targeting components within sub-panels or tabs, the demo script must explicitly activate the target view first (e.g. action: 'click', target: '#tab-btn-gitops').
  3. Explicit Semantic IDs: Always use explicit semantic IDs (#gitops-file-topology, #btn-probe-acme-tax, #chapter-item-3) rather than ambiguous positional selectors (tr:first-child).
  4. Smart Callout Positioning: Callouts are automatically positioned adjacent to the target element's bounding rect with pointer-events: none and translucent styling, ensuring the callout never covers or hides the interactive element or underlying functionality.

Phase 2 — Write the Narrated E2E Test Script

Create packages/robos-test/demos/<app-id>-<feature-slug>-demo.js:

'use strict';
const path = require('path');
const { runDemo } = require('../lib/demo-runner');
const scenarios  = require('../lib/scenarios');

const SCRIPT = [
  {
    narration: 'We begin on the main dashboard to verify the new feature integration.',
    minHold: 2500,
  },
  {
    narration: 'The user opens the sprint filter dropdown to select the active sprint.',
    target: '#sprint-filter',
    action: 'click',
    callout: 'Open Sprint Filter Dropdown',
    minHold: 2500,
  },
  {
    narration: 'Selecting Sprint 24 filters the task cards and updates the sprint metrics banner.',
    target: '[data-sprint-id="sprint-24"]',
    action: 'click',
    callout: 'Select Sprint 24',
    minHold: 3000,
  },
  {
    narration: 'The developer enters a quick search term to find high-priority defect tickets.',
    target: 'input#filter-search',
    action: 'type',
    value: 'P0 blocker',
    callout: 'Filter tickets by "P0 blocker"',
    minHold: 3000,
  },
  {
    narration: 'The active sprint cards are rendered with updated story point totals.',
    js: `(() => {
      const count = document.querySelectorAll('.task-card').length;
      console.log('Filtered task count:', count);
    })()`,
    minHold: 3000,
  },
];

runDemo({
  slug: '<app-id>-<feature-slug>',
  appId: '<app-id>',
  windowTitle: 'RobOS <App Name>',
  scenario: scenarios['all-good'],
  script: SCRIPT,
}).catch(err => {
  console.error(err);
  process.exit(1);
});

Phase 3 — Implement the Feature

Implement the application code across the standard RobOS layers:

  1. Preload (packages/<app-id>/preload.js): Expose IPC bindings via contextBridge.
  2. Main Process (packages/<app-id>/main.js): Register ipcMain.handle() handlers for data operations.
  3. Renderer HTML/CSS/JS (packages/<app-id>/renderer/): Add UI components adhering to RobOS dark theme (--bg-primary: #0d1117, --accent: #00bcd4).

Phase 3b — Knowledge Graph & GitOps Continuous Synchronization

RobOS development skills strictly ensure the Knowledge Graph is kept up to date:

  • Register or update all affected entities in Modular KGraph Packages (services, contracts, requirements, eLearning courses).
  • Ensure declarative GitOps files under .robos/ (topology.yaml, teams.yaml, packages.yaml, elearning.yaml) reflect the state.

Phase 3c — Documentation Synchronization Prompt

Cardinal Rule: Whenever Knowledge Graph objects are updated, the AI coding agent must be prompted to discern any noticeable updates to system documentation and update the documentation accordingly:

  1. Examine what was added or altered in Modular KGraph Packages.
  2. Discern any noticeable updates needed across docs/why-robos.md, README.md, docs/project-plan/, and specs.
  3. Automatically update the corresponding documentation files to maintain perfect documentation alignment.

Phase 4 — Execute Narrated E2E on Localhost (Isolated)

Run the text-narrated E2E test using the containerized test harness or local virtual display:

In Docker E2E Container (Recommended):

./scripts/e2e-container.sh node packages/robos-test/demos/<app-id>-<feature-slug>-demo.js

On Local Host (with Xvfb / Headless Display):

xvfb-run -a -s "-screen 0 1920x1080x24" node packages/robos-test/demos/<app-id>-<feature-slug>-demo.js

This pipeline automatically:

  1. Launches the Electron app inside the virtual display (isolated, no host popups).
  2. Displays step text narration banners and pointer callouts on active elements.
  3. Records video with ffmpeg while executing each scripted action.
  4. Generates synchronized WebVTT captions (.vtt) for the step transcript.
  5. Saves the final verified video into <slug>-final.webm.

Phase 5 — Structured Verification Report

Reports delivered to the user must provide actionable evidence showing the feature works, rather than generic test counts:

  1. Embedded Video Artifact: Embed the generated <slug>-final.webm video demonstration.
  2. Scenario Step Definitions Table: Present a chronological step table mapping:
    • Timeline timestamps (00:00:00 - 00:00:15)
    • Step title / action
    • Text explanation of what the step executed and verified
  3. Synchronized Transcript: Full WebVTT captions transcript.
  4. File Deliverables & Local Walkthrough Archive:
    • Local Test Run: packages/robos-test/run/demos/<slug>/<slug>-final.webm & <slug>.vtt
    • Persistent Archive: ~/.robos/development/walkthroughs/<slug>/
      • <slug>-final.webm (video)
      • <slug>.vtt (captions)
      • walkthrough.md (summary, metadata, and step transcript table)
      • Historical timestamped runs: ~/.robos/development/walkthroughs/<slug>/history/<timestamp>/

Validation Checklist

  • Text-narrated test script created with clear step-by-step user explanations.
  • DOM selectors in js: actions verified against actual renderer HTML/JS.
  • Executed on localhost (Docker/Xvfb container) without QEMU VM overhead and without host desktop popups.
  • Video output (<slug>-final.webm) generated with on-screen text banners and WebVTT captions.
  • Walkthrough deliverables verified in persistent archive ~/.robos/development/walkthroughs/<slug>/.
  • Verification report documents step definitions and proof table in order.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall