ticket-creator

票据创建器

根据用户意图创建结构清晰的项目票据，并自动检测上下文、智能设置默认值。

适用场景

• 用户说“创建一个票据”“写一个票据”“建一个票据”
• 用户描述了功能、Bug 或任务，并希望将其整理成正式票据
• 用户说“把这个整理成票据”或类似的话
• 用户希望以结构化格式记录工作

工作流

1. 理解意图

首先了解需要创建哪些票据。用户可能会提出以下要求：

• 创建一张包含完整上下文的票据
• 在一次请求中创建多张票据（例如“为 X、Y 和 Z 创建票据”）
• 列出需要整理成正式票据的功能或 Bug

从用户的消息中提取可用信息。如果请求含糊不清或需要澄清，请询问：

• 票据的主题是什么？（简要描述）
• 这是什么类型的工作？（Epic、Task、Enhancement）
• 优先级是什么？（High、Medium、Low）
• 票据之间或与其他工作之间是否存在依赖关系？

保持对话自然，不要让用户填写表格。

2. 为每张票据启动子 Agent

为需要创建的每张票据启动子 Agent，让它们并行开展研究和生成：

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 调用启动所有子 Agent。这样它们就能并行研究并生成票据。

子 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. 汇总并展示结果

所有子 Agent 完成后：

1. 收集各子 Agent 回复中生成的票据
2. 按顺序向用户展示所有票据，并使用清晰的分隔符
3. 提供摘要：
   • 创建了多少张票据
   • 检测到的项目前缀和编号（或是否使用了占位符）
   • 票据中发现的任何模式（例如，全部标记为 High 优先级，或票据之间存在依赖关系）

4. 填写模板（供子 Agent 使用）

使用以下准确结构：

### [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 个词
• 状态：除非用户另有指定，默认为“Not Started”
• 类型：根据意图推断（新功能 = Enhancement/Epic，修复 = Task，大型计划 = Epic）
• 优先级：不明确时询问，默认设为 Medium
• 依赖关系：如果未提及依赖关系，填写“None”
• 描述：用 1-3 段说明：
  • 要解决的问题或要实现的目标
  • 重要性（对用户的影响、技术债务等）
  • 代码库中的相关上下文
• 验收标准：使用具体、可测试的条目，涵盖：
  • 需要实现的内容
  • 如何验证其正常工作
  • 需要哪些文档
  • 集成和部署方面的注意事项
  • 需要处理的边界情况
  • 性能要求（如适用）
• 可选章节：如有帮助，可添加小节（例如“安全注意事项”“实施者须知”），但内容应描述约束或上下文，而非规定实施方式。避免添加规定文件、函数或逐步操作方式的“技术方案”章节——请参阅下文“描述结果，而非实现方式”。

5. 输出票据

将填写好的模板直接放入 Markdown 代码块中发送到聊天。用户可以复制它，并保存到管理票据的位置。

输出后，简要说明：

• 检测到的项目前缀和编号（或说明使用了占位符）
• 获取上下文的来源（如果使用了 opsx:explore、现有票据、文档等）

质量指南

让工单可执行：验收标准应足够明确，让其他人无需提问就能实现工单。

兼顾详细程度与简洁性：史诗级任务需要比简单任务提供更多背景信息。不要对琐碎的改动规定过多细节。

明确说明如何验证：“测试通过”不够具体。“单元测试涵盖 X、Y、Z 边界情况；集成测试验证端到端流程”则很明确。

说明原因：描述应解释动机，而不只是说明要做什么。未来的读者需要理解这项工作为何重要。

使用领域术语：采用代码库中的术语（例如，如果代码中称其为“规则”而非“检查”，就使用“规则”）。

描述结果，而非实现方式：工单应说明必须改变什么，而不是如何改变。避免提及特定文件、函数、行号或分步技术方案——从编写工单到开始处理期间，代码可能会发生变化，“如何实现”的细节很快就会过时，而“要实现什么”（行为、契约、标准）则能保持有效。例外情况：已知的外部约束（例如“必须使用现有的 AuthProvider 接口”），或本身就是需求一部分、而非建议方案的接口／架构契约。如果研究发现与实现相关的信息，应将其作为明确标注为非强制要求的背景信息单独提供（例如放在“实施者参考背景”下），不要将其作为指令写入验收标准或描述中。

示例

示例 1：单项功能请求

输入：“我们需要为 scan 命令添加一个 --json 标志，让用户可以将输出传递给 jq”

处理流程：

1. 解析意图：单个工单，增强功能，中优先级
2. 启动一个子 Agent，提供工单详情
3. 子 Agent 研究代码库、检测项目元数据并填写模板
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 仓库：子 Agent 无法从远程 URL 检测项目前缀 → 将使用占位符
• 意图不明确：在启动子 Agent 之前（而非之后）提出澄清问题
• 用户只提供了部分信息：在启动子 Agent 之前尽可能补全信息，并将默认值传递给它们
• 史诗级任务规模很大：可考虑建议用户在启动子 Agent 之前将其拆分为多个工单
• 子 Agent 失败：如果子 Agent 失败或超时，应向用户报告错误，并提出重试该特定工单
• 顺序编号：并行创建多个工单时，子 Agent 可能会建议相同的工单编号。汇总结果后，如有需要，应重新按顺序为工单编号，并告知用户。
• Claude.ai 或不支持子 Agent 的环境：改为串行处理——按照研究／检测／生成工作流，逐个处理工单

输出格式

始终将工单放在 Markdown 代码块中输出，方便用户复制：

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

然后简要说明检测到或推断出的信息。