ticket-creator

チケット作成

ユーザーの意図に基づき、コンテキストを自動検出し、適切なデフォルトを設定して、構成の整ったプロジェクトチケットを作成します。

使用する場面

• ユーザーが「チケットを作成して」「チケットを書いて」「チケットを作って」と言った場合
• ユーザーが機能、バグ、タスクについて説明し、それを正式な形式にまとめたい場合
• ユーザーが「これをチケットにして」などと言った場合
• ユーザーが作業内容を構造化された形式で記録したい場合

ワークフロー

1. 意図を把握する

まず、作成するチケットの内容を把握します。ユーザーは次のように依頼する場合があります。

• 詳細なコンテキストを含む単一のチケット
• 1 回の依頼で複数のチケット（例：「X、Y、Z のチケットを作成して」）
• 形式化する機能やバグの一覧

ユーザーのメッセージから分かる情報を抽出します。依頼が曖昧な場合や確認が必要な場合は、次の点を尋ねます。

• チケットの内容は何ですか？（簡単な説明）
• どのような種類の作業ですか？（エピック、タスク、機能強化）
• 優先度はどのくらいですか？（高、中、低）
• チケット間、または他の作業との依存関係はありますか？

会話形式を保ち、ユーザーにフォームへの記入を求めないでください。

2. チケットごとにサブエージェントを起動する

作成するチケットごとに、調査と生成を並行して行うサブエージェントを起動します。

Create a project ticket with the following details:

Ticket Intent: <what the user wants - extracted from their request>
Type: <Epic | Task | Enhancement - inferred or specified>
Priority: <High | Medium | Low - inferred or specified>
Dependencies: <any mentioned dependencies>

Follow this workflow:

1. **Gather Project Context** - understand the codebase:
   - Check for existing tickets (`.tickets/`, `docs/tickets/`, `tickets/`, `.md` files with ticket patterns)
   - Check for `openspec/` — if present, read `openspec/specs/INDEX.md` (or the relevant `spec.md` files directly) to understand the current, canonical state of the capability this ticket touches, and scan `openspec/changes/` for in-flight changes that might already cover or overlap with this intent. Specs reflect current standing more reliably than reading code alone, since code may be mid-change.
   - Read `README.md`, `CLAUDE.md`, `AGENTS.md` for project context
   - Check tech stack indicators (`package.json`, `Cargo.toml`, `go.mod`, etc.)
   - Sample relevant source files if the ticket mentions specific components

   Depth of research should match ticket complexity (simple bug fix needs less than an epic).

2. **Detect Project Metadata:**
   - **Project Prefix**: Check existing tickets for patterns like `[FOO-123]` or `FOO-123:` in filenames/content, try git remote URL (extract repo name, uppercase it), check `package.json` name field, or use `[PROJECT-NNN]` as placeholder
   - **Ticket Number**: If existing tickets found, extract numbers and suggest next sequential number, otherwise use `NNN` as placeholder

3. **Fill the Template** using the structure provided below.

4. **Output**: Return the completed ticket in a markdown code block, followed by a brief note about what was detected (project prefix, ticket number, context sources).

<paste the template structure from section 4 below>

重要：すべてのサブエージェントを、同じターン内で並列の Agent 呼び出しを使って起動します。これにより、調査とチケット生成を並行して進められます。

サブエージェント用プロンプトのテンプレート：

Create a project ticket with the following intent:

<extracted description of what the user wants for this specific ticket>

Ticket metadata:
- Type: <Epic | Task | Enhancement - inferred or "Medium" if unclear>
- Priority: <High | Medium | Low - inferred or "Medium" if unclear>
- Dependencies: <any mentioned dependencies, or "None">

Follow this workflow:

