Issue First

Issue-First Enforcement

Create Beads tracking issue BEFORE implementation (<30 seconds).

Purpose

Ensures Issue-First pattern: All implementation work tracked in Beads BEFORE coding starts.

Philosophy: Fast classification + Hierarchical tracking + No lost work

When to Use This Skill

Auto-activated when:

• User says "create X", "implement Y", "build Z"
• User says "fix bug", "refactor X", "update Y"
• User starts ANY implementation work without Beads issue

Trigger phrases:

• "create the X skill"
• "implement authentication"
• "fix the bug in X"
• "refactor Y component"
• "update Z service"

Workflow

1. Set Beads Context

mcp__plugin_beads_beads__set_context(
  workspace_root="/Users/fengning/prime-radiant-ai"
)

2. Check if Issue Already Exists

// Check current branch
currentBranch = git branch --show-current
// Extract Feature-Key if exists

if (currentBranch.startsWith("feature-")) {
  featureKey = extract_key(currentBranch)

  try {
    issue = mcp__plugin_beads_beads__show(issue_id=featureKey)
    // Issue exists, use it
    echo "✓ Using existing issue: ${issue.id}"
    return issue
  } catch {
    // No issue, continue to create
  }
}

3. Classify Work Type

Ask user to classify:

What type of work is this?

1. **epic** - Large feature with multiple phases (weeks)
   Examples: Authentication system, analytics dashboard

2. **feature** - New functionality (days)
   Examples: Add OAuth login, create export feature

3. **task** - Work item (hours to days)
   Examples: Write tests, update docs, refactor code

4. **bug** - Something broken (varies)
   Examples: Fix session timeout, resolve API error

5. **chore** - Maintenance (hours)
   Examples: Update dependencies, improve tooling

User provides: Type

4. Determine Priority

Ask user to confirm priority:

What priority? (Based on Beads convention)

0. **Critical** - Security, data loss, broken builds
1. **High** - Major features, important bugs
2. **Medium** - Default, nice-to-have (RECOMMENDED)
3. **Low** - Polish, optimization
4. **Backlog** - Future ideas

User provides: Priority number (default: 2)

5. Find Parent in Hierarchy

Analyze Beads context:

// Get current context
currentContext = bash: scripts/bd-context

// Parse for current epic/feature
if (currentContext contains epic or feature in_progress) {
  parentIssue = current epic/feature
} else {
  // Ask user
  readyWork = mcp__plugin_beads_beads__ready()

  echo "Current work context:"
  for issue in readyWork:
    echo "  ${issue.id}: ${issue.title} (${issue.type})"

  echo "\nIs this work under one of these? (or standalone?)"
}

Determine:

• Parent issue ID (if applicable)
• Hierarchical ID pattern (bd-xyz.N if child)

6. Create Tracking Issue

Generate title:

Format: [TYPE_PREFIX]: [DESCRIPTION]

Prefixes:
- epic: No prefix, just description
- feature: No prefix, just description
- task: "Task: " or phase-specific (Research/Spec/Implementation/Testing)
- bug: "Bug: "
- chore: "Chore: "

Create issue:

issue = mcp__plugin_beads_beads__create({
  title: generated_title,
  issue_type: work_type,  // epic/feature/task/bug/chore
  priority: priority_num,  // 0-4
  description: user_description,
  assignee: "claude-code",
  deps: parent_id ? [parent_id] : undefined,
  id: hierarchical_id  // e.g., bd-xpi.7 if child
})

Start work immediately:

mcp__plugin_beads_beads__update(
  issue.id,
  status="in_progress"
)

7. Optional: Setup Documentation

For epics and features only:

if (issue.type === "epic" || issue.type === "feature") {
  echo "\n📄 Setup documentation?"
  echo "   [y] Yes - Create docs/${issue.id}/ with templates"
  echo "   [n] No - Just track in Beads"
  echo "   (Recommended for epics/features)"

  read choice

  if (choice === "y") {
    // Call helper script
    bash: scripts/setup-feature-docs ${issue.id} "${issue.title}" ${issue.type}

    // Commit doc setup
    bash: git commit -m "docs: initialize ${issue.id} documentation

Feature-Key: ${issue.id}
Agent: claude-code
Role: doc-setup"

    echo "\n✅ Documentation created: docs/${issue.id}/"
  }
}

Why optional:

• Tasks/bugs don't need docs (update parent docs)
• User controls (can say no)
• Epics/features benefit most from templates

8. Confirm and Pass Control

Confirm to user:

✅ Created tracking issue: ${issue.id}
📋 Type: ${issue.type} | Priority: P${issue.priority}
🔗 Parent: ${parent_id || 'standalone'}
📍 Status: in_progress
📄 Docs: ${docs_created ? `docs/${issue.id}/` : 'None (Beads only)'}

Proceed with implementation using Feature-Key: ${issue.id}

Optional: External Documentation

If this epic/feature requires external reference docs (API docs, guides, tool documentation):

💡 Tip: Create epic-specific doc skill with:
   /docs-create ${issue.id} <url1> <url2> <url3> ...

This caches docs and creates auto-activating skill for this epic.

Only mention if user hasn't already set up docs. Keep it brief - just a pointer, not required.

9. Auto-Create Feature Branch (When on Master)

For epics, features, and P0-P1 work only:

After creating the Beads issue, automatically create a matching git branch if currently on master.

Decision Logic:

const currentBranch = git branch --show-current
const shouldCreateBranch = (
  currentBranch === "master" &&
  (issue.type === "epic" ||
   issue.type === "feature" ||
   issue.priority <= 1)
)

if (!shouldCreateBranch) {
  // Skip if:
  // - Already on a feature branch (resume work)
  // - Working on tasks/bugs/chores (P2+, trunk workflow OK)
  return
}

Branch Creation Flow:

# Auto-create branch (no prompt when on master)
echo "\n🌿 Creating feature branch for ${issue.id}..."
echo "   Branch name: feature-${issue.id}"
echo "   (Auto-created for ${issue.type}, P${issue.priority} on master)"
echo ""
# Call helper script (handles all edge cases)
bash scripts/git-create-feature-branch "${issue.id}" "${issue.type}" ${issue.priority}

exit_code=$?

case $exit_code in
  0)
    # Success
    echo "✅ Branch created: feature-${issue.id}"
    echo "   Ready to code!"
    ;;

  3)
    # Needs commit first
    echo "⚠️  Uncommitted changes detected on master."
    echo "   Auto-committing current work before branch creation..."
    echo ""

    # Invoke sync-feature-branch skill automatically
    # (User would say: "commit my work")
    # After commit completes, retry branch creation
    bash scripts/git-create-feature-branch "${issue.id}" "${issue.type}" ${issue.priority}
    ;;

  *)
    # Error
    echo "❌ Failed to create branch"
    echo "   Falling back to master branch workflow."
    echo "   You can manually create branch later: git checkout -b feature-${issue.id}"
    ;;
esac

Why Automatic (No Prompt):

• Prevents accidental commits to master for large/important work
• Small tasks/bugs (P2+) still use trunk workflow (not auto-created)
• Auto-detects uncommitted changes and commits them first
• Guarantees clean git state before branch creation
• User requested: "wouldn't that have made the process way easier?" (bd-axb)

Clean State Guarantees:

The git-create-feature-branch script ensures:

1. ✅ Pre-flight checks:

   • Uncommitted changes → Offer auto-commit via sync-feature-branch
   • Staged changes → Offer auto-commit
   • Untracked files → Warn (won't carry over)
   • Branch exists → Error
   • Not in repo → Error

2. ✅ Creation:

   • Always create from master/main (latest)
   • Never carry uncommitted changes
   • Checkout new branch automatically

3. ✅ Post-verification:

   • Verify on correct branch
   • Verify clean working tree
   • Verify no staged changes

Next Step: Check for Matching Skill

Before implementing directly, check if a specialized subagent or skill exists:

1. For complex work, use specialized subagents (.claude/agents/):

   • "backend/api/service/endpoint" → Task(subagent_type="backend-engineer")
   • "frontend/component/ui/page" → Task(subagent_type="frontend-engineer")
   • "security/auth/encryption" → Task(subagent_type="security-engineer")
   • "devops/ci/deployment" → Task(subagent_type="devops-engineer")
   • "testing/e2e/integration" → Task(subagent_type="quality-assurance-tester")

2. For workflow automation, use skills (.claude/skills/):

   • "create skill" → skill-creator
   • "commit work" → sync-feature-branch
   • "open PR" → create-pull-request

3. If using subagent:

   Task(
     subagent_type="subagent-name",
     prompt="Implement ${issue.title} for ${issue.id}"
   )
   

4. If no specialized tool: Implement directly using Feature-Key: ${issue.id}

Implementation continues with:

• Feature-Key: ${issue.id}
• All commits include Feature-Key trailer
• Close issue when complete

Classification Rules

Epic vs Feature

Examples:

• "Authentication system" → Epic (OAuth + JWT + sessions + 2FA)
• "Add OAuth login button" → Feature (single component)

Task vs Bug vs Chore

Priority Guidelines

Hierarchical ID Assignment

Pattern:

bd-xyz (Parent)
├── bd-xyz.1 (Child 1)
├── bd-xyz.2 (Child 2)
│   ├── bd-xyz.2.1 (Grandchild 1)
│   └── bd-xyz.2.2 (Grandchild 2)
└── bd-xyz.3 (Child 3)

How to determine ID:

if (parentIssue exists) {
  // Get existing children
  parent = mcp__plugin_beads_beads__show(parent_id)

  // Count children (dependents with discovered-from or blocks)
  childCount = parent.dependents.filter(d =>
    d.type === "discovered-from" || d.type === "blocks"
  ).length

  // Next child ID
  hierarchical_id = `${parent_id}.${childCount + 1}`
} else {
  // Standalone issue, Beads auto-generates ID
  hierarchical_id = undefined  // Let Beads assign bd-xxx
}

Integration Points

With Beads

Core operations:

• set_context() - Required first step
• show() - Check if issue exists
• ready() - Find parent context
• create() - Create tracking issue
• update() - Set status to in_progress

Hierarchy:

• Use deps parameter for parent-child
• Hierarchical IDs track structure
• discovered-from for work found during implementation

With Implementation

After issue-first completes:

1. User proceeds with implementation
2. All commits include: Feature-Key: ${issue.id}
3. When done: Close issue via sync-feature-branch or manually
4. PR links to issue automatically

With Other Skills

Relationship:

• issue-first → Creates tracking issue
• beads-workflow → Creates epics with phases (uses issue-first internally)
• sync-feature-branch → Commits with Feature-Key
• create-pull-request → Links PR to issue

Best Practices

Do

✅ Always create issue BEFORE coding ✅ Classify accurately (epic/feature/task/bug/chore) ✅ Use correct priority (P2 default) ✅ Link to parent when applicable ✅ Set status to in_progress immediately ✅ Use hierarchical IDs for children ✅ Commit with Feature-Key: ${issue.id}

Don't

❌ Skip for "quick fixes" (>10 lines = not quick) ❌ Create issue after implementation starts ❌ Guess at classification (ask user) ❌ Default everything to feature ❌ Forget to link to parent ❌ Leave status as open (start work immediately)

What This Skill Does

✅ Detects implementation work without tracking issue ✅ Classifies work type (epic/feature/task/bug/chore) ✅ Determines priority (0-4) ✅ Finds parent in Beads hierarchy ✅ Generates hierarchical ID if child ✅ Creates Beads tracking issue ✅ Sets status to in_progress ✅ Offers to create feature branch (epics/features/P0-P1) ✅ Ensures clean git state before branch creation ✅ Auto-recovers from uncommitted changes ✅ Passes control to implementation with Feature-Key

What This Skill DOESN'T Do

❌ Implement the actual work (just creates tracking) ❌ Force creation for tiny edits (<10 lines) ❌ Create issue if one already exists ❌ Block workflow (fast classification only) ❌ Make decisions without user input

Examples

Example 1: Create Skill (Task)

Hook detects: "create the skill-creator skill"

issue-first activates:

1. Set Beads context ✓
2. Check existing: No issue found
3. Classify:
   User: "This is a task"
   AI: ✓ task

4. Priority:
   AI: "Default P2 for normal work?"
   User: "Yes, P2"

5. Parent:
   AI detects: bd-xpi (DX_V3_BEADS_INTEGRATION) in progress
   AI: "This work is under bd-xpi?"
   User: "Yes"

   Children of bd-xpi: bd-xpi.1 through bd-xpi.6 exist
   Next ID: bd-xpi.7

6. Create:
   mcp__plugin_beads_beads__create({
     title: "Implementation: skill-creator meta-skill",
     issue_type: "task",
     priority: 2,
     id: "bd-xpi.7",
     deps: ["bd-xpi"],
     assignee: "claude-code"
   })

7. Confirm:
   ✅ Created: bd-xpi.7
   📋 Type: task | Priority: P2
   🔗 Parent: bd-xpi
   📍 Status: in_progress

   Feature-Key: bd-xpi.7

User proceeds with skill-creator implementation.

Example 2: Fix Bug (Bug)

User: "fix the session timeout bug"

issue-first:

1. Classify: bug (something broken)
2. Priority: P1 (high - security/ux issue)
3. Parent: bd-auth (current authentication work)
   Next ID: bd-auth.3

4. Create:
   mcp__plugin_beads_beads__create({
     title: "Bug: Session timeout not handled",
     issue_type: "bug",
     priority: 1,
     id: "bd-auth.3",
     deps: ["bd-auth"]
   })

5. Status: in_progress

Feature-Key: bd-auth.3

User proceeds with bug fix.

Example 3: Standalone Feature

User: "add export to CSV feature"

issue-first:

1. Classify: feature
2. Priority: P2
3. Parent: None (standalone)

4. Create:
   mcp__plugin_beads_beads__create({
     title: "CSV_EXPORT_FEATURE",
     issue_type: "feature",
     priority: 2,
     assignee: "claude-code"
   })
   # Returns: bd-new (Beads auto-generates)

5. Status: in_progress

Feature-Key: bd-new

User proceeds with CSV export implementation.

Troubleshooting

Issue Already Exists

Symptom: Beads says "issue ID already exists"

Solution: Check current branch/context, use existing issue instead of creating new one

Can't Determine Parent

Symptom: Unclear what parent should be

Solution:

// Show all in-progress work
mcp__plugin_beads_beads__list(status="in_progress")

// Ask user to choose or create standalone

Classification Unclear

Symptom: User unsure if epic vs feature, or task vs bug

Solution:

• Epic vs Feature: Ask about timeline and phases
• Task vs Bug: Ask "is something broken?" (bug) or "is this new work?" (task)

Related Skills

• beads-workflow: Creates epics with phase tasks (uses issue-first pattern)
• sync-feature-branch: Commits with Feature-Key from this skill
• create-pull-request: Links PR to issue created by this skill
• fix-pr-feedback: Creates child issues using same pattern

Resources

Beads reference:

• Official AGENTS.md: https://github.com/steveyegge/beads/blob/main/AGENTS.md
• Issue types: bug, feature, task, epic, chore
• Priorities: 0 (critical) → 4 (backlog)
• Hierarchical IDs: bd-xyz.N pattern

Last Updated: 2025-01-17 Skill Type: Workflow Average Duration: <30 seconds (+ branch creation if opted) Related Docs:

• https://github.com/steveyegge/beads/blob/main/AGENTS.md
• .claude/skills/beads-workflow/SKILL.md
• AGENTS.md (Issue-First core principle) Related Scripts:
• scripts/git-create-feature-branch
• scripts/lib/git-state-checks.sh