nddipiazza/robos / .agents/skills/e2e-driven-dev
e2e-driven-dev
VerifiedExecute 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.2 KB |
SKILL.md
View on GitHub---
name: e2e-driven-dev
description: 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`:
```javascript
'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):
```bash
./scripts/e2e-container.sh node packages/robos-test/demos/<app-id>-<feature-slug>-demo.js
```
#### On Local Host (with Xvfb / Headless Display):
```bash
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |