@nano-step/skill-manager 5.1.0 → 5.2.0

package/skills/comprehensive-feature-builder/SKILL.md

@@ -0,0 +1,558 @@
+---
+name: comprehensive-feature-builder
+description: Systematic 5-phase workflow for researching, designing, implementing, and testing ANY feature. Integrates explore/librarian agents, GraphQL inspector, Sequential Thinking, UI/UX Pro Max, OpenSpec proposals, and E2E test generator with Playwright MCP. Saves checkpoints to files to prevent token bloat. Loops on test failures until all pass.
+---
+
+# Comprehensive Feature Builder Skill
+
+> **Purpose**: A systematic, checkpoint-based workflow for researching, designing, implementing, and testing ANY feature with full traceability.
+
+## Overview
+
+This skill provides a 5-phase workflow that:
+1. **Saves reports to files** at each phase (prevents token bloat)
+2. **Uses checklists** for progress tracking
+3. **Integrates OpenSpec** for proposal creation
+4. **Uses E2E test generator** with Playwright MCP for verification
+5. **Captures screenshots** at every step
+6. **Loops on failures** until tests pass
+
+## When to Use
+
+Trigger phrases:
+- "Implement feature X comprehensively"
+- "Research and build X"
+- "Full feature implementation for X"
+- "Create X with full testing"
+
+## Prerequisites
+
+Before starting:
+- [ ] Identify feature name (kebab-case): `{feature-name}`
+- [ ] Create output directory: `/ai/feature-research/{feature-name}/`
+- [ ] Verify backend is running (GraphQL endpoint accessible)
+- [ ] Verify frontend dev server is running
+
+## Directory Structure
+
+```
+/ai/feature-research/{feature-name}/
+├── progress.json                    # Current phase & status
+├── 01-discovery/
+│   ├── checklist.md                 # Phase 1 checklist
+│   ├── report.md                    # Discovery findings
+│   ├── codebase-analysis.md         # Explore agent results
+│   ├── external-research.md         # Librarian agent results
+│   └── graphql-schema.md            # GraphQL inspector results
+├── 02-analysis/
+│   ├── checklist.md                 # Phase 2 checklist
+│   ├── report.md                    # Gap analysis
+│   ├── architecture-decisions.md    # Oracle consultation
+│   └── sequential-thinking.md       # Structured analysis
+├── 03-design/
+│   ├── checklist.md                 # Phase 3 checklist
+│   ├── report.md                    # Design summary
+│   ├── ui-concept.md                # UI/UX Pro Max output
+│   ├── component-specs.md           # Component hierarchy
+│   └── ui-prompts.md                # Implementation prompts
+├── 04-implementation/
+│   ├── checklist.md                 # Phase 4 checklist
+│   ├── report.md                    # Implementation summary
+│   ├── openspec-proposal/           # OpenSpec change proposal
+│   └── code-changes.md              # Files modified
+├── 05-testing/
+│   ├── checklist.md                 # Phase 5 checklist
+│   ├── report.md                    # Test results
+│   ├── e2e-tests/                   # Generated test files
+│   ├── screenshots/                 # Step-by-step screenshots
+│   └── bug-fixes.md                 # Bugs found and fixed
+└── final-summary.md                 # Complete feature summary
+```
+
+---
+
+## Phase 1: Discovery
+
+### Objective
+Gather all context about the feature from codebase, PRD, GraphQL schema, and external research.
+
+### Checklist (`01-discovery/checklist.md`)
+
+```markdown
+## Phase 1: Discovery Checklist
+
+### 1.1 Codebase Exploration
+- [ ] Launch explore agent for existing implementations
+- [ ] Search for related pages, components, stores, hooks
+- [ ] Identify existing patterns to follow
+- [ ] Save results to `codebase-analysis.md`
+
+### 1.2 PRD & Requirements
+- [ ] Search PRD for feature requirements
+- [ ] Find user stories and acceptance criteria
+- [ ] Identify related epics and dependencies
+- [ ] Document in `report.md`
+
+### 1.3 GraphQL Schema Inspection
+- [ ] Use graphql-tools MCP to inspect types
+- [ ] List all related queries and mutations
+- [ ] Document input/output types
+- [ ] Save to `graphql-schema.md`
+
+### 1.4 External Research (if needed)
+- [ ] Launch librarian agent for best practices
+- [ ] Research UI/UX patterns
+- [ ] Find library documentation
+- [ ] Save to `external-research.md`
+
+### 1.5 Phase Completion
+- [ ] All sub-checklists complete
+- [ ] `report.md` summarizes findings
+- [ ] Update `progress.json` to phase 2
+```
+
+### Actions
+
+```typescript
+// 1. Fire parallel background agents
+task(subagent_type="explore", run_in_background=true, load_skills=[], 
+  description="Explore {feature} in codebase",
+  prompt="Find all code related to {feature}: pages, components, stores, hooks, GraphQL operations...")
+
+task(subagent_type="explore", run_in_background=true, load_skills=[],
+  description="Explore backend schema for {feature}",
+  prompt="Find all backend GraphQL types, queries, mutations for {feature}...")
+
+task(subagent_type="librarian", run_in_background=true, load_skills=[],
+  description="Research {feature} best practices",
+  prompt="Find UI/UX best practices, patterns, and examples for {feature}...")
+
+// 2. Use GraphQL inspector MCP
+graphql-tools_filter_types(search="{feature}", detailed=false)
+graphql-tools_filter_queries(search="{feature}", detailed=false)
+graphql-tools_filter_mutations(search="{feature}", detailed=false)
+// Then get details for specific types found
+
+// 3. Search PRD
+grep(pattern="Epic.*{feature}|Story.*{feature}", path="/ai/")
+
+// 4. Collect background results
+background_output(task_id="...")
+
+// 5. Save reports to files
+write(filePath="/ai/feature-research/{feature}/01-discovery/report.md", content="...")
+```
+
+### Output Template (`01-discovery/report.md`)
+
+```markdown
+# Discovery Report: {Feature Name}
+
+**Date**: {date}
+**Phase**: 1 - Discovery
+**Status**: Complete
+
+## Executive Summary
+{1-2 paragraph summary of findings}
+
+## Existing Implementation
+- **Pages**: {list of existing pages}
+- **Components**: {list of components}
+- **Stores**: {Zustand stores}
+- **Hooks**: {custom hooks}
+- **GraphQL Operations**: {queries, mutations}
+
+## PRD Requirements
+- **Epic**: {epic number and name}
+- **Stories**: {list of user stories}
+- **Acceptance Criteria**: {key AC}
+
+## GraphQL Schema
+### Types
+{list of types with key fields}
+
+### Queries
+{list of queries with arguments}
+
+### Mutations
+{list of mutations with inputs}
+
+## External Research
+{key findings from librarian agent}
+
+## Gaps Identified
+- {gap 1}
+- {gap 2}
+
+## Next Phase
+Ready for Phase 2: Analysis
+```
+
+---
+
+## Phase 2: Analysis
+
+### Objective
+Analyze gaps, make architecture decisions, and plan implementation using Sequential Thinking.
+
+### Checklist (`02-analysis/checklist.md`)
+
+```markdown
+## Phase 2: Analysis Checklist
+
+### 2.1 Gap Analysis
+- [ ] Compare PRD requirements vs existing implementation
+- [ ] Identify missing features
+- [ ] Identify bugs or issues
+- [ ] Document in `report.md`
+
+### 2.2 Sequential Thinking
+- [ ] Use Sequential-Thinking MCP for structured analysis
+- [ ] Break down implementation into steps
+- [ ] Identify dependencies and order
+- [ ] Save to `sequential-thinking.md`
+
+### 2.3 Architecture Decisions (if complex)
+- [ ] Consult Oracle for architecture questions
+- [ ] Document decisions and rationale
+- [ ] Save to `architecture-decisions.md`
+
+### 2.4 Phase Completion
+- [ ] Gap analysis complete
+- [ ] Implementation plan created
+- [ ] Update `progress.json` to phase 3
+```
+
+### Actions
+
+```typescript
+// 1. Use Sequential Thinking for structured analysis
+Sequential-Thinking_sequentialthinking(
+  thought="Analyzing {feature} implementation...",
+  thoughtNumber=1,
+  totalThoughts=5,
+  nextThoughtNeeded=true
+)
+
+// 2. Consult Oracle if complex architecture decisions needed
+task(subagent_type="oracle", run_in_background=false, load_skills=[],
+  description="Architecture consultation for {feature}",
+  prompt="Review the discovery report and advise on: {specific questions}...")
+
+// 3. Save analysis report
+write(filePath="/ai/feature-research/{feature}/02-analysis/report.md", content="...")
+```
+
+---
+
+## Phase 3: Design
+
+### Objective
+Create UI/UX design using ui-ux-pro-max skill, define component specs.
+
+### Checklist (`03-design/checklist.md`)
+
+```markdown
+## Phase 3: Design Checklist
+
+### 3.1 UI/UX Design
+- [ ] Load ui-ux-pro-max skill
+- [ ] Create UI concept based on research
+- [ ] Define visual style and patterns
+- [ ] Save to `ui-concept.md`
+
+### 3.2 Component Specification
+- [ ] Define component hierarchy
+- [ ] Specify props and state
+- [ ] Define data flow
+- [ ] Save to `component-specs.md`
+
+### 3.3 UI Prompts
+- [ ] Create detailed implementation prompts
+- [ ] Include Vietnamese text requirements
+- [ ] Include accessibility requirements
+- [ ] Save to `ui-prompts.md`
+
+### 3.4 Phase Completion
+- [ ] UI concept approved
+- [ ] Component specs complete
+- [ ] Update `progress.json` to phase 4
+```
+
+### Actions
+
+```typescript
+// 1. Load UI/UX Pro Max skill
+skill("ui-ux-pro-max")
+
+// 2. Create UI concept
+task(category="visual-engineering", load_skills=["ui-ux-pro-max", "frontend-ui-ux"],
+  description="Design UI for {feature}",
+  prompt="Based on discovery report, create UI concept for {feature}...")
+
+// 3. Save design documents
+write(filePath="/ai/feature-research/{feature}/03-design/ui-concept.md", content="...")
+write(filePath="/ai/feature-research/{feature}/03-design/component-specs.md", content="...")
+```
+
+---
+
+## Phase 4: Implementation
+
+### Objective
+Create OpenSpec proposal, implement code changes, verify with LSP diagnostics.
+
+### Checklist (`04-implementation/checklist.md`)
+
+```markdown
+## Phase 4: Implementation Checklist
+
+### 4.1 OpenSpec Proposal
+- [ ] Create change directory: `openspec/changes/{change-id}/`
+- [ ] Write `proposal.md` with Why/What/Impact
+- [ ] Write `tasks.md` with implementation steps
+- [ ] Write spec deltas in `specs/{capability}/spec.md`
+- [ ] Validate: `openspec validate {change-id} --strict --no-interactive`
+- [ ] Copy proposal to `04-implementation/openspec-proposal/`
+
+### 4.2 Code Implementation
+- [ ] Implement tasks from `tasks.md` sequentially
+- [ ] Mark each task complete as done
+- [ ] Run `pnpm codegen` if GraphQL changes
+- [ ] Verify with `lsp_diagnostics` on changed files
+
+### 4.3 Build Verification
+- [ ] Run `pnpm build` - must pass
+- [ ] Fix any TypeScript errors
+- [ ] Document changes in `code-changes.md`
+
+### 4.4 Phase Completion
+- [ ] All tasks in `tasks.md` marked complete
+- [ ] Build passes
+- [ ] Update `progress.json` to phase 5
+```
+
+### Actions
+
+```typescript
+// 1. Create OpenSpec proposal
+bash("mkdir -p openspec/changes/{change-id}/specs/{capability}")
+
+write(filePath="openspec/changes/{change-id}/proposal.md", content=`
+# Change: {Feature Name}
+
+## Why
+{Problem/opportunity from discovery}
+
+## What Changes
+- {Change 1}
+- {Change 2}
+
+## Impact
+- Affected specs: {capabilities}
+- Affected code: {files}
+`)
+
+write(filePath="openspec/changes/{change-id}/tasks.md", content=`
+## 1. Implementation
+- [ ] 1.1 {Task 1}
+- [ ] 1.2 {Task 2}
+...
+`)
+
+write(filePath="openspec/changes/{change-id}/specs/{capability}/spec.md", content=`
+## ADDED Requirements
+### Requirement: {Feature}
+{Description}
+
+#### Scenario: {Success case}
+- **WHEN** {action}
+- **THEN** {result}
+`)
+
+// 2. Validate proposal
+bash("openspec validate {change-id} --strict --no-interactive")
+
+// 3. Implement code (delegate to coding agent)
+task(category="quick", load_skills=["frontend-ui-ux"],
+  description="Implement {feature}",
+  prompt="Implement the following from tasks.md: ...")
+
+// 4. Verify
+lsp_diagnostics(filePath="{changed-file}", severity="error")
+bash("cd sharex-frontend-v0 && pnpm build")
+```
+
+---
+
+## Phase 5: Testing
+
+### Objective
+Generate E2E tests, run with Playwright MCP, capture screenshots, fix bugs until all pass.
+
+### Checklist (`05-testing/checklist.md`)
+
+```markdown
+## Phase 5: Testing Checklist
+
+### 5.1 E2E Test Generation
+- [ ] Load e2e-test-generator skill
+- [ ] Generate test cases from acceptance criteria
+- [ ] Create page objects if needed
+- [ ] Save tests to `e2e-tests/`
+
+### 5.2 Test Execution with Playwright MCP
+- [ ] Navigate to feature page
+- [ ] Execute each test step
+- [ ] Capture screenshot after each action
+- [ ] Log all steps to `report.md`
+
+### 5.3 Bug Fix Loop
+- [ ] If test fails, document bug in `bug-fixes.md`
+- [ ] Fix the bug
+- [ ] Re-run test
+- [ ] Repeat until pass
+- [ ] Capture final passing screenshot
+
+### 5.4 Phase Completion
+- [ ] All E2E tests pass
+- [ ] All screenshots captured
+- [ ] Bug fixes documented
+- [ ] Update `progress.json` to complete
+```
+
+### Actions
+
+```typescript
+// 1. Load E2E test generator skill
+skill("e2e-test-generator")
+
+// 2. Generate tests based on acceptance criteria
+task(category="quick", load_skills=["e2e-test-generator", "playwright"],
+  description="Generate E2E tests for {feature}",
+  prompt="Generate E2E tests for {feature} based on acceptance criteria: ...")
+
+// 3. Execute tests with Playwright MCP
+playwright_browser_navigate(url="http://localhost:5123/{feature-page}")
+playwright_browser_snapshot()
+playwright_browser_take_screenshot(filename="/ai/feature-research/{feature}/05-testing/screenshots/01-initial.png")
+
+// For each test step:
+playwright_browser_click(ref="{element-ref}", element="{description}")
+playwright_browser_take_screenshot(filename="/ai/feature-research/{feature}/05-testing/screenshots/02-after-click.png")
+
+// 4. Bug fix loop
+// IF test fails:
+//   - Document bug in bug-fixes.md
+//   - Fix the code
+//   - Re-run test
+//   - Repeat until pass
+
+// 5. Save test report
+write(filePath="/ai/feature-research/{feature}/05-testing/report.md", content=`
+# E2E Test Report: {Feature}
+
+## Test Results
+| Test | Status | Screenshot |
+|------|--------|------------|
+| {test 1} | ✅ PASS | screenshots/01-xxx.png |
+| {test 2} | ✅ PASS | screenshots/02-xxx.png |
+
+## Bugs Found & Fixed
+| Bug | Fix | Verified |
+|-----|-----|----------|
+| {bug 1} | {fix} | ✅ |
+
+## Screenshots
+{list of all screenshots with descriptions}
+`)
+```
+
+---
+
+## Progress Tracking
+
+### progress.json Schema
+
+```json
+{
+  "feature": "{feature-name}",
+  "currentPhase": 1,
+  "phases": {
+    "1-discovery": {
+      "status": "complete",
+      "completedAt": "2026-02-13T10:00:00Z",
+      "report": "01-discovery/report.md"
+    },
+    "2-analysis": {
+      "status": "in-progress",
+      "startedAt": "2026-02-13T10:30:00Z"
+    },
+    "3-design": { "status": "pending" },
+    "4-implementation": { "status": "pending" },
+    "5-testing": { "status": "pending" }
+  },
+  "lastUpdated": "2026-02-13T10:30:00Z"
+}
+```
+
+### Resume Instructions
+
+When resuming work:
+1. Read `progress.json` to find current phase
+2. Read the current phase's `checklist.md` to find incomplete items
+3. Read previous phase's `report.md` for context
+4. Continue from the first unchecked item
+
+---
+
+## Tool Reference
+
+| Phase | Tools | Purpose |
+|-------|-------|---------|
+| 1 | explore agent, librarian agent, graphql-tools MCP, grep | Gather context |
+| 2 | Sequential-Thinking MCP, oracle agent | Analyze and plan |
+| 3 | ui-ux-pro-max skill, visual-engineering category | Design UI |
+| 4 | OpenSpec CLI, coding agents, lsp_diagnostics | Implement |
+| 5 | e2e-test-generator skill, playwright MCP | Test and verify |
+
+---
+
+## Quick Start
+
+```bash
+# 1. Create feature directory
+FEATURE="meal-planning-enhancement"
+mkdir -p /ai/feature-research/$FEATURE/{01-discovery,02-analysis,03-design,04-implementation,05-testing/screenshots}
+
+# 2. Initialize progress.json
+echo '{"feature":"'$FEATURE'","currentPhase":1,"phases":{"1-discovery":{"status":"in-progress"},"2-analysis":{"status":"pending"},"3-design":{"status":"pending"},"4-implementation":{"status":"pending"},"5-testing":{"status":"pending"}}}' > /ai/feature-research/$FEATURE/progress.json
+
+# 3. Start Phase 1: Discovery
+# (Follow checklist above)
+```
+
+---
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Skip phases | Complete each phase fully |
+| Forget screenshots | Capture after EVERY action |
+| Ignore test failures | Fix and re-test until pass |
+| Skip OpenSpec | Always create proposal first |
+| Manual testing only | Use Playwright MCP for E2E |
+| Lose context | Save reports to files |
+
+---
+
+## Success Criteria
+
+Feature is complete when:
+- [ ] All 5 phase checklists are 100% complete
+- [ ] All E2E tests pass
+- [ ] All screenshots captured
+- [ ] OpenSpec proposal validated
+- [ ] Build passes without errors
+- [ ] `final-summary.md` written

package/skills/comprehensive-feature-builder/skill.json

@@ -0,0 +1,9 @@
+{
+  "name": "comprehensive-feature-builder",
+  "version": "1.0.0",
+  "description": "Systematic 5-phase workflow for researching, designing, implementing, and testing features with checkpoint-based progress tracking",
+  "compatibility": "OpenCode",
+  "agent": null,
+  "commands": [],
+  "tags": ["feature", "workflow", "testing", "implementation", "design"]
+}