@pennyfarthing/core 7.5.0 → 7.6.1

package/pennyfarthing-dist/skills/story/scripts/size-story.sh

@@ -0,0 +1,198 @@
+#!/usr/bin/env bash
+# size-story.sh - Display story sizing guidelines
+# Usage: size-story.sh [points]
+#   No args: Show all sizing guidelines
+#   points:  Show specific guidance for that point value
+
+set -euo pipefail
+
+POINTS="${1:-}"
+
+print_all() {
+    cat << 'EOF'
+# Story Sizing Guidelines
+
+| Points | Scale | Complexity | Testing |
+|--------|-------|------------|---------|
+| 1-2 | Trivial | Single file, config | Minimal/none |
+| 3 | Small | Few files, single component | Some tests |
+| 5 | Medium | Multiple files, cross-layer | Comprehensive |
+| 8 | Large | Significant scope, cross-repo | Extensive |
+| 13+ | Epic | **SPLIT THIS** | N/A |
+
+## 1-2 Points (Trivial)
+- Single file change
+- Config update
+- Simple bug fix
+- Minimal or no new tests needed
+
+## 3 Points (Small)
+- Few files changed
+- Single component/handler
+- Straightforward implementation
+- Some tests needed
+
+## 5 Points (Medium)
+- Multiple files across layers
+- New feature component
+- API + UI changes
+- Comprehensive tests
+
+## 8 Points (Large)
+- Significant feature
+- Multiple components
+- Database changes possible
+- Cross-repo coordination
+
+## 13+ Points (Epic-level)
+- **SPLIT THIS STORY**
+- Too complex for single story
+- Multiple unknowns
+- Break into 3-5 smaller stories
+EOF
+}
+
+print_specific() {
+    local pts="$1"
+    case "$pts" in
+        1|2)
+            cat << 'EOF'
+## 1-2 Points (Trivial)
+
+**Characteristics:**
+- Single file change
+- Config update
+- Simple bug fix
+- Minimal or no new tests needed
+
+**Examples:**
+- Fix typo in documentation
+- Update environment variable
+- Add missing import
+- Simple CSS adjustment
+
+**YAML:**
+```yaml
+- id: PROJ-XXXXX
+  title: "Fix typo in README"
+  points: 1
+  workflow: trivial
+```
+EOF
+            ;;
+        3)
+            cat << 'EOF'
+## 3 Points (Small)
+
+**Characteristics:**
+- Few files changed
+- Single component/handler
+- Straightforward implementation
+- Some tests needed
+
+**Examples:**
+- Add validation to existing endpoint
+- Fix bug with tests
+- Add new utility function
+
+**YAML:**
+```yaml
+- id: PROJ-XXXXX
+  title: "Add input validation"
+  points: 3
+  workflow: tdd
+```
+EOF
+            ;;
+        5)
+            cat << 'EOF'
+## 5 Points (Medium)
+
+**Characteristics:**
+- Multiple files across layers
+- New feature component
+- API + UI changes
+- Comprehensive tests
+
+**Examples:**
+- New admin page
+- New API endpoint with tests
+- Refactor with behavioral tests
+
+**YAML:**
+```yaml
+- id: PROJ-XXXXX
+  title: "Add settings page"
+  points: 5
+  workflow: tdd
+```
+EOF
+            ;;
+        8)
+            cat << 'EOF'
+## 8 Points (Large)
+
+**Characteristics:**
+- Significant feature
+- Multiple components
+- Database changes possible
+- Cross-repo coordination
+
+**Examples:**
+- New integration
+- Major refactor
+- New subsystem
+
+**YAML:**
+```yaml
+- id: PROJ-XXXXX
+  title: "Add notification system"
+  points: 8
+  workflow: tdd
+```
+
+**Consider:** Can this be split into 2-3 smaller stories?
+EOF
+            ;;
+        13|21|*)
+            if [[ "$pts" -ge 13 ]]; then
+                cat << 'EOF'
+## 13+ Points - TOO LARGE
+
+**This story should be SPLIT.**
+
+Stories over 8 points have:
+- Multiple unknowns
+- High risk of scope creep
+- Difficult to estimate accurately
+- Hard to review in one PR
+
+**Action:** Break into 3-5 smaller stories:
+1. Identify distinct deliverables
+2. Create a story per deliverable
+3. Size each story 3-5 points
+4. Link stories to parent epic
+
+**Example split:**
+```
+Epic: User Dashboard (13 pts total)
+├── Story 1: Dashboard layout (3 pts)
+├── Story 2: User stats API (5 pts)
+├── Story 3: Activity feed (3 pts)
+└── Story 4: Export feature (2 pts)
+```
+EOF
+            else
+                echo "Unknown point value: $pts"
+                echo "Valid values: 1, 2, 3, 5, 8, 13+"
+                exit 1
+            fi
+            ;;
+    esac
+}
+
+if [[ -z "$POINTS" ]]; then
+    print_all
+else
+    print_specific "$POINTS"
+fi