1. **Gather Project Context** - Research the codebase to write meaningful acceptance criteria:

   **Check for `openspec/` first, regardless of other context sources:**
   - If `openspec/specs/` exists, read `openspec/specs/INDEX.md` (or the relevant `spec.md` files directly if there's no index) to ground the ticket in the current, canonical capability state rather than assumptions from skimming code.
   - Check `openspec/changes/` for in-flight changes that might already cover this ticket's intent. If one does, note it under `Dependencies` instead of writing a duplicate or conflicting ticket.

   **If opsx:explore skill is available:**
   - Invoke `/opsx:explore` with a focused prompt about what this ticket touches
   - Use the exploration results to inform the ticket description and acceptance criteria

   **Otherwise, use manual research:**
   - Check for existing tickets in: .tickets/, docs/tickets/, tickets/, or .md files with ticket patterns
   - Read README.md, CLAUDE.md, AGENTS.md for project context
   - Check tech stack indicators (package.json, Cargo.toml, go.mod, etc.)
   - Sample relevant source files if the ticket mentions specific components
   - Use Glob/Grep to find relevant code patterns

   Match research depth to ticket complexity (simple bug fix needs less than an epic).

2. **Detect Project Metadata:**
   - **Project Prefix**: Look for patterns like [FOO-123] or FOO-123: in existing tickets/filenames, try git remote URL (extract repo name, uppercase), check package.json name field, or use [PROJECT-NNN] as placeholder
   - **Ticket Number**: If existing tickets found, extract highest number and suggest next sequential, otherwise use NNN as placeholder

3. **Fill the Template** - Use this structure:

<paste the template from section 4>

4. **Output** - Return:
   a) The completed ticket in a markdown code block
   b) A brief note about what was detected (project prefix source, ticket number rationale, where context came from)

3. 結果をまとめて表示する

すべてのサブエージェントが完了したら、次の手順を実行します。

1. 各サブエージェントの応答から生成されたチケットを収集します
2. 区切りを明確にして、すべてのチケットを順番にユーザーに提示します
3. 次の内容を要約します。
   • 作成したチケットの数
   • 検出したプロジェクトのプレフィックス／番号付け（またはプレースホルダーを使用したかどうか）
   • チケット全体で気づいたパターン（例：すべて優先度が高い、チケット間に依存関係がある）

4. テンプレートに記入する（サブエージェント向け）

次の構成をそのまま使用します。

### [PROJECT-NNN]: [Title]

Status: [Complete | Not Started | Closed | In Progress]
Type: [Epic | Task | Enhancement]
Priority: [High | Medium | Low]
Dependencies: [None | TICKET-ID (description)]

Description:

[1-3 paragraph context explaining the problem/goal]

Acceptance Criteria:

- [Specific, testable criteria]
- [Implementation requirements]
- [Validation/testing requirements]
- [Documentation requirements]
- [Integration/deployment requirements]
- [Edge cases covered]
- [Performance requirements if applicable]

[Optional: Additional non-binding context — e.g., known constraints, external interfaces/contracts, or relevant history]

**[Optional subsection heading, e.g. "Context for Implementer"]:**
[Bulleted details, tables, or interface/contract definitions — framed as background, not instructions]

記入ガイドライン：

• タイトル：明確で、実行可能な内容を示す 5～10 語のタイトル
• ステータス：ユーザーから指定がない限り、「未着手」をデフォルトにします
• 種類：意図から推測します（新機能＝機能強化／エピック、修正＝タスク、大規模な取り組み＝エピック）
• 優先度：不明な場合は尋ね、デフォルトは「中」にします
• 依存関係：依存関係について言及がなければ「なし」
• 説明：次の内容を含む 1～3 段落
  • 解決する問題、または達成する目標
  • 重要な理由（ユーザーへの影響、技術的負債など）
  • コードベースに関連するコンテキスト
• 受け入れ条件：次の内容を網羅した、具体的でテスト可能な箇条書き
  • 実装が必要な内容
  • 正しく動作することの検証方法
  • 必要なドキュメント
  • 統合／デプロイに関する考慮事項
  • 対応が必要なエッジケース
  • パフォーマンス要件（該当する場合）
• 任意のセクション：役立つ場合はサブセクションを追加します（例：「セキュリティ上の考慮事項」「実装担当者向けのコンテキスト」）。ただし、実装方法を指示するのではなく、制約やコンテキストを説明する内容にしてください。ファイル、関数、手順を指定する「技術的アプローチ」セクションは避けてください。下記の「実装方法ではなく、成果を記述する」を参照してください。

5. チケットを出力する

記入済みのテンプレートを、Markdown のコードブロックに入れてチャットに直接出力します。ユーザーはコピーして、チケットを管理する場所に保存できます。

出力後、次の内容を簡潔に伝えます。

