---
namespace: aiwg
name: issue-create
platforms: [all]
description: Create a new ticket/issue with configurable backend (Gitea, GitHub, Jira, Linear, or local files)
commandHint:
argumentHint:
[description] [--provider NAME --labels "label1,label2" --assignee USER --check-regression]
allowedTools: Read, Write, Glob, Bash, mcp__gitea__create_issue
model: sonnet
category: project-management
---
> **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:
>
> ```bash
> aiwg discover ""
> aiwg show skill
> ```
>
> Only kernel-listed skills (`aiwg-doctor`, `aiwg-refresh`, `aiwg-status`, `aiwg-help`, `use`, `steward`) are directly invokable as slash commands. See [skill-discovery rule](../../../addons/aiwg-utils/rules/skill-discovery.md).
# Issue Create
## 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. **Load configuration** from `.aiwg/config.yaml` or project `CLAUDE.md`
2. **Validate configuration** and authenticate with provider
3. **Check for regressions** (if bug report with `--check-regression`)
4. **Create ticket** using appropriate backend (MCP, CLI, or local file)
5. **Return ticket reference** (issue number, URL, or file path)
## Parameters
- **``** (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 command invocation:
```bash
# Basic usage
/issue-create "Implement user auth"
# With description
/issue-create "Fix navigation bug" "Nav menu not showing on mobile devices"
# With labels
/issue-create "Add dark mode" "Implement theme toggle" --labels "feature,ui"
# With assignee
/issue-create "Security audit" "Run penetration test" --assignee "security-team" --priority high
# Bug report with regression check
/issue-create "Login broken after deployment" "Users can't login" --labels "bug,critical" --check-regression
# Override provider
/issue-create "Local task" "Quick reminder" --provider local
```
**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. **`.aiwg/aiwg.config` `remotes.issue_tracker`** (#994) — derive provider from the 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 `.aiwg/aiwg.config`** (the preferred path):
```ts
import { readAiwgConfig, resolveRemotes, resolveRemoteProvider } from 'aiwg/config';
const cfg = await readAiwgConfig(projectDir);
const resolved = resolveRemotes(cfg?.remotes);
// resolved.issue_tracker is a git remote name (defaults to "origin")
// Resolve the URL via `git remote get-url `
const url = exec(`git remote get-url ${resolved.issue_tracker}`).trim();
const provider = resolveRemoteProvider(url); // 'gitea' | 'github' | 'gitlab' | 'unknown'
```
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` providers list must explicitly include `gitea` so we can fall through to that.
**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**:
```bash
# 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**:
| Regression Status | Priority | Labels | Action |
|-------------------|----------|--------|--------|
| REGRESSION DETECTED | Critical | bug, regression-confirmed | Escalate, include analysis |
| NO REGRESSION | Original | bug, no-regression | Standard bug workflow |
| CHECK FAILED | Original | bug, regression-check-failed | Create issue, note failure |
### 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: Create Issue (Provider-Specific)
#### Gitea
Use MCP tool `mcp__gitea__create_issue`:
```bash
# 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:
```bash
# 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:
```bash
# Prepare JSON payload
cat > /tmp/jira-issue.json < /tmp/linear-mutation.json </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}" < $1000" --labels "bug,payments"
```
**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: /issue-create [description] [options]
Examples:
- /issue-create "Implement user auth"
- /issue-create "Fix bug" "Nav menu broken on mobile"
- /issue-create "Add feature" "Dark mode toggle" --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 use local provider: /issue-create "title" --provider local
```
**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**:
```bash
# Create tickets from use cases
/issue-create "Implement UC-001: User Login" "See @.aiwg/requirements/use-cases/UC-001-login.md" --labels "requirement,feature"
```
**Architecture Phase**:
```bash
# Create tickets from ADR decisions
/issue-create "Implement ADR-003: Use PostgreSQL" "Migrate from SQLite to PostgreSQL per @.aiwg/architecture/adrs/003-use-postgresql.md" --labels "architecture,database"
```
**Testing Phase**:
```bash
# Create tickets from test failures with regression check
/issue-create "Fix failing test: auth.test.ts" "Test failure in authentication module" --priority high --labels "bug,testing" --check-regression
```
**Security Review**:
```bash
# Create tickets from security audit findings
/issue-create "Fix SQL injection vulnerability" "Parameterize queries in auth module" --priority critical --labels "security,vulnerability"
```
**Retrospectives**:
```bash
# Create tickets from retro action items
/issue-create "Improve CI/CD pipeline" "Reduce build time from 10min to 5min" --labels "process-improvement,devops"
```
**Regression Detection**:
```bash
# Create issue from detected regression
/issue-create "Performance regression in API" "p99 latency increased from 200ms to 450ms" --labels "bug,performance,regression" --check-regression
```
## 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