package/pennyfarthing-dist/skills/story/scripts/story-template.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# story-template.sh - Show story templates by type
+# Usage: story-template.sh [bug|feature|refactor|chore]
+#   No args: Show all templates
+#   type:    Show specific template
+
+set -euo pipefail
+
+TYPE="${1:-}"
+
+print_bug() {
+    cat << 'EOF'
+## Bug Fix Story Template
+
+```yaml
+- id: PROJ-XXXXX
+  title: "[Component] Bug description"
+  description: |
+    **Symptom:** What user sees
+    **Error:** Error message or behavior
+    **Affected:** Pages/endpoints impacted
+  points: 2-3
+  priority: P1
+  status: backlog
+  workflow: tdd
+  acceptance_criteria:
+    - Bug no longer occurs under [conditions]
+    - Regression test added covering the bug
+    - Related code audited for same issue
+```
+
+**Sizing hints:**
+- Simple fix with clear cause: 2 pts
+- Investigation needed: 3 pts
+- Multiple components affected: 5 pts
+EOF
+}
+
+print_feature() {
+    cat << 'EOF'
+## Feature Story Template
+
+```yaml
+- id: PROJ-XXXXX
+  title: "[Action verb] [what] for [who/where]"
+  description: |
+    User can [action] to [benefit].
+    [Additional context if needed]
+  points: 3-8
+  priority: P2
+  status: backlog
+  workflow: tdd
+  acceptance_criteria:
+    - Feature works as specified
+    - UI matches design (if applicable)
+    - API documented (if applicable)
+    - Tests cover happy path and edge cases
+    - Error handling implemented
+```
+
+**Sizing hints:**
+- Single component: 3 pts
+- API + UI: 5 pts
+- Cross-repo/complex: 8 pts
+EOF
+}
+
+print_refactor() {
+    cat << 'EOF'
+## Refactor Story Template
+
+```yaml
+- id: PROJ-XXXXX
+  title: "Refactor [component] to [improvement]"
+  description: |
+    Current: [what exists now]
+    Target: [what it should become]
+    Why: [reason for change]
+  points: 3-5
+  priority: P2
+  status: backlog
+  workflow: tdd
+  acceptance_criteria:
+    - All existing tests pass
+    - No behavior changes (unless explicitly scoped)
+    - Code follows new pattern
+    - Documentation updated
+```
+
+**Sizing hints:**
+- Extract/rename: 2-3 pts
+- Restructure module: 5 pts
+- Architecture change: 8 pts (consider splitting)
+EOF
+}
+
+print_chore() {
+    cat << 'EOF'
+## Chore Story Template
+
+```yaml
+- id: PROJ-XXXXX
+  title: "[Action] [what]"
+  description: |
+    [What needs to be done and why]
+  points: 1-2
+  priority: P2
+  status: backlog
+  workflow: trivial
+  acceptance_criteria:
+    - Task completed
+    - No regressions introduced
+```
+
+**Examples:**
+- Update dependencies
+- Fix typo in docs
+- Remove dead code
+- Update config values
+
+**Note:** Chores typically use a lightweight workflow.
+EOF
+}
+
+print_all() {
+    cat << 'EOF'
+# Story Templates
+
+Use these templates when adding stories to sprint YAML.
+
+EOF
+    print_bug
+    echo ""
+    print_feature
+    echo ""
+    print_refactor
+    echo ""
+    print_chore
+}
+
+case "$TYPE" in
+    bug)
+        print_bug
+        ;;
+    feature)
+        print_feature
+        ;;
+    refactor)
+        print_refactor
+        ;;
+    chore)
+        print_chore
+        ;;
+    "")
+        print_all
+        ;;
+    *)
+        echo "Unknown type: $TYPE"
+        echo "Valid types: bug, feature, refactor, chore"
+        exit 1
+        ;;
+esac

package/pennyfarthing-dist/skills/story/skill.md

@@ -0,0 +1,219 @@
+---
+name: story
+description: |
+  Story creation, sizing, and templates. Use when creating new stories,
+  determining story points, or getting the right template for bug/feature/refactor work.
+  For starting work on stories, use /sprint work instead.
+args: "[size|template|create|finish] [options]"
+---
+
+# /story - Story Management
+
+Story creation and sizing utilities. For **starting work** on stories, use `/sprint work`.
+
+## Commands
+
+### `/story size [points]`
+
+Display story sizing guidelines.
+
+<when>
+- Without argument: Show all sizing guidelines
+- With points: Show specific guidance for that point value
+</when>
+
+<run>
+.pennyfarthing/scripts/core/run.sh story/size-story.sh [points]
+</run>
+
+<example>
+.pennyfarthing/scripts/core/run.sh story/size-story.sh        # All guidelines
+.pennyfarthing/scripts/core/run.sh story/size-story.sh 3      # 3-point guidance
+.pennyfarthing/scripts/core/run.sh story/size-story.sh 13     # Split guidance
+</example>
+
+<output>
+Sizing characteristics, workflow suggestions, examples.
+</output>
+
+---
+
+### `/story template [type]`
+
+Display story templates by type.
+
+<when>
+- Without argument: Show all templates
+- With type: Show specific template (bug, feature, refactor, chore)
+</when>
+
+<run>
+.pennyfarthing/scripts/core/run.sh story/story-template.sh [type]
+</run>
+
+<example>
+.pennyfarthing/scripts/core/run.sh story/story-template.sh           # All templates
+.pennyfarthing/scripts/core/run.sh story/story-template.sh bug       # Bug template
+.pennyfarthing/scripts/core/run.sh story/story-template.sh feature   # Feature template
+</example>
+
+<output>
+YAML template with acceptance criteria patterns.
+</output>
+
+---
+
+### `/story create <epic-id> "<title>" <points> [options]`
+
+Generate a story YAML block for adding to sprint.
+
+<run>
+.pennyfarthing/scripts/core/run.sh story/create-story.sh <epic-id> "<title>" <points> [options]
+</run>
+
+<args>
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `epic-id` | Yes | Parent epic (e.g., `MSSCI-11952`) |
+| `title` | Yes | Story title (quoted) |
+| `points` | Yes | Story points (1, 2, 3, 5, 8) |
+</args>
+
+<output>
+| Option | Values | Default | Description |
+|--------|--------|---------|-------------|
+| `--type` | bug, feature, refactor, chore | feature | Story type |
+| `--workflow` | (project-defined) | auto | Override auto-workflow |
+| `--priority` | P0, P1, P2, P3 | P2 | Priority level |
+| `--repos` | (project-defined) | - | Affected repos |
+| `--jira` | flag | - | Also show Jira create command |
+</output>
+
+<example>
+# Simple feature
+.pennyfarthing/scripts/core/run.sh story/create-story.sh MSSCI-11952 "Add error handling" 3
+
+# Bug fix
+.pennyfarthing/scripts/core/run.sh story/create-story.sh MSSCI-11952 "Fix null pointer" 2 --type bug
+
+# Chore with explicit workflow
+.pennyfarthing/scripts/core/run.sh story/create-story.sh MSSCI-11952 "Update deps" 1 --type chore
+
+# With Jira command
+.pennyfarthing/scripts/core/run.sh story/create-story.sh MSSCI-11952 "New feature" 5 --jira
+</example>
+
+<output>
+YAML block ready to paste into `sprint/current-sprint.yaml`
+</output>
+
+---
+
+### `/story finish <story-id> [--dry-run]`
+
+Complete a story: archive session, merge PR, transition Jira, update sprint YAML.
+
+<critical>
+Prerequisites before running:
+- Session file exists at `.session/{story-id}-session.md`
+- PR is approved and mergeable
+- Reviewer has approved (phase: finish in session)
+</critical>
+
+<run>
+.pennyfarthing/scripts/core/run.sh workflow/finish-story.sh <story-id> [--dry-run]
+</run>
+
+<args>
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `story-id` | Yes | Story ID (e.g., `MSSCI-12052`) |
+| `--dry-run` | No | Show what would be done without executing |
+</args>
+
+<example>
+.pennyfarthing/scripts/core/run.sh workflow/finish-story.sh MSSCI-12052           # Finish story
+.pennyfarthing/scripts/core/run.sh workflow/finish-story.sh MSSCI-12052 --dry-run # Preview only
+</example>
+
+<output>
+1. Archives session file to `sprint/archive/{jira-key}-session.md`
+2. Squash merges PR and deletes remote branch
+3. Transitions Jira issue to Done
+4. Updates sprint YAML (status: done, completed date, removes assigned_to)
+5. Deletes local feature branch
+6. Removes session file
+
+Step-by-step progress with final summary and Jira link.
+</output>
+
+---
+
+## Sizing Quick Reference
+
+| Points | Scale | Complexity | Examples |
+|--------|-------|------------|----------|
+| 1-2 | Trivial | Single file, minimal testing | Config, typo, simple fix |
+| 3 | Small | Few files, some testing | Validation, single component |
+| 5 | Medium | Multiple files, comprehensive testing | New page, API endpoint |
+| 8 | Large | Significant scope, extensive testing | Integration, major refactor |
+| 13+ | **SPLIT** | Too complex for single story | Break into smaller stories |
+
+## Workflow Selection
+
+Workflows define the development process for a story. Common patterns:
+
+| Workflow | When to Use |
+|----------|-------------|
+| `trivial` | Quick changes, no new tests needed |
+| `tdd` | Standard development with test coverage |
+| `agent-docs` | Documentation-focused work |
+| `bdd` | Behavior-driven development |
+
+<output>
+Auto-selection heuristics:
+- 1-2 point chores/bugs → `trivial`
+- 3+ point features → `tdd`
+- Documentation tasks → `agent-docs`
+</output>
+
+<when>
+Projects can define custom workflows in `pennyfarthing-dist/workflows/`.
+</when>
+
+## Acceptance Criteria Patterns
+
+### Good AC (SMART)
+
+<example>
+- "Admin users can access /admin/settings without 403"
+- "API returns 204 No Content on successful DELETE"
+- "Tests cover admin, manager, analyst roles"
+</example>
+
+### Bad AC (Vague)
+
+<critical>
+Avoid these patterns:
+- "Feature works correctly"
+- "No bugs"
+- "Good performance"
+</critical>
+
+---
+
+## Related Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `/sprint` | Sprint management, backlog, start work |
+| `/jira` | Jira operations (create in Jira, sync, claim) |
+| `/workflow` | View/set workflow definitions |
+
+## File Locations
+
+| File | Purpose |
+|------|---------|
+| `sprint/current-sprint.yaml` | Add new stories here |
+| `sprint/planning.yaml` | Future epics/stories |
+| `pennyfarthing-dist/workflows/` | Workflow definitions |