Initial commit

2025-11-30 09:07:10 +08:00
commit 169a5fc5cd
99 changed files with 25560 additions and 0 deletions
--- a/skills/agileflow-story-writer/SKILL.md
+++ b/skills/agileflow-story-writer/SKILL.md
@@ -0,0 +1,227 @@
+---
+name: agileflow-story-writer
+description: Automatically formats user requirements and feature discussions into proper user stories with acceptance criteria following AgileFlow templates. Loads when user describes features, requirements, or tasks to implement.
+allowed-tools: Read, Write, Edit, Glob
+---
+
+# agileflow-story-writer
+
+ROLE & IDENTITY
+- Skill ID: STORY-WRITER
+- Specialization: User story formatting from feature discussions with acceptance criteria
+- Part of the AgileFlow docs-as-code system
+
+OBJECTIVE
+Convert user feature descriptions and requirements into properly formatted AgileFlow user stories with acceptance criteria, owner assignment, priority, and estimates. Ensure stories are ready for dev agent pickup by following Definition of Ready (AC exists, test stub created, status=ready).
+
+INPUTS
+- User feature description or requirement discussion
+- Existing stories in docs/06-stories/ (for numbering)
+- Epic context (if story is part of epic)
+- Story template from templates/story-template.md
+- Project conventions from CLAUDE.md (optional)
+
+FIRST ACTION
+
+**Deterministic boot sequence**:
+1. Check if docs/06-stories/ exists: `[ -d docs/06-stories ] && echo "Found" || echo "Not found"`
+2. If found, count existing stories: `ls docs/06-stories/US-*.md 2>/dev/null | wc -l`
+3. Read story template: `cat templates/story-template.md`
+4. Check status.json for epic context: `jq '.stories | to_entries[] | select(.value.status == "ready")' docs/09-agents/status.json`
+
+PROACTIVE KNOWLEDGE LOADING
+
+**Before generating story**:
+- Read templates/story-template.md for current story structure
+- List docs/06-stories/ to determine next story number (US-####)
+- Read docs/09-agents/status.json to check if story is part of an epic
+- Read CLAUDE.md for project-specific story conventions (if exists)
+- Scan recent stories to match team's AC writing style
+
+**Owner Determination**:
+- **AG-UI**: Frontend components, styling, user interactions, accessibility
+- **AG-API**: Backend services, APIs, data models, business logic
+- **AG-CI**: CI/CD pipelines, testing infrastructure, quality gates
+- **AG-DEVOPS**: Infrastructure, deployment, monitoring, automation
+
+WORKFLOW
+
+1. **Extract user story components**:
+   - **Who** (user type): As a [user type]
+   - **What** (capability): I want to [action/capability]
+   - **Why** (benefit): So that [benefit/value]
+
+2. **Determine metadata**:
+   - **Owner**: Based on work type (AG-UI, AG-API, AG-CI, AG-DEVOPS)
+   - **Priority**: P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
+   - **Estimate**: 1,2,3,5,8,13 story points (Fibonacci)
+   - **Epic**: Link if part of larger epic
+
+3. **Generate acceptance criteria** (2-5 criteria):
+   - Format: **Given** [context] **When** [action] **Then** [outcome]
+   - Make specific and testable
+   - Cover happy path + edge cases
+
+4. **Create story file**:
+   - Path: `docs/06-stories/US-####-descriptive-name.md`
+   - Follow template structure from templates/story-template.md
+   - Include: frontmatter, description, AC, technical notes, testing strategy
+
+5. **Show diff** and wait for YES/NO confirmation (diff-first pattern)
+
+6. **After YES**:
+   - Write story file
+   - Update docs/06-stories/README.md index
+   - Update docs/09-agents/status.json with new story entry (status: ready)
+   - Create test stub at docs/07-testing/test-cases/US-####.md
+
+RELATED COMMANDS
+
+- `/AgileFlow:epic` - Creates epics that contain stories (use when feature is large)
+- `/AgileFlow:status STORY=... STATUS=...` - Update story status after creation
+- `/AgileFlow:story-validate US-####` - Validate story completeness before dev agent pickup
+- `/AgileFlow:adr-new` - Document architectural decisions referenced in story
+- `/AgileFlow:chatgpt MODE=research TOPIC=...` - Research technical approach before writing story
+
+**When to use slash commands**:
+- After creating story → `/AgileFlow:story-validate` to ensure Definition of Ready
+- Large feature → `/AgileFlow:epic` instead of single story
+- Architectural decision needed → `/AgileFlow:adr-new` to document choice
+
+OUTPUTS
+
+- User story file at `docs/06-stories/US-####-descriptive-name.md`
+- Updated `docs/06-stories/README.md` index
+- Updated `docs/09-agents/status.json` with new story entry
+- Test stub at `docs/07-testing/test-cases/US-####.md`
+
+HANDOFFS
+
+**AgileFlow Coordination** (if working within AgileFlow system):
+- Updates docs/09-agents/status.json with new story:
+  ```json
+  {
+    "US-0042": {
+      "title": "User Login Form",
+      "owner": "AG-UI",
+      "status": "ready",
+      "priority": "P1",
+      "estimate": "5",
+      "epic": "EP-0001",
+      "created": "2025-10-30T10:00:00Z"
+    }
+  }
+  ```
+- May append bus message if part of epic coordination:
+  ```jsonl
+  {"ts":"2025-10-30T10:00:00Z","from":"STORY-WRITER","type":"status","story":"US-0042","text":"New story created, ready for AG-UI pickup"}
+  ```
+- Creates test stub in docs/07-testing/test-cases/ (Definition of Ready requirement)
+- Dev agents (AG-UI, AG-API, AG-CI, AG-DEVOPS) will pick up stories with status=ready
+
+**Story Lifecycle**:
+- Story created → status=ready (if Definition of Ready met)
+- Dev agent picks up → status=in-progress
+- Implementation complete → status=in-review
+- PR merged → status=done
+
+QUALITY CHECKLIST
+
+Before creating story file, verify:
+- [ ] User story follows "As a...I want...So that..." format
+- [ ] At least 2 acceptance criteria with Given/When/Then
+- [ ] Owner is appropriate for work type (AG-UI/AG-API/AG-CI/AG-DEVOPS)
+- [ ] Priority reflects urgency and impact (P0-P3)
+- [ ] Estimate is in Fibonacci sequence (1,2,3,5,8,13)
+- [ ] File name matches pattern: US-####-descriptive-name.md
+- [ ] Technical notes capture implementation details and dependencies
+- [ ] Definition of Done is comprehensive
+- [ ] Story will be added to status.json with status=ready
+- [ ] Test stub will be created at docs/07-testing/test-cases/US-####.md
+
+## Story Point Estimation Guide
+
+- **1 point**: Trivial change (update text, fix typo, config tweak)
+- **2 points**: Simple feature (add form field, new button, basic validation)
+- **3 points**: Small feature (basic CRUD endpoint, simple component)
+- **5 points**: Medium feature (authentication flow, data model with relations)
+- **8 points**: Large feature (payment integration, complex UI workflow)
+- **13 points**: Very large (consider splitting into multiple stories or epic)
+
+## Priority Guidelines
+
+- **P0 (Critical)**: Blocking users, security issues, data loss, production outage
+- **P1 (High)**: Major features, important fixes, user-facing improvements
+- **P2 (Medium)**: Nice-to-have features, minor improvements, enhancements
+- **P3 (Low)**: Tech debt, cleanup, future enhancements, optimizations
+
+## User Story Format Reference
+
+```markdown
+---
+story_id: US-0042
+epic: EP-0001
+title: User Login Form
+owner: AG-UI
+status: ready
+estimate: 5
+priority: P1
+created: 2025-10-30
+updated: 2025-10-30
+dependencies: [US-0040]
+---
+
+## Description
+
+As a user,
+I want to log in with my email and password,
+So that I can access my account and personalized features.
+
+## Acceptance Criteria
+
+### AC1: Successful Login
+**Given** a registered user with valid credentials
+**When** user enters email "user@example.com" and password "ValidPass123!"
+**Then** user is redirected to dashboard with welcome message (HTTP 200)
+
+### AC2: Invalid Credentials
+**Given** user enters incorrect password
+**When** user submits login form
+**Then** error message "Invalid email or password" is displayed (HTTP 401)
+
+### AC3: Input Validation
+**Given** user submits empty email field
+**When** user clicks "Login" button
+**Then** validation error "Email is required" is shown
+
+## Technical Notes
+
+- Use JWT authentication with 24h expiration
+- Store tokens in httpOnly cookies
+- Implement rate limiting (5 attempts per 15 minutes)
+- Hash passwords with bcrypt (cost factor 12)
+
+## Testing Strategy
+
+- Unit tests for form validation logic
+- Integration tests for authentication flow
+- E2E test for full login journey
+- Test stub: docs/07-testing/test-cases/US-0042.md
+
+## Definition of Done
+
+- [ ] Code implemented and reviewed
+- [ ] Tests written and passing
+- [ ] Documentation updated
+- [ ] Deployed to staging
+- [ ] Acceptance criteria validated
+```
+
+## Notes
+
+- If user is vague, ask clarifying questions before generating story
+- Always increment story number based on existing stories in docs/06-stories/
+- Update docs/06-stories/README.md index after creating story
+- If story is >13 points, suggest breaking into multiple stories or creating an epic
+- Follow "diff-first; YES/NO" pattern - show story before writing file
+- Create test stub to satisfy Definition of Ready (required for status=ready)
--- a/skills/agileflow-story-writer/examples/good-story-example.md
+++ b/skills/agileflow-story-writer/examples/good-story-example.md
@@ -0,0 +1,63 @@
+# [STORY-042] Add Dark Mode Toggle to Settings
+
+**Owner**: AG-UI
+**Status**: TODO
+**Epic**: [EPIC-005] User Experience Improvements
+**Priority**: P2
+**Estimate**: 5 story points
+
+## User Story
+
+As a user who works at night,
+I want to toggle dark mode in the settings,
+So that I can reduce eye strain and improve readability in low-light conditions.
+
+## Acceptance Criteria
+
+### AC1: Settings Toggle Available
+**Given** I am on the settings page
+**When** I navigate to the "Appearance" section
+**Then** I should see a dark mode toggle switch
+
+### AC2: Theme Switches Immediately
+**Given** I am viewing the app in light mode
+**When** I toggle dark mode on
+**Then** the entire UI should switch to dark theme within 200ms
+
+### AC3: Preference Persists
+**Given** I have enabled dark mode
+**When** I close and reopen the application
+**Then** dark mode should still be active
+
+### AC4: System Preference Detection
+**Given** I have not set a preference
+**When** the app loads for the first time
+**Then** it should default to my system's dark mode preference
+
+## Technical Notes
+
+- Use CSS custom properties for theme colors
+- Store preference in localStorage: `theme: 'light' | 'dark' | 'system'`
+- Listen to `prefers-color-scheme` media query for system default
+- Ensure all components support both themes
+- Add transition animations for smooth mode switching
+
+## Testing Strategy
+
+- Test theme switching in all major browsers (Chrome, Firefox, Safari)
+- Verify localStorage persistence across sessions
+- Test system preference detection on different OS
+- Validate WCAG contrast ratios in dark mode
+- Test with keyboard navigation (accessibility)
+
+## Definition of Done
+
+- [ ] Dark mode toggle implemented in settings UI
+- [ ] Theme preference stored in localStorage
+- [ ] All components styled for dark mode
+- [ ] System preference detection working
+- [ ] Unit tests for theme switching logic
+- [ ] E2E tests for toggle interaction
+- [ ] Documentation updated with theme implementation details
+- [ ] Deployed to staging and tested
+- [ ] Accessibility audit passed (WCAG AA)
--- a/skills/agileflow-story-writer/templates/story-template.md
+++ b/skills/agileflow-story-writer/templates/story-template.md
@@ -0,0 +1,44 @@
+# [STORY-###] {Title}
+
+**Owner**: {AG-UI | AG-API | AG-CI | AG-DEVOPS}
+**Status**: TODO
+**Epic**: {Link to epic if applicable}
+**Priority**: {P0 | P1 | P2 | P3}
+**Estimate**: {1-13 story points}
+
+## User Story
+
+As a {user type},
+I want to {action/capability},
+So that {benefit/value}.
+
+## Acceptance Criteria
+
+### AC1: {Criterion Name}
+**Given** {initial context/state}
+**When** {action/trigger}
+**Then** {expected outcome}
+
+### AC2: {Another Criterion}
+**Given** {context}
+**When** {action}
+**Then** {outcome}
+
+## Technical Notes
+
+- {Implementation details}
+- {Dependencies}
+- {Risks/Considerations}
+
+## Testing Strategy
+
+- {How to test this story}
+- {Edge cases to verify}
+
+## Definition of Done
+
+- [ ] Code implemented and reviewed
+- [ ] Tests written and passing
+- [ ] Documentation updated
+- [ ] Deployed to staging
+- [ ] Acceptance criteria validated