Issue Create

Skill access pattern (post-kernel-pivot, 2026.5+)

Skill names referenced in this document are AIWG skills, not slash commands. Most are not kernel-listed and cannot be invoked as /skill-name by the platform. Reach them via:

aiwg discover "<capability>"
aiwg show skill <name>

Only kernel-listed skills (aiwg-doctor, aiwg-refresh, aiwg-status, aiwg-help, use, steward) are directly invokable as slash commands. See skill-discovery rule.

Issue Create

Semantic Label Contract (#1789)

Resolve the target workspace member first and check its issue-comment capability. Then resolve that member's .aiwg/aiwg.config remotes.issue_tracker, remotes.tracker_actor, and issues.labels before translating any semantic label role into a tracker-native string. Validate the resolved label against the target tracker catalog. Preserve caller-supplied unrelated labels, report unavailable roles, and never provision a missing label implicitly. If issues.labels is absent, retain legacy behavior with an explicit fallback warning rather than silently guessing project semantics. Reject any write route whose authenticated login is listed in the target member's forbid_actors.

Purpose

Create a new ticket/issue for tracking work items, bugs, features, or tasks. Automatically uses the configured ticketing provider (Gitea, GitHub, Jira, Linear) or falls back to local file-based tracking.

Task

Given a ticket title and optional description:

1. Resolve the target member and authorization, then load its .aiwg/aiwg.config
2. Validate configuration and authenticate with provider
3. Check for regressions (if bug report with --check-regression)
4. Compose and assess the final draft before any write; split it at enforced policy boundaries when possible
5. Create only approved ticket segment(s) using the appropriate backend (MCP, CLI, or local file), then cross-link split siblings
6. Return ticket reference(s) and deterministic recovery state if a multi-ticket write stops partway through

Parameters

• <title> (required): Short, descriptive title for the ticket
• [description] (optional): Detailed description of the work item
• --provider NAME (optional): Override configured provider (gitea|github|jira|linear|local)
• --labels "label1,label2" (optional): Comma-separated labels/tags
• --assignee USER (optional): Assign to specific user
• --priority LEVEL (optional): Priority level (low|medium|high|critical)
• --milestone NAME (optional): Associate with milestone (provider-dependent)
• --check-regression (optional): Run regression check for bug reports (auto-runs if labels include "bug" or "regression")

Inputs

Configuration sources (checked in order):

1. .aiwg/config.yaml - Project-level configuration
2. CLAUDE.md - User-level configuration
3. Default: local provider

Required for Gitea:

• Provider: gitea
• URL: Base URL (e.g., https://git.integrolabs.net)
• Owner: User or organization name
• Repo: Repository name
• Token: ~/.config/gitea/token (or configured path)

Required for GitHub:

• Provider: github
• Owner: User or organization name
• Repo: Repository name
• Auth: gh CLI authenticated

Required for Jira:

• Provider: jira
• URL: Jira instance URL
• Owner: Project key
• Auth: JIRA_API_TOKEN environment variable

Required for Linear:

• Provider: linear
• URL: https://api.linear.app
• Owner: Team ID
• Auth: LINEAR_API_TOKEN environment variable

Required for Local:

• Provider: local
• Directory: .aiwg/issues/ (created if missing)

Outputs

Gitea/GitHub/Jira/Linear:

• Issue created on remote system
• Issue number returned
• URL to view ticket

Local:

• File created: .aiwg/issues/ISSUE-{num}.md
• Issue number returned
• File path returned

Workflow

Step 1: Parse Parameters

Extract from the user's request or from composed skill arguments:

# Basic request
Create an issue titled "Implement user auth"

# With description
Create an issue titled "Fix navigation bug" with the body "Nav menu not showing on mobile devices"

# With labels
Create an issue titled "Add dark mode" with labels "feature,ui"

# With assignee
Create an issue titled "Security audit", assign security-team, and mark it high priority

# Bug report with regression check
Create a bug issue titled "Login broken after deployment" and check whether it is a regression

# Override provider
Create a local issue titled "Local task" with the body "Quick reminder"

Parameter extraction:

• Title: First quoted argument (required)
• Description: Second quoted argument (optional, default: empty)
• Flags: Parse --flag value pairs

Step 2: Load Configuration

Resolution precedence (highest first):

1. --provider flag — explicit override always wins.
2. Target member .aiwg/aiwg.config remotes.issue_tracker (#994, #1764) — derive provider from that member remote's URL.
3. Legacy .aiwg/config.yaml (ticketing block) — back-compat for older projects.
4. CLAUDE.md "Issueing Configuration" block — fallback for projects pre-dating either.
5. local — default if nothing is configured.

Resolving from a workspace member (the preferred path):

import { authorizeWorkspaceOperation } from 'aiwg/config/workspace';

const decision = await authorizeWorkspaceOperation(workspaceDir, targetRepo, 'issue-comment');
if (!decision.allowed || !decision.member) throw new Error(decision.reason);
const provider = decision.member.issueTracker.provider;
const url = decision.member.issueTracker.url;
const actor = decision.member.remotes.tracker_actor;

When provider === 'unknown' (self-hosted instances we can't classify by URL), the operator must pass --provider explicitly. Don't guess.

Worked example for this repo (origin → git.integrolabs.net/roctinam/aiwg):

• resolved.issue_tracker = 'origin'
• git remote get-url origin = git@git.integrolabs.net:roctinam/aiwg.git
• resolveRemoteProvider(url) returns 'unknown' (the host doesn't include "gitea")
• → operator must set --provider gitea, OR the project's aiwg.config must set remotes.issue_provider: "gitea" so issue tooling can use that explicit tracker hint.

Override warning: if --provider differs from the auto-resolved one, print: ⚠️ Using --provider github (resolved from .aiwg/aiwg.config: gitea)

Step 3: Regression Detection (for Bug Reports)

Trigger conditions:

• Explicit: --check-regression flag provided
• Automatic: --labels contains "bug" OR "regression"
• Type: Issue is categorized as bug/defect

Regression check process:

# Detect if regression check should run
if [[ "$LABELS" == *"bug"* ]] || [[ "$LABELS" == *"regression"* ]] || [[ "$CHECK_REGRESSION" == "true" ]]; then
  echo "⏳ Running regression check..."

  # Run regression check against main branch
  /regression-check --baseline main --scope changed-files --format summary > /tmp/regression-results.md

  # Parse results
  REGRESSION_DETECTED=$(grep "REGRESSIONS DETECTED" /tmp/regression-results.md)

  if [ -n "$REGRESSION_DETECTED" ]; then
    # Escalate priority and add labels
    PRIORITY="critical"
    LABELS="${LABELS},regression-confirmed"

    # Extract regression details for issue body
    REGRESSION_SUMMARY=$(sed -n '/### Critical Regressions/,/###/p' /tmp/regression-results.md)

    # Append to description
    DESCRIPTION="${DESCRIPTION}

---

## Regression Analysis

${REGRESSION_SUMMARY}

**Full Report**: See attached regression-results.md"
  else
    # No regression detected
    LABELS="${LABELS},no-regression"
  fi
fi

Impact on issue creation:

Step 4: Validate Configuration

For each provider, validate required fields:

Gitea:

• url present and valid URL
• owner present
• repo present
• Token file exists and readable

GitHub:

• owner present
• repo present
• gh CLI installed (which gh)
• gh authenticated (gh auth status)

Jira:

• url present and valid URL
• owner (project key) present
• JIRA_API_TOKEN environment variable set

Linear:

• url present (default: https://api.linear.app)
• owner (team ID) present
• LINEAR_API_TOKEN environment variable set

Local:

• .aiwg/issues/ directory exists or can be created
• Directory is writable

Error handling:

• If validation fails, report error and suggest fix
• Optionally fall back to local provider with warning

Step 5: Policy-Boundary Composition (Required Before Every Write)

After regression metadata, labels, priority, and acceptance criteria are final, run the same threat policy that address-issues will apply later:

aiwg run skill issue-create -- plan \
  --title "$TITLE" \
  --body-file "$DRAFT_BODY_FILE" \
  --labels "$LABELS" \
  --project-root "$TARGET_REPO"

The returned aiwg.issue-composition-plan.v1 envelope is authoritative for the write step:

• single: create the one draft unchanged.
• authorization-required: do not write until the issue-specific policy authorization is recorded for the returned digest.
• split: create every segment in order, using its exact title, body, labels, priority, provider scope, and provenance marker.
• split-authorization-required: obtain authorization for the digest, then create every independently assessed segment in order.
• blocked: make no tracker mutation. Report blockingRule and the suggested human-editable segments.

Never delete the aiwg-policy-segment marker. Before retrying a partial split, search the target tracker for every marker in the recovery envelope and reuse existing matches. After all segments exist, replace {{AIWG_RELATED_ISSUES}} with sibling links and the declared dependency. This is what prevents a retry from duplicating the first issue after a later write fails.

This preflight is mandatory for Gitea MCP, tea, GitHub CLI/API, Jira, Linear, and local-file routes. Higher-level flows that author issues must call this skill or the same composer; they may not jump directly to a tracker create API.

Step 6: Create Issue (Provider-Specific)

Gitea

Use MCP tool mcp__gitea__create_issue:

# Load configuration
TOKEN=$(cat ~/.config/gitea/token)
URL="https://git.integrolabs.net"
OWNER="roctinam"
REPO="ai-writing-guide"

# Prepare issue body
BODY="${description}"

# Add metadata section if labels/assignee/priority specified
if [ -n "$LABELS" ] || [ -n "$ASSIGNEE" ] || [ -n "$PRIORITY" ]; then
  BODY="${BODY}\n\n---\n\n"
  [ -n "$LABELS" ] && BODY="${BODY}**Labels**: ${LABELS}\n"
  [ -n "$ASSIGNEE" ] && BODY="${BODY}**Assignee**: @${ASSIGNEE}\n"
  [ -n "$PRIORITY" ] && BODY="${BODY}**Priority**: ${PRIORITY}\n"
fi

# Create issue via MCP
# Note: Use actual MCP tool invocation here

MCP Tool Parameters:

• owner: Organization/user name
• repo: Repository name
• title: Issue title
• body: Issue description (markdown)
• assignee: Username (optional)
• labels: Array of label names (optional)

Return format:

✅ Issue created: ISSUE-42

View at: https://git.integrolabs.net/roctinam/ai-writing-guide/issues/42

Title: Implement user auth
Status: open
Labels: feature, high-priority

GitHub

Use gh CLI:

# Basic creation
gh issue create \
  --repo "${OWNER}/${REPO}" \
  --title "${TITLE}" \
  --body "${DESCRIPTION}"

# With labels
gh issue create \
  --repo "${OWNER}/${REPO}" \
  --title "${TITLE}" \
  --body "${DESCRIPTION}" \
  --label "${LABELS}"

# With assignee
gh issue create \
  --repo "${OWNER}/${REPO}" \
  --title "${TITLE}" \
  --body "${DESCRIPTION}" \
  --assignee "${ASSIGNEE}"

# With milestone
gh issue create \
  --repo "${OWNER}/${REPO}" \
  --title "${TITLE}" \
  --body "${DESCRIPTION}" \
  --milestone "${MILESTONE}"

Return format:

✅ Issue created: #42

View at: https://github.com/jmagly/aiwg/issues/42

Title: Implement user auth
Status: open
Labels: feature, high-priority

Jira

Use Jira REST API v3:

# Prepare JSON payload
cat > /tmp/jira-issue.json <<EOF
{
  "fields": {
    "project": {
      "key": "${PROJECT_KEY}"
    },
    "summary": "${TITLE}",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "${DESCRIPTION}"
            }
          ]
        }
      ]
    },
    "issuetype": {
      "name": "Task"
    },
    "priority": {
      "name": "${PRIORITY:-Medium}"
    }
  }
}
EOF

# Create issue
curl -X POST "${JIRA_URL}/rest/api/3/issue" \
  -u "${JIRA_EMAIL}:${JIRA_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/jira-issue.json

Return format:

✅ Issue created: PROJECT-42

View at: https://yourcompany.atlassian.net/browse/PROJECT-42

Title: Implement user auth
Status: To Do
Priority: High

Linear

Use Linear GraphQL API:

# Prepare GraphQL mutation
cat > /tmp/linear-mutation.json <<EOF
{
  "query": "mutation IssueCreate(\$teamId: String!, \$title: String!, \$description: String) { issueCreate(input: { teamId: \$teamId, title: \$title, description: \$description }) { success issue { id identifier url } } }",
  "variables": {
    "teamId": "${TEAM_ID}",
    "title": "${TITLE}",
    "description": "${DESCRIPTION}"
  }
}
EOF

# Create issue
curl -X POST https://api.linear.app/graphql \
  -H "Authorization: ${LINEAR_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @/tmp/linear-mutation.json

Return format:

✅ Issue created: ENG-42

View at: https://linear.app/team/issue/ENG-42

Title: Implement user auth
Status: Backlog
Priority: High

Local

Create markdown file in .aiwg/issues/:

# Determine next ticket number
mkdir -p .aiwg/issues
NEXT_NUM=$(ls .aiwg/issues/ISSUE-*.md 2>/dev/null | wc -l)
NEXT_NUM=$((NEXT_NUM + 1))
TICKET_ID=$(printf "ISSUE-%03d" $NEXT_NUM)
TICKET_FILE=".aiwg/issues/${TICKET_ID}.md"

# Create ticket file
cat > "${TICKET_FILE}" <<EOF
---
id: ${TICKET_ID}
title: ${TITLE}
status: open
created: $(date +%Y-%m-%d)
updated: $(date +%Y-%m-%d)
assignee: ${ASSIGNEE:-unassigned}
labels: ${LABELS:-none}
priority: ${PRIORITY:-medium}
---

# ${TICKET_ID}: ${TITLE}

**Status**: open
**Created**: $(date +%Y-%m-%d)
**Updated**: $(date +%Y-%m-%d)
**Assignee**: ${ASSIGNEE:-unassigned}
**Priority**: ${PRIORITY:-medium}

## Description

${DESCRIPTION}

## Acceptance Criteria

- [ ] (Add acceptance criteria here)

## Comments

### $(date +%Y-%m-%d\ %H:%M)

Issue created.
EOF

Return format:

✅ Issue created: ISSUE-001

File: .aiwg/issues/ISSUE-001.md

Title: Implement user auth
Status: open
Priority: medium

Step 7: Attach Regression Report (if applicable)

If regression check was run and regression detected:

# Save regression report alongside issue
if [ -f /tmp/regression-results.md ]; then
  cp /tmp/regression-results.md ".aiwg/issues/${TICKET_ID}-regression-report.md"

  # Add reference to issue body (provider-specific)
  # For local: already included in DESCRIPTION above
  # For Gitea/GitHub: attach as comment or file
fi

Step 8: Return Issue Reference

Output format (consistent across providers):

✅ Issue created: {ticket-id}

{view-url-or-file-path}

**Title**: {title}
**Status**: {status}
**Priority**: {priority}
**Labels**: {labels}
**Assignee**: {assignee}

{If regression detected:}
⚠️ **Regression Detected**: Critical regressions found and documented in issue

## Next Steps

- View ticket: {url-or-command}
- To update status, discover and load `issue-update`.
- To add a comment, discover and load `issue-update`.
- To list tickets, discover and load `issue-list`.

Examples

Example 1: Create Feature Request (Gitea)

Request:

Create a high-priority feature issue titled "Add dark mode" with body "Implement theme toggle for light/dark mode preferences" and labels "feature,ui".

Config (.aiwg/config.yaml):

ticketing:
  provider: gitea
  url: https://git.integrolabs.net
  owner: roctinam
  repo: ai-writing-guide

Output:

✅ Issue created: ISSUE-42

View at: https://git.integrolabs.net/roctinam/ai-writing-guide/issues/42

**Title**: Add dark mode
**Status**: open
**Priority**: high
**Labels**: feature, ui
**Assignee**: unassigned

## Next Steps

- View ticket: https://git.integrolabs.net/roctinam/ai-writing-guide/issues/42
- Update status by loading `issue-update` for ISSUE-42.
- Add comments through `issue-update`.
- List feature tickets by loading `issue-list`.

Example 2: Create Bug Report with Regression Check (Local)

Request:

Create a critical bug issue titled "Login broken after deployment" with body "Users unable to authenticate since v2.1.4 deployment" and run the regression check.

Output:

⏳ Running regression check...
✓ Regression analysis complete: 2 critical regressions detected

✅ Issue created: ISSUE-003

File: .aiwg/issues/ISSUE-003.md

**Title**: Login broken after deployment
**Status**: open
**Priority**: critical
**Labels**: bug, critical, regression-confirmed
**Assignee**: unassigned

⚠️ **Regression Detected**: 2 critical regressions found
   - Authentication validation failing at token refresh
   - Session state not persisting across requests

**Regression Report**: .aiwg/issues/ISSUE-003-regression-report.md

## Next Steps

- View ticket: cat .aiwg/issues/ISSUE-003.md
- View regression details: cat .aiwg/issues/ISSUE-003-regression-report.md
- Update status by loading `issue-update` for ISSUE-003.
- Run regression analysis through the regression-check capability.
- List regression issues by loading `issue-list`.

Example 3: Create Task with Assignee (GitHub)

Request:

Create an issue titled "Security audit" with body "Run penetration test on authentication endpoints", assign security-team, add labels "security,high-priority", and set milestone "Q1-2026".

Config (CLAUDE.md):

## Issueing Configuration

- **Provider**: github
- **Owner**: jmagly
- **Repo**: ai-writing-guide

Output:

✅ Issue created: #128

View at: https://github.com/jmagly/aiwg/issues/128

**Title**: Security audit
**Status**: open
**Priority**: medium (default)
**Labels**: security, high-priority
**Assignee**: @security-team
**Milestone**: Q1-2026

## Next Steps

- View ticket: gh issue view 128
- Update status by loading `issue-update` for #128.
- Add comments through `issue-update`.
- List security tickets by loading `issue-list`.

Example 4: Bug Report with Auto-Detected Regression Check

Request:

Create a payments bug issue titled "Payment calculation incorrect" with body "Discount not applying for orders > $1000".

Output:

ℹ️ Bug report detected, running automatic regression check...
⏳ Running regression check against baseline main...
✓ Regression confirmed: Introduced in commit abc1234

✅ Issue created: ISSUE-025

**Title**: Payment calculation incorrect
**Status**: open
**Priority**: critical (escalated due to regression)
**Labels**: bug, payments, regression-confirmed
**Assignee**: unassigned

⚠️ **Regression Confirmed**:
   - Introduced in: commit abc1234 (2026-01-15)
   - Root cause: Integer division in discount calculation
   - Blast radius: 12 unit tests, 3 integration tests affected

**Actions**:
   - Priority escalated to CRITICAL
   - Regression analyst assigned
   - Full report attached

**Regression Report**: .aiwg/issues/ISSUE-025-regression-report.md

## Next Steps

- View regression analysis: cat .aiwg/issues/ISSUE-025-regression-report.md
- Assign to developer: `/issue-update ISSUE-025 --assignee developer-name`
- Review introducing commit: git show abc1234
- Run targeted regression tests: npm test -- --grep "discount calculation"

Error Handling

No Configuration Found

⚠️ No ticketing configuration found.

Using default: local file-based tracking (.aiwg/issues/)

To configure a provider, create .aiwg/config.yaml:

ticketing:
  provider: gitea
  url: https://git.integrolabs.net
  owner: roctinam
  repo: ai-writing-guide

Or add to CLAUDE.md:

## Issueing Configuration

- **Provider**: gitea
- **URL**: https://git.integrolabs.net
- **Owner**: roctinam
- **Repo**: ai-writing-guide

Proceeding with local provider...

Invalid Configuration

❌ Invalid ticketing configuration:

Issues:
- provider 'gitehub' not recognized (must be: gitea, github, jira, linear, local)
- missing required field: url
- missing required field: repo

Fix configuration in .aiwg/config.yaml or CLAUDE.md

Cannot create ticket without valid configuration.

Authentication Failed

❌ Failed to authenticate with Gitea:

Issues:
- Token file not found: ~/.config/gitea/token
- Create token at https://git.integrolabs.net/user/settings/applications
- Save to ~/.config/gitea/token (mode 600)

Falling back to local file-based tracking.

To retry with Gitea:
1. Create token at https://git.integrolabs.net/user/settings/applications
2. Save to ~/.config/gitea/token
3. Run command again

Proceeding with local provider...

Regression Check Failed

⚠️ Regression check failed to complete:

Error: Baseline branch 'main' not found
Possible causes:
- Fresh repository without baseline
- Branch name incorrect

Creating issue without regression analysis.
Use `regression-check` manually after issue creation to verify.

Missing Title

❌ Issue title is required.

Usage: discover and load the skill, then compose the issue request:

aiwg discover "issue create"
aiwg show skill issue-create

Examples:
- Create an issue titled "Implement user auth"
- Create a bug issue titled "Fix bug" with body "Nav menu broken on mobile"
- Create a feature issue titled "Add feature" with labels "feature,ui"

Provider-Specific Errors

Gitea MCP Error:

❌ Failed to create Gitea issue:

Error: 401 Unauthorized
- Token may be invalid or expired
- Verify token at https://git.integrolabs.net/user/settings/applications
- Check token file: ~/.config/gitea/token

Falling back to local provider...

GitHub CLI Error:

❌ Failed to create GitHub issue:

Error: gh: command not found
- Install GitHub CLI: brew install gh (or platform equivalent)
- Authenticate: gh auth login

Or ask for a local issue explicitly after loading the `issue-create` skill.

Jira API Error:

❌ Failed to create Jira issue:

Error: 400 Bad Request - Invalid project key
- Verify project key: ${PROJECT_KEY}
- Check Jira URL: ${JIRA_URL}
- Verify API token: echo $JIRA_API_TOKEN

Falling back to local provider...

Local Filesystem Error:

❌ Failed to create local ticket file:

Error: Permission denied - .aiwg/issues/
- Check directory permissions: ls -la .aiwg/
- Ensure writable: chmod 755 .aiwg/issues/

Cannot create ticket.

Best Practices

1. Use project-level config (.aiwg/config.yaml) for team consistency
2. Provide detailed descriptions - Include context, acceptance criteria, and steps to reproduce (for bugs)
3. Use labels consistently - Establish team conventions (e.g., feature, bug, tech-debt)
4. Set priorities appropriately - Reserve critical for urgent production issues
5. Assign tickets early - Use --assignee to clarify ownership
6. Link to artifacts - Reference related files (@.aiwg/requirements/UC-001.md)
7. Use milestones - Group related work with --milestone
8. Test authentication - Verify provider connectivity before creating many tickets
9. Enable regression checks - Use --check-regression for bug reports to detect regressions early
10. Review regression reports - Always examine attached regression analysis before starting work

Integration with SDLC Workflows

Requirements Phase:

# Create tickets from use cases
Create an issue titled "Implement UC-001: User Login" referencing @.aiwg/requirements/use-cases/UC-001-login.md with labels "requirement,feature"

Architecture Phase:

# Create tickets from ADR decisions
Create an issue titled "Implement ADR-003: Use PostgreSQL" referencing @.aiwg/architecture/adrs/003-use-postgresql.md with labels "architecture,database"

Testing Phase:

# Create tickets from test failures with regression check
Create a high-priority bug issue titled "Fix failing test: auth.test.ts" and run the regression check

Security Review:

# Create tickets from security audit findings
Create a critical security issue titled "Fix SQL injection vulnerability" with labels "security,vulnerability"

Retrospectives:

# Create tickets from retro action items
Create an issue titled "Improve CI/CD pipeline" with labels "process-improvement,devops"

Regression Detection:

# Create issue from detected regression
Create a regression issue titled "Performance regression in API" and include p99 latency evidence

References

• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/config/issueing-config.md - Configuration schema
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/commands/issue-update.md - Update ticket command
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/commands/issue-list.md - List tickets command
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/commands/regression-check.md - Regression detection command
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/regression-analyst.md - Regression analysis agent
• @CLAUDE.md - User ticketing configuration