diff --git a/.chezmoiignore b/.chezmoiignore index 5bf2ba1..0945142 100644 --- a/.chezmoiignore +++ b/.chezmoiignore @@ -39,6 +39,7 @@ homebrew/ .config/git/freee homebrew/Brewfile.work .claude/rules/pr-size.md +.claude/skills/acli/ {{ end }} # Local files (never managed by chezmoi) diff --git a/dot_claude/skills/acli/SKILL.md b/dot_claude/skills/acli/SKILL.md new file mode 100644 index 0000000..89d8bd6 --- /dev/null +++ b/dot_claude/skills/acli/SKILL.md @@ -0,0 +1,269 @@ +--- +name: acli +description: Atlassian CLI (acli) for Jira operations. Use when (1) creating Jira tickets/issues, (2) updating or editing existing tickets, (3) searching Jira issues, (4) viewing ticket details, (5) managing work items programmatically. Provides correct syntax and ADF format for descriptions. +--- + +# Atlassian CLI (acli) + +CLI tool for Jira Cloud operations. Use `acli jira workitem` commands for issue management. + +## Initial Setup + +Before using acli, always confirm with user: + +1. **Project Key**: Required for all operations +2. **Parent Epic/Ticket**: Required when creating sub-tasks or linking issues +3. **Issue Type**: Task, Bug, Story, etc. + +``` +AskUserQuestion examples: +- "What is the Jira project key?" (e.g., PROJ, TEAM) +- "What is the parent Epic key?" (e.g., PROJ-100) +- "What issue type should I use?" (Task, Bug, Story, Sub-task) +- "Are there any reference tickets I should check for format/style?" +``` + +**Important**: Always verify the parent ticket exists before creating sub-tasks: + +```bash +acli jira workitem view --key PROJ-100 +``` + +## Quick Reference + +| Operation | Command | +|-----------|---------| +| View | `acli jira workitem view --key KEY-123` | +| Create | `acli jira workitem create --from-json file.json` | +| Edit | `acli jira workitem edit --from-json file.json --yes` | +| Search | `acli jira workitem search --jql "project = PROJ"` | +| Delete | `acli jira workitem delete --key KEY-123` (requires confirmation) | + +## Ticket Templates + +When creating tickets, ask user for reference tickets to match existing style: + +```bash +# Check existing ticket format +acli jira workitem view --key PROJ-50 +``` + +### Standard Ticket Structure + +Recommended sections for task tickets: + +1. **Summary** (概要): Brief description of the task +2. **Background/Investigation** (調査結果): Context, data, evidence +3. **Acceptance Criteria** (受け入れ条件): Checklist of completion criteria +4. **References** (参考資料): Links to documentation, Datadog, PRs, etc. + +## Creating Tickets + +Use `--from-json` with ADF (Atlassian Document Format) for proper formatting: + +```bash +acli jira workitem create --from-json /tmp/ticket.json +``` + +### JSON Structure + +```json +{ + "projectKey": "PROJ", + "type": "Task", + "parentIssueId": "PROJ-100", + "summary": "Ticket title", + "description": { + "type": "doc", + "version": 1, + "content": [...] + } +} +``` + +### Issue Types + +| Type | Use Case | +|------|----------| +| Epic | Large feature/initiative grouping multiple tasks | +| Story | User-facing feature | +| Task | Technical work item | +| Bug | Defect fix | +| Sub-task | Child of another issue | + +### ADF Content Types + +See [references/adf-format.md](references/adf-format.md) for complete ADF reference. + +**Common patterns:** + +```json +// Heading +{"type": "heading", "attrs": {"level": 2}, "content": [{"type": "text", "text": "Title"}]} + +// Paragraph +{"type": "paragraph", "content": [{"type": "text", "text": "Content"}]} + +// Bullet list +{"type": "bulletList", "content": [ + {"type": "listItem", "content": [ + {"type": "paragraph", "content": [{"type": "text", "text": "Item"}]} + ]} +]} + +// Task list (checkboxes) - for acceptance criteria +{"type": "taskList", "attrs": {"localId": "list-1"}, "content": [ + {"type": "taskItem", "attrs": {"localId": "item-1", "state": "TODO"}, + "content": [{"type": "text", "text": "Task item"}]} +]} + +// Code (inline) +{"type": "text", "text": "code here", "marks": [{"type": "code"}]} + +// Link - for references +{"type": "text", "text": "Link text", "marks": [{"type": "link", "attrs": {"href": "https://..."}}]} +``` + +### Including References + +Always include relevant links in tickets: + +```json +{ + "type": "bulletList", + "content": [ + { + "type": "listItem", + "content": [ + { + "type": "paragraph", + "content": [ + { "type": "text", "text": "Datadog URL", "marks": [ + { "type": "link", "attrs": { "href": "https://app.datadoghq.com/logs?..." } } + ]} + ] + } + ] + }, + { + "type": "listItem", + "content": [ + { + "type": "paragraph", + "content": [ + { "type": "text", "text": "Related PR", "marks": [ + { "type": "link", "attrs": { "href": "https://github.com/..." } } + ]} + ] + } + ] + } + ] +} +``` + +## Editing Tickets + +Use `--from-json` with `issues` array to specify targets: + +```bash +acli jira workitem edit --from-json /tmp/edit.json --yes +``` + +### Edit JSON Structure + +```json +{ + "issues": ["PROJ-123", "PROJ-124"], + "description": { + "type": "doc", + "version": 1, + "content": [...] + } +} +``` + +**Important flags:** +- `--yes`: Skip confirmation prompt (required for automation) +- `--from-json`: Use JSON file with `issues` array + +**Common mistake:** `--key` and `--from-json` cannot be used together. Use `issues` array inside JSON instead. + +## Linking Issues + +### Issue Links (blocks, relates to, etc.) + +```bash +acli jira workitem link --help +``` + +### Parent-Child Relationships + +Set `parentIssueId` in create JSON for Epic-Task relationships. + +## Bulk Operations + +### Create Multiple Tickets + +Loop through data and create JSON for each: + +```bash +for item in "Item1" "Item2" "Item3"; do + # Generate JSON with proper ADF + cat > /tmp/ticket.json << EOF + {...} +EOF + acli jira workitem create --from-json /tmp/ticket.json +done +``` + +### Edit Multiple Tickets + +Include all keys in `issues` array: + +```json +{ + "issues": ["PROJ-1", "PROJ-2", "PROJ-3"], + "summary": "Updated title" +} +``` + +## Common Workflows + +### Create Task Under Epic + +1. Ask user for project key and parent Epic +2. Verify parent Epic exists: `acli jira workitem view --key EPIC-KEY` +3. Ask if there are reference tickets for format +4. Generate JSON with `parentIssueId` +5. Create with `--from-json` + +### Update Ticket Description + +1. View current ticket: `acli jira workitem view --key PROJ-123` +2. Generate edit JSON with `issues` array +3. Include new ADF description +4. Run with `--yes` flag + +### Create Tickets with References + +1. Gather all reference URLs (Datadog, GitHub, docs) +2. Include as links in description using ADF link marks +3. Verify links are accessible + +## Troubleshooting + +| Error | Cause | Solution | +|-------|-------|----------| +| `INVALID_INPUT` | Bad ADF format | Validate JSON structure | +| `flags cannot be used together` | `--key` with `--from-json` | Use `issues` array in JSON | +| Markdown not rendering | Plain text description | Use ADF format | +| Confirmation prompt blocking | Missing `--yes` | Add `--yes` flag | +| `Issue does not exist` | Wrong key or no permission | Verify key with `view` first | + +## References + +- [ADF Format Reference](references/adf-format.md) - Complete ADF syntax guide +- Run `acli jira workitem --help` for all available commands +- Run `acli jira workitem create --generate-json` for JSON template +- Run `acli jira workitem edit --generate-json` for edit JSON template diff --git a/dot_claude/skills/acli/assets/.gitkeep b/dot_claude/skills/acli/assets/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/dot_claude/skills/acli/assets/example_asset.txt b/dot_claude/skills/acli/assets/example_asset.txt new file mode 100644 index 0000000..d0ac204 --- /dev/null +++ b/dot_claude/skills/acli/assets/example_asset.txt @@ -0,0 +1,24 @@ +# Example Asset File + +This placeholder represents where asset files would be stored. +Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed. + +Asset files are NOT intended to be loaded into context, but rather used within +the output Claude produces. + +Example asset files from other skills: +- Brand guidelines: logo.png, slides_template.pptx +- Frontend builder: hello-world/ directory with HTML/React boilerplate +- Typography: custom-font.ttf, font-family.woff2 +- Data: sample_data.csv, test_dataset.json + +## Common Asset Types + +- Templates: .pptx, .docx, boilerplate directories +- Images: .png, .jpg, .svg, .gif +- Fonts: .ttf, .otf, .woff, .woff2 +- Boilerplate code: Project directories, starter files +- Icons: .ico, .svg +- Data files: .csv, .json, .xml, .yaml + +Note: This is a text placeholder. Actual assets can be any file type. diff --git a/dot_claude/skills/acli/references/adf-format.md b/dot_claude/skills/acli/references/adf-format.md new file mode 100644 index 0000000..8cd347f --- /dev/null +++ b/dot_claude/skills/acli/references/adf-format.md @@ -0,0 +1,306 @@ +# ADF (Atlassian Document Format) Reference + +ADF is JSON-based format for rich text in Jira/Confluence. + +## Document Structure + +```json +{ + "type": "doc", + "version": 1, + "content": [ + // Array of block-level nodes + ] +} +``` + +## Block-Level Nodes + +### Heading + +```json +{ + "type": "heading", + "attrs": { "level": 1 }, // 1-6 + "content": [ + { "type": "text", "text": "Heading Text" } + ] +} +``` + +### Paragraph + +```json +{ + "type": "paragraph", + "content": [ + { "type": "text", "text": "Paragraph content" } + ] +} +``` + +### Bullet List + +```json +{ + "type": "bulletList", + "content": [ + { + "type": "listItem", + "content": [ + { + "type": "paragraph", + "content": [ + { "type": "text", "text": "List item" } + ] + } + ] + } + ] +} +``` + +### Ordered List + +```json +{ + "type": "orderedList", + "content": [ + { + "type": "listItem", + "content": [ + { + "type": "paragraph", + "content": [ + { "type": "text", "text": "Numbered item" } + ] + } + ] + } + ] +} +``` + +### Task List (Checkboxes) + +```json +{ + "type": "taskList", + "attrs": { "localId": "tasklist-1" }, + "content": [ + { + "type": "taskItem", + "attrs": { + "localId": "task-1", + "state": "TODO" // or "DONE" + }, + "content": [ + { "type": "text", "text": "Task description" } + ] + } + ] +} +``` + +### Code Block + +```json +{ + "type": "codeBlock", + "attrs": { "language": "python" }, + "content": [ + { "type": "text", "text": "print('hello')" } + ] +} +``` + +### Blockquote + +```json +{ + "type": "blockquote", + "content": [ + { + "type": "paragraph", + "content": [ + { "type": "text", "text": "Quoted text" } + ] + } + ] +} +``` + +### Rule (Horizontal Line) + +```json +{ + "type": "rule" +} +``` + +### Table + +```json +{ + "type": "table", + "attrs": { "isNumberColumnEnabled": false, "layout": "default" }, + "content": [ + { + "type": "tableRow", + "content": [ + { + "type": "tableHeader", + "attrs": {}, + "content": [ + { + "type": "paragraph", + "content": [{ "type": "text", "text": "Header" }] + } + ] + } + ] + }, + { + "type": "tableRow", + "content": [ + { + "type": "tableCell", + "attrs": {}, + "content": [ + { + "type": "paragraph", + "content": [{ "type": "text", "text": "Cell" }] + } + ] + } + ] + } + ] +} +``` + +## Inline Marks + +Apply to text nodes via `marks` array. + +### Bold + +```json +{ "type": "text", "text": "bold", "marks": [{ "type": "strong" }] } +``` + +### Italic + +```json +{ "type": "text", "text": "italic", "marks": [{ "type": "em" }] } +``` + +### Code (Inline) + +```json +{ "type": "text", "text": "code", "marks": [{ "type": "code" }] } +``` + +### Link + +```json +{ + "type": "text", + "text": "Click here", + "marks": [ + { + "type": "link", + "attrs": { "href": "https://example.com" } + } + ] +} +``` + +### Strikethrough + +```json +{ "type": "text", "text": "deleted", "marks": [{ "type": "strike" }] } +``` + +### Combined Marks + +```json +{ + "type": "text", + "text": "bold and italic", + "marks": [ + { "type": "strong" }, + { "type": "em" } + ] +} +``` + +## Complete Example + +```json +{ + "type": "doc", + "version": 1, + "content": [ + { + "type": "heading", + "attrs": { "level": 2 }, + "content": [{ "type": "text", "text": "Summary" }] + }, + { + "type": "paragraph", + "content": [ + { "type": "text", "text": "This task involves " }, + { "type": "text", "text": "important", "marks": [{ "type": "strong" }] }, + { "type": "text", "text": " changes." } + ] + }, + { + "type": "heading", + "attrs": { "level": 2 }, + "content": [{ "type": "text", "text": "Acceptance Criteria" }] + }, + { + "type": "taskList", + "attrs": { "localId": "ac-1" }, + "content": [ + { + "type": "taskItem", + "attrs": { "localId": "ti-1", "state": "TODO" }, + "content": [{ "type": "text", "text": "Feature implemented" }] + }, + { + "type": "taskItem", + "attrs": { "localId": "ti-2", "state": "TODO" }, + "content": [{ "type": "text", "text": "Tests passing" }] + } + ] + }, + { + "type": "heading", + "attrs": { "level": 2 }, + "content": [{ "type": "text", "text": "References" }] + }, + { + "type": "bulletList", + "content": [ + { + "type": "listItem", + "content": [ + { + "type": "paragraph", + "content": [ + { + "type": "text", + "text": "Documentation", + "marks": [{ "type": "link", "attrs": { "href": "https://example.com/docs" } }] + } + ] + } + ] + } + ] + } + ] +} +``` diff --git a/dot_claude/skills/acli/references/api_reference.md b/dot_claude/skills/acli/references/api_reference.md new file mode 100644 index 0000000..0011037 --- /dev/null +++ b/dot_claude/skills/acli/references/api_reference.md @@ -0,0 +1,34 @@ +# Reference Documentation for Acli + +This is a placeholder for detailed reference documentation. +Replace with actual reference content or delete if not needed. + +Example real reference docs from other skills: +- product-management/references/communication.md - Comprehensive guide for status updates +- product-management/references/context_building.md - Deep-dive on gathering context +- bigquery/references/ - API references and query examples + +## When Reference Docs Are Useful + +Reference docs are ideal for: +- Comprehensive API documentation +- Detailed workflow guides +- Complex multi-step processes +- Information too lengthy for main SKILL.md +- Content that's only needed for specific use cases + +## Structure Suggestions + +### API Reference Example +- Overview +- Authentication +- Endpoints with examples +- Error codes +- Rate limits + +### Workflow Guide Example +- Prerequisites +- Step-by-step instructions +- Common patterns +- Troubleshooting +- Best practices diff --git a/dot_claude/skills/acli/scripts/.gitkeep b/dot_claude/skills/acli/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/dot_claude/skills/acli/scripts/example.py b/dot_claude/skills/acli/scripts/example.py new file mode 100755 index 0000000..d443fc0 --- /dev/null +++ b/dot_claude/skills/acli/scripts/example.py @@ -0,0 +1,19 @@ +#!/usr/bin/env python3 +""" +Example helper script for acli + +This is a placeholder script that can be executed directly. +Replace with actual implementation or delete if not needed. + +Example real scripts from other skills: +- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields +- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images +""" + +def main(): + print("This is an example script for acli") + # TODO: Add actual script logic here + # This could be data processing, file conversion, API calls, etc. + +if __name__ == "__main__": + main()