Add Item Mode

You are now in Add Item Mode. Your role is to interactively gather details about a new work item, create a repository issue, link it to the configured GitHub Project, and set appropriate custom fields.

Your Focus

• Interactive gathering: Ask user for title, description, priority, size, and status
• Issue creation: Create repository issue via gh issue create
• Project linking: Add issue to project via gh-api-scripts add-to-project
• Field updates: Set custom fields via gh-api-scripts operations (set-status, set-priority, set-size)

Required Skills

IMPORTANT: Before performing any GitHub Project operations, you MUST invoke the compass-rose:gh-api-scripts skill using the Skill tool:

Skill(compass-rose:gh-api-scripts)

This skill provides:

• add-to-project - Link issue to project
• set-status - Set status field
• set-priority - Set priority field
• set-size - Set size field

Do NOT use raw gh project commands. The skill documentation shows exact command syntax using ${CLAUDE_PLUGIN_ROOT}.

Workflow

1. Verify Configuration

The gh-api-scripts skill handles configuration loading and validation. Verify config exists before gathering user input:

# Check config exists (detailed validation done by gh-api-scripts operations)
if [ ! -f .compass-rose/config.json ]; then
  echo "Error: Configuration file not found."
  echo ""
  echo "Please create .compass-rose/config.json with your project details."
  exit 1
fi

Configuration validation is performed by the add-to-project operation - if config is missing or invalid, it returns structured error responses.

2. Gather Item Details

Interactively prompt the user for the following details:

2.1. Title (Required)

What is the title of the new item?

Example: "Fix login timeout bug" or "Add dark mode support"

Validation:

• Must not be empty
• Keep concise (ideally <80 characters)

2.2. Description (Optional)

Provide a description for this item (optional, press Enter to skip):

Include:
- What needs to be done
- Why it's important
- Any relevant context or links
- Acceptance criteria (for larger items)

Default: Empty string if user skips

2.3. Priority

Select priority for this item:

Available options:
1. P0 - Critical
2. P1 - High
3. P2 - Medium
4. P3 - Low

Enter number (1-4) or press Enter for P2 (default):

Default: P2 (medium priority) if user skips Validation: Must be one of the project's configured priority options

2.4. Size

Select size estimate for this item:

Available options:
1. S - Small (< 4 hours)
2. M - Medium (1-2 days)
3. L - Large (3-5 days)
4. XL - Extra Large (> 1 week, consider spec)

Enter number (1-4) or press Enter for M (default):

Default: M (medium) if user skips Validation: Must be one of the project's configured size options

XL Warning: If user selects XL:

XL items typically benefit from formal specification.

Consider using /lore-development:specify to create a detailed spec before implementation.
This ensures clear success criteria and reduces scope creep.

Continue with XL size? (y/n):

2.5. Status

Select initial status for this item:

Available options:
1. Ready - Ready for implementation
2. To Do - Backlog (needs refinement)
3. Blocked - Cannot proceed yet

Enter number (1-3) or press Enter for "Ready" (default):

Default: "Ready" if user skips Validation: Must be one of the project's configured status options

3. Create Repository Issue

Use gh issue create to create the issue first:

# Get repository name from git remote
REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner)

# Create issue and capture URL
ISSUE_URL=$(gh issue create \
  --title "$TITLE" \
  --body "$DESCRIPTION" \
  --repo "$REPO" \
  --json url \
  --jq .url)

# Extract issue number from URL (for confirmation message)
ISSUE_NUMBER=$(echo "$ISSUE_URL" | grep -oP '\d+$')

Error Handling:

Error: Failed to create repository issue.

Verify that:
1. You have write access to the repository
2. You are authenticated: gh auth status
3. The repository exists: gh repo view

4. Add Issue to Project

Use the add-to-project operation from the gh-api-scripts skill (which you invoked earlier). The skill documentation shows the exact command syntax using ${CLAUDE_PLUGIN_ROOT}.

Note: The config must include a repository field for add-to-project to work. The script returns structured errors for missing config or authentication issues.

5. Set Custom Fields

Use the set-status, set-priority, and set-size operations from the gh-api-scripts skill. Each operation handles field discovery internally. The skill documentation shows the exact command syntax using ${CLAUDE_PLUGIN_ROOT}.

Notes:

• Each operation is independent - if one fails, continue with the remaining fields
• Operations handle field discovery internally (no need to query field IDs)
• The FIELD_NOT_FOUND error indicates the project doesn't have that field configured

Error Handling:

Warning: Failed to set <field> field.

The item was created successfully but some fields could not be set.
You can manually update these fields in the GitHub Projects web UI.

6. Confirm Creation

Display summary of created item:

Item created successfully!

Issue: #<issue-number> - <title>
Link: <issue-url>

Fields set:
- Priority: <priority-value>
- Size: <size-value>
- Status: <status-value>

View in project: https://github.com/orgs/<owner>/projects/<number>

If any fields failed to set:

Item created successfully!

Issue: #<issue-number> - <title>
Link: <issue-url>

Fields set:
- Priority: <priority-value>
- Size: <size-value>

Could not set: Status (manual update required)

View in project: https://github.com/orgs/<owner>/projects/<number>

7. Handle Edge Cases

No Custom Fields Available:

Note: This project has no custom fields configured. Only title and description
will be set.

The item will be created as a basic repository issue linked to the project.

Authentication Issues:

Error: GitHub CLI is not authenticated.

Run the following command to authenticate:
  gh auth login

After authentication, you may need to add the 'project' scope:
  gh auth refresh -s project

Repository Not Found:

Error: Could not determine repository.

Verify that:
1. You are in a git repository: git status
2. Repository has a GitHub remote: git remote -v
3. You have access to the repository: gh repo view

User Cancellation: If user enters "cancel" or "exit" at any prompt:

Item creation cancelled. No changes made.

Requirements Mapping

This skill implements the following specification requirements:

• REQ-F-8: Create new repository issues (not draft items)
• REQ-F-9: Update issue custom fields (Priority, Size, Iteration, Status)
• REQ-F-10: Link newly created issues to the configured project
• REQ-F-7: Handle projects with custom field configurations gracefully
• REQ-NF-3: Handle missing custom fields gracefully (warn, don't fail)
• Explicit Constraint #1: Do NOT create draft items (always create proper repository issues)

Implementation Notes

Performance Targets:

• Config check: <100ms (local file read)
• Issue creation: <2s (gh issue create)
• Project linking: <1s (gh-api-scripts add-to-project)
• Field updates: <1s per field (gh-api-scripts set-status/set-priority/set-size)
• Total operation: <5s end-to-end (for 3 fields)

Data Flow:

1. Verify config -> 2. Gather input -> 3. Create issue ->
2. Link to project -> 5. Set fields -> 6. Confirm

CLI Dependencies:

• gh CLI installed and authenticated
• project scope authorized (gh auth refresh -s project)
• jq for JSON parsing
• git for repository context
• Python 3.12+ for gh-api-scripts skill

Two-Step Creation Process: Following TD-5 from the plan, we ALWAYS create repository issues first, then link to project. This ensures:

• Issues have proper issue numbers for reference
• Issues appear in repository Issues tab
• Issues can be linked across multiple projects if needed
• Better visibility and integration with GitHub ecosystem

Example Session

--- Create New Item ---

What is the title of the new item?
> Fix authentication timeout on mobile

Provide a description for this item (optional, press Enter to skip):
> Users on mobile devices are experiencing session timeouts after 30 seconds
> of inactivity. The web app timeout is configured for 30 minutes.
>
> Acceptance criteria:
> - Mobile timeout matches web (30 minutes)
> - Existing sessions are not affected
> - Timeout is configurable via environment variable

Select priority for this item:

Available options:
1. P0 - Critical
2. P1 - High
3. P2 - Medium
4. P3 - Low

Enter number (1-4) or press Enter for P2 (default):
> 1

Select size estimate for this item:

Available options:
1. S - Small (< 4 hours)
2. M - Medium (1-2 days)
3. L - Large (3-5 days)
4. XL - Extra Large (> 1 week, consider spec)

Enter number (1-4) or press Enter for M (default):
> 1

Select initial status for this item:

Available options:
1. Ready - Ready for implementation
2. To Do - Backlog (needs refinement)
3. Blocked - Cannot proceed yet

Enter number (1-3) or press Enter for "Ready" (default):
> 1

Creating repository issue...
Issue created: #156

Linking to project...
Added to project

Setting custom fields...
Priority set to P0
Size set to S
Status set to Ready

Item created successfully!

Issue: #156 - Fix authentication timeout on mobile
Link: https://github.com/my-org/my-repo/issues/156

Fields set:
- Priority: P0
- Size: S
- Status: Ready

View in project: https://github.com/orgs/my-org/projects/123

Anti-Patterns to Avoid

• Don't use raw gh commands: Always use gh-api-scripts skill for GitHub Project operations
• Don't skip config validation: Always verify config exists before proceeding
• Don't fail on missing fields: Warn user and continue with available fields
• Don't create draft items: ALWAYS create repository issues (per spec constraint)
• Don't skip confirmation: Always show summary of created item with link
• Don't store credentials: Rely on gh CLI authentication
• Don't skip XL warning: Always prompt user when they select XL size

Related Skills

• /compass-rose:next-item - Find next work item to tackle
• /compass-rose:backlog - Review entire backlog
• /compass-rose:start-work - Begin implementation of item
• /lore-development:specify - Create formal spec for large items (Lore Development integration)

References

• Spec: REQ-F-8, REQ-F-9, REQ-F-10, REQ-F-7, REQ-NF-3, Explicit Constraint #1
• Plan: TD-5 (Item Type Strategy - Repository Issues Only)
• Skill: compass-rose/skills/gh-api-scripts/SKILL.md (GitHub Project API operations)