XP Work Manager Skill - Usage Guide

This skill helps you record feedback, todos, bugs, and user goals into tracking files, and manage your iteration workflow in the Buckyverse project. It is for work tracking only, not branch management or code changes.

How to Use

Automatic Invocation

The skill is automatically invoked when you use any of these trigger commands in your chat:

Recording New Items

• Feedback/Improvements:

  • improve: [your request]
  • improve : [your request]
  • feedback: [your request]

• Tasks/Features:

  • feat: [description]
  • todo: [description]
  • task: [description]

• Bug Reports:

  • bug: [description]
  • bug report: [description]

• User Goals/Scenarios:

  • goal: [description]
  • scenario: [description]
  • user_goal: [description]
  • user_scenario: [description]

Managing Iteration Work

• Moving Items to Iteration:

  • add to iteration: [reference to section]
  • iteration: [reference to section]
  • add to iteration: [new text block] (for new items)

• Marking Items as Done:

  • done: [reference to section in ITERATION.md]

• Moving Items to Acceptance:

  • needs acceptance: [reference to section in ITERATION.md]
  • acceptance: [reference to section in ITERATION.md]

Manual Invocation

You can also manually invoke the skill by typing:

/xp_work

Use git-town for branch commands and add-book-to-buckyverse / pdf-to-wikijs-markdown for file-copy and OCR workflows.

Then describe what you want to record or manage.

Examples

Recording Feedback

improve: The GraphQL API could have better error messages for authentication failures

The agent will:

1. Ask clarifying questions if needed
2. Read the existing work/FEEDBACK.md file
3. Add a formatted entry with today's date
4. Confirm "It is now on the list"

Recording a Task

feat: Add dark mode support to the Intercom mobile app

The agent will add this to work/TODO.md with proper formatting.

Reporting a Bug

bug: Phoenix server crashes when processing large GraphQL queries over 10MB

The agent will add this to work/BUGS.md with issue and expected behavior sections.

Recording a User Goal

goal: User wants to plan a party and track all related tasks and purchases

The agent will add this to work/USER_GOALS.md with user goal, current state, success criteria, and related features.

Moving an Item to Iteration

add to iteration: Support Project-Level Tasks with Multiple Steps

The agent will:

1. Find the section "Support Project-Level Tasks with Multiple Steps" in one of the tracking files (FEEDBACK.md, TODO.md, USER_GOALS.md, or BUGS.md)
2. Remove that section from the source file
3. Format it according to the iteration template
4. Add it to the bottom of work/ITERATION.md
5. Include source information (which file it came from)
6. Confirm "Moved to iteration"

Adding a New Item to Iteration

iteration: Implement real-time notifications for task assignments

The agent will:

1. Add the new text block directly to work/ITERATION.md
2. Format it according to the iteration template
3. Mark source as "Manual Entry"
4. Confirm "Added to iteration"

Marking an Item as Done

done: Implement real-time notifications for task assignments

The agent will:

1. Find the section in work/ITERATION.md
2. Remove it from the file
3. Confirm "Marked as done and removed from iteration"

Moving an Item to Acceptance

needs acceptance: Implement real-time notifications for task assignments

The agent will:

1. Find the section in work/ITERATION.md
2. Remove it from ITERATION.md
3. Format it according to the acceptance template
4. Add it to the bottom of work/ACCEPTANCE.md
5. Include both the original date and the date moved to acceptance
6. Confirm "Moved to acceptance queue"

Tracking Files

The skill manages these files in the work/ directory (at project root):

• work/FEEDBACK.md - Feedback and improvement requests
• work/TODO.md - Tasks and features to implement
• work/BUGS.md - Bug reports and issues
• work/USER_GOALS.md - User goals and scenarios
• work/ITERATION.md - Current work items in the active iteration
• work/ACCEPTANCE.md - Work items awaiting product owner acceptance

Workflow Overview

The typical workflow follows this pattern:

1. Record items in FEEDBACK.md, TODO.md, BUGS.md, or USER_GOALS.md
2. Move to Iteration when ready to work on them
3. Work on items in ITERATION.md
4. Mark as Done when complete (removes from iteration)
5. Move to Acceptance when ready for product owner review (moves from iteration to acceptance queue)

Format Templates

The entry format templates are stored in the skill's assets/ directory:

• assets/feedback-template.md - Format template for feedback entries
• assets/todo-template.md - Format template for todo/task entries
• assets/bug-template.md - Format template for bug reports
• assets/user-goal-template.md - Format template for user goals/scenarios
• assets/iteration-template.md - Format template for iteration work items
• assets/acceptance-template.md - Format template for acceptance queue items

These templates define the structure and format for each entry type. The agent automatically references these templates when creating entries. If you need to modify the format structure, edit the corresponding template file in .cursor/skills/xp_work/assets/. Work files use project-relative paths: work/.

What the Skill Does

✅ Reads existing files to maintain format consistency
✅ Gets today's date automatically
✅ Asks clarifying questions when needed
✅ Generates descriptive titles
✅ Formats entries according to guidelines
✅ Appends to the end of files
✅ Moves sections between files (removes from source, adds to destination)
✅ Preserves file structure when removing sections
✅ Tracks source information for iteration items
✅ Manages iteration workflow (iteration → done → acceptance)

What the Skill Does NOT Do

❌ Implement any code changes
❌ Modify existing entries (except when moving them)
❌ Delete files
❌ Make decisions about priority or implementation
❌ Reorganize files beyond the defined workflow

The skill is read-only for tracking purposes (except for moving items between files as part of the workflow). You'll use these files to guide your development work separately.

Tips

1. Be specific: The more detail you provide, the better the entry will be
2. Answer questions: If the agent asks for clarification, provide it for a better entry
3. Check the files: Review work/FEEDBACK.md, work/TODO.md, work/BUGS.md, and work/USER_GOALS.md to see your tracked items
4. Use context: Mention which application/module the item relates to (e.g., "Estate API", "Intercom app")
5. Reference sections clearly: When moving items, use the exact section title from the file
6. Review iteration regularly: Check work/ITERATION.md to see what's currently in progress
7. Track acceptance: Review work/ACCEPTANCE.md to see what's ready for product owner review

Section References

When referencing sections for moving items, you can use:

• Section title: The exact ## Title from the markdown file
• Partial title: A unique portion of the title that identifies the section
• Line number: If you know the approximate line number (the agent will find the containing section)

The agent will search for the section and extract the entire section including the heading and all content.

Viewing the Skill

To view this skill in Cursor:

1. Open Cursor Settings (Cmd+Shift+J on Mac, Ctrl+Shift+J on Windows/Linux)
2. Navigate to Rules
3. Look for xp_work in the Agent Decides section