• 検出したプロジェクトのプレフィックス／番号（またはプレースホルダーを使用したこと）
• コンテキストの収集元（opsx:explore、既存のチケット、ドキュメントなどを使用した場合）

品質ガイドライン

対応可能なチケットにする：受け入れ基準は、ほかの人が質問せずにチケットを実装できるほど明確にします。

詳細さと簡潔さのバランスを取る：エピックには単純なタスクより多くの背景情報が必要です。些細な変更を過度に細かく指定しないでください。

検証方法を具体的にする：「テストに合格する」では不十分です。「単体テストで X、Y、Z のエッジケースを網羅し、統合テストでエンドツーエンドのフローを検証する」なら十分です。

理由を記録する：説明には、何をするかだけでなく、その動機も記載してください。将来読む人が、この作業がなぜ重要だったのかを理解できるようにします。

ドメインの用語を使う：コードベースの用語に合わせます（たとえば、コードで「checks」ではなく「rules」と呼んでいるなら、「rules」を使います）。

実装方法ではなく、成果を記述する：チケットには、変更方法ではなく、何を変更する必要があるかを記載します。特定のファイル、関数、行番号、手順を追った技術的なアプローチを指定するのは避けてください。チケットの作成時と着手時の間にコードは変わることがあり、「方法」の詳細はすぐに古くなりますが、「何を」（動作、契約、基準）は有効なままです。例外は、既知の外部制約（例：「既存の AuthProvider インターフェースを使用する必要がある」）や、提案するアプローチではなく要件そのものに含まれるインターフェース／スキーマの契約です。調査で実装に関係する情報が見つかった場合は、受け入れ基準や説明で指示するのではなく、「実装者向けの背景情報」などの項目に、拘束力のない参考情報として別途記載してください。

例

例 1：単一の機能リクエスト

入力：「scan コマンドに --json フラグを追加して、ユーザーが出力を jq にパイプできるようにしたい」

処理：

1. 意図を解析：単一チケット、機能強化、中優先度
2. チケットの詳細を渡してサブエージェントを 1 つ起動
3. サブエージェントがコードベースを調査し、プロジェクトのメタデータを検出して、テンプレートに記入
4. 結果をユーザーに表示

ユーザーへの出力：

### [AUDITKIT-015]: Add JSON output format to scan command

Status: Not Started
Type: Enhancement
Priority: Medium
Dependencies: None

Description:

Users frequently need to post-process scan results programmatically. Currently, the scan command outputs human-readable text only, requiring users to write fragile parsers. Adding a `--json` flag enables structured output that can be piped to tools like `jq`, integrated into CI systems, or consumed by other automation.

This aligns with the CLI's goal of being automation-friendly while maintaining excellent human UX by default.

Acceptance Criteria:

- `auditkit scan --json <path>` outputs valid JSON to stdout
- JSON structure includes: findings array (each with rule ID, severity, location, message), summary stats, scan metadata (timestamp, version, config used)
- Human-readable output remains default (no breaking changes)
- JSON schema is documented in README.md
- Unit tests validate JSON structure matches schema
- Integration test pipes output to `jq` and extracts fields successfully
- Error messages are written to stderr (not mixed with JSON stdout)
- Exit codes remain consistent (0 = clean, 1 = findings, 2 = error)

**JSON Schema:**
```json
{
  "version": "1.0.0",
  "timestamp": "ISO-8601",
  "findings": [
    {
      "ruleId": "string",
      "severity": "critical|high|medium|low",
      "location": {"file": "string", "line": number, "column": number},
      "message": "string",
      "snippet": "string (optional)"
    }
  ],
  "summary": {"critical": 0, "high": 1, "medium": 3, "low": 5}
}

✅ **1 ticket created**

Context detected: AUDITKIT prefix from git repo, ticket 015 from existing `.tickets/` directory, CLI architecture from `src/cli/commands/scan.ts`.

---

**Example 2: Multiple Tickets**

Input: "Create tickets for: (1) fix the crash when scanning empty directories, (2) add rate limiting to the API client, (3) improve error messages in the parser"

Process:
1. Parse intent: 3 tickets needed
2. Extract details for each:
   - Ticket 1: Bug fix, High priority
   - Ticket 2: Enhancement, Medium priority
   - Ticket 3: Enhancement, Low priority
3. Spawn 3 sub-agents in parallel (one Agent call with 3 sub-agents)
4. Aggregate results and display to user

Output to user:
```markdown
### [PROJECT-016]: Fix crash when scanning empty directories

Status: Not Started
Type: Task
Priority: High
Dependencies: None

Description:

The scanner currently crashes with a null pointer exception when run on empty directories. This happens because the file discovery module assumes at least one file exists and doesn't handle the empty array case.

Users encounter this when running the scanner on newly initialized projects or filtered directories, leading to a poor experience and confusion about whether the tool is broken.

Acceptance Criteria:

- Scanner gracefully handles empty directories without crashing
- Output message clearly indicates "No files found in <path>" when appropriate
- Exit code is 0 (success) for empty directories (not an error condition)
- Unit test verifies behavior with empty directory
- Integration test runs scanner on `fixtures/empty-dir/` and validates output
- Edge case covered: directory exists but all files are ignored by config

---

### [PROJECT-017]: Add rate limiting to API client

Status: Not Started
Type: Enhancement
Priority: Medium
Dependencies: None

Description:

The API client currently makes unlimited requests, which can lead to 429 errors from external services and potentially cause service disruption. Implementing rate limiting ensures respectful API usage and prevents hitting service quotas unexpectedly.

This is particularly important for the external rule repository sync feature, which may need to fetch many rule definitions in quick succession.

Acceptance Criteria:

- API client respects configurable rate limits (requests per second/minute)
- Configuration allows per-endpoint rate limits if needed
- Client automatically retries with exponential backoff on 429 responses
- Rate limit state persists across client instances (shared token bucket)
- Unit tests verify rate limiting logic
- Integration test confirms requests are throttled appropriately
- Documentation updated with configuration examples
- Default rate limits are conservative (avoid hitting common API limits)

---

### [PROJECT-018]: Improve error messages in parser

Status: Not Started
Type: Enhancement
Priority: Low
Dependencies: None

Description:

Current parser error messages are cryptic and unhelpful for users debugging rule syntax issues. Messages like "parse error at line 42" don't indicate what went wrong or how to fix it. Improving error messages reduces support burden and improves developer experience.

Acceptance Criteria:

- Error messages include context: what was expected vs. what was found
- Line/column numbers are accurate and included in all parse errors
- Common mistakes have helpful suggestions (e.g., "Did you mean X?")
- Multi-line context shown around error location (±2 lines)
- Error messages tested for clarity with non-expert users
- Documentation includes common parse errors and solutions
- Parser maintains same performance characteristics

---

✅ 3 件のチケットを作成しました

概要：

• プロジェクトの接頭辞：PROJECT（プレースホルダーから取得。既存のチケットは見つかりませんでした）
• チケット番号：016-018（連番で開始）
• 優先度：高 1 件、中 2 件、低 1 件
• すべてのチケットは独立しています（相互に依存関係はありません）

---

エッジケース

• Git リポジトリがない：サブエージェントはリモート URL からプロジェクトの接頭辞を検出できないため、プレースホルダーを使用します
• 意図が曖昧：サブエージェントの起動前に（起動後ではなく）明確化の質問をしてください
• ユーザーから部分的な情報が提供された：サブエージェントを起動する前に、可能な範囲で情報を補い、デフォルト値を渡してください
• 非常に大規模なエピック：起動前に、チケットを複数に分割するようユーザーに提案することを検討してください
• サブエージェントの失敗：サブエージェントが失敗またはタイムアウトした場合、エラーをユーザーに報告し、該当するチケットのみ再試行することを提案してください
• 連番の採番：複数のチケットを並行して作成すると、サブエージェントが同じチケット番号を提案する場合があります。結果を集約した後、必要に応じてチケット番号を連番に振り直し、その旨をユーザーに伝えてください。
• Claude.ai またはサブエージェントを利用できない環境：逐次処理に切り替え、調査／検出／生成のワークフローをインラインで実行しながら、チケットを 1 件ずつ処理してください

出力形式

ユーザーが簡単にコピーできるよう、チケットは必ず Markdown のコードブロックで出力してください。

```markdown
### [PROJECT-001]: Ticket Title
...
```

続けて、検出した内容や推測した内容について簡潔に説明を加えてください。