User Story Updater Agent

Role: Updates GitHub issues for individual user stories to include checkable acceptance criteria and task connections.

🚀 How to Invoke This Agent

Subagent Type: specweave-github:user-story-updater:user-story-updater

Usage Example:

Task({
  subagent_type: "specweave-github:user-story-updater:user-story-updater",
  prompt: "Update GitHub issue #501 for user story FS-031/US-004 with checkable ACs and task connections",
  model: "opus" // default: opus (best quality)
});

Naming Convention: {plugin}:{directory}:{yaml-name-or-directory-name}

• Plugin: specweave-github
• Directory: user-story-updater
• Agent Name: user-story-updater

When to Use:

• You need to sync user story details from SpecWeave to GitHub issues
• You want to add checkable acceptance criteria checkboxes to GitHub issues
• You need to link tasks in SpecWeave tasks.md to GitHub issues
• You're updating GitHub issue content with the latest user story information and progress

Activates For:

• "Update user story issue"
• "Fix GitHub issue format for US-004"
• "Add checkable ACs to GitHub issue"
• "Refresh user story issue #501"
• "Sync user story to GitHub"

Capabilities:

1. Parse User Story Files (us-*.md from living docs)

   • Extract frontmatter (id, epic, status, priority)
   • Parse user story description (As a... I want... So that...)
   • Extract acceptance criteria with completion status
   • Find related tasks from increment tasks.md

2. Build Rich GitHub Issue Content

   • Convert ACs to GitHub task checkboxes (- [x] or - [ ])
   • Link tasks to increment tasks.md with anchors
   • Calculate progress percentages
   • Format with proper sections

3. Update Existing Issues

   • Search for existing issue by title pattern
   • Replace issue body with new formatted content
   • Preserve issue number and URL

Tools You Have:

• Read - Read user story files and tasks.md
• Bash - Execute gh CLI commands
• Write - Create TypeScript if needed

Workflow:

When user says "update user story issue for FS-031/US-004":

// 1. Find user story file
const projectRoot = process.cwd();
const userStoryPath = await findUserStoryFile(projectRoot, 'FS-031', 'US-004');
// Result: .specweave/docs/internal/specs/default/FS-031/us-004-bidirectional-status-sync.md

// 2. Parse and build content
import { UserStoryContentBuilder } from './lib/user-story-content-builder.js';
const builder = new UserStoryContentBuilder(userStoryPath, projectRoot);
const content = await builder.parse();
const issueBody = await builder.buildIssueBody();

// 3. Find existing GitHub issue
const searchResult = await bash(`gh issue list --search "[FS-031][US-004]" --json number,title`);
const issue = JSON.parse(searchResult)[0];

// 4. Update issue
await bash(`gh issue edit ${issue.number} --body "${issueBody}"`);

// 5. Report success
console.log(`✅ Updated issue #${issue.number}`);
console.log(`🔗 https://github.com/owner/repo/issues/${issue.number}`);

Example Execution:

User: "Fix the display of GitHub issue #501 for US-004"

Agent: "I'll update GitHub issue #501 for US-004 to include checkable ACs and task connections.

🔍 Finding user story: FS-031/US-004
   📄 Found: .specweave/docs/internal/specs/default/FS-031/us-004-bidirectional-status-sync.md

📖 Parsing content...
   ✅ User story description: As a PM, I want status changes...
   ✅ 6 acceptance criteria (4 completed, 2 pending)
   ✅ 6 tasks linked from increment 0031

📝 Building issue body...
   ✅ ACs converted to checkboxes
   ✅ Tasks linked to tasks.md
   ✅ Progress calculated: 67% ACs, 50% tasks

🚀 Updating GitHub issue #501...
   [gh issue edit 501 --body "..."]
   ✅ Updated successfully!

🔗 View issue: https://github.com/anton-abyzov/specweave/issues/501

Key Implementation Details:

1. Find User Story File:

   # Search in all projects
   find .specweave/docs/internal/specs -name "us-004-*.md" -path "*/FS-031/*"
   

2. Parse User Story (use UserStoryContentBuilder):

   • Frontmatter: YAML parsing
   • ACs: Pattern - [x] **AC-US4-01**: Description (P1, testable)
   • Tasks: Extract from Implementation section
   • Increment: Pattern **Increment**: [0031-name](...)

3. Build Issue Body:

   • See UserStoryContentBuilder.buildIssueBody()
   • Sections: User Story, Acceptance Criteria, Implementation Tasks
   • Checkboxes: - [x] for completed, - [ ] for pending
   • Links: Relative to repository root

4. Update GitHub Issue:

   # Find issue
   gh issue list --search "[FS-031][US-004]" --json number,title --jq '.[0].number'
   
   # Update body
   gh issue edit 501 --body "$(cat body.md)"
   

Error Handling:

• ✅ User story file not found → Search all projects, suggest alternatives
• ✅ GitHub issue not found → Offer to create new issue
• ✅ Missing frontmatter → Graceful fallback with warnings
• ✅ No tasks found → Show "No tasks defined yet"

Related Files:

• plugins/specweave-github/lib/user-story-content-builder.ts - Core builder class
• plugins/specweave-github/commands/update-user-story.md - Command spec
• .specweave/docs/internal/specs/{project}/FS-*/us-*.md - User story files

Testing:

1. Read user story file: us-004-bidirectional-status-sync.md
2. Use UserStoryContentBuilder to parse
3. Build issue body
4. Update issue #501
5. Verify checkable ACs and task links work

Success Criteria:

• ✅ GitHub issue has checkable ACs (can check/uncheck in UI)
• ✅ Tasks link to correct increment tasks.md sections
• ✅ Progress percentages match reality
• ✅ User story description formatted correctly