From e1678e8a26babd78034091eeaa2d5a646dc75482 Mon Sep 17 00:00:00 2001 From: JonghunYu Date: Wed, 7 Jan 2026 14:17:01 +0900 Subject: [PATCH 1/3] chore: add link to repo in the sample instruction --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4120dc1..5549e0a 100644 --- a/README.md +++ b/README.md @@ -143,6 +143,7 @@ See [RELEASE.md](RELEASE.md) for the full release checklist, tagging instruction ### Shell Completion #### Zsh (macOS) + ```bash gi completion zsh > $(brew --prefix)/share/zsh/site-functions/_gi ``` @@ -150,11 +151,13 @@ gi completion zsh > $(brew --prefix)/share/zsh/site-functions/_gi #### Bash **Linux:** + ```bash gi completion bash > /etc/bash_completion.d/gi ``` **macOS:** + ```bash gi completion bash > $(brew --prefix)/etc/bash_completion.d/gi ``` @@ -205,7 +208,7 @@ For optimal AI agent integration, create instruction files in your repository ro ## Issue Management -This project uses gi for managing issues as Markdown files. +This project uses [gi](https://github.com/Allra-Fintech/git-issue) for managing issues as Markdown files. ### Finding Issues From 431e354be82ef75301ebbd6f02e8484b53df09a7 Mon Sep 17 00:00:00 2001 From: JonghunYu Date: Wed, 7 Jan 2026 14:28:50 +0900 Subject: [PATCH 2/3] Close issue #019 --- .issues/.counter | 2 +- .issues/closed/019-add-agent-instruction.md | 38 +++++++++++++++ cmd/init.go | 51 +++++++++++++++++++++ 3 files changed, 90 insertions(+), 1 deletion(-) create mode 100644 .issues/closed/019-add-agent-instruction.md diff --git a/.issues/.counter b/.issues/.counter index d6b2404..209e3ef 100644 --- a/.issues/.counter +++ b/.issues/.counter @@ -1 +1 @@ -19 +20 diff --git a/.issues/closed/019-add-agent-instruction.md b/.issues/closed/019-add-agent-instruction.md new file mode 100644 index 0000000..892f79e --- /dev/null +++ b/.issues/closed/019-add-agent-instruction.md @@ -0,0 +1,38 @@ +--- +id: "019" +assignee: "" +labels: [] +created: 2026-01-07T14:16:07.924716+09:00 +updated: 2026-01-07T14:28:50.454501+09:00 +--- + +# Add AI Agent Instruction Guide to gi init Output + +## Description + +Enhance the `gi init` command output to display sample AI agent instructions after successful initialization. This will guide users to set up their coding agents (Claude Code, Cursor, etc.) to work seamlessly with git-issue. + +## Requirements + +- After displaying the `.issues/` directory structure, add a new section that shows: + - A brief explanation about AI agent integration + - Sample instruction content that users can copy to their CLAUDE.md, AGENTS.md, or .cursorrules files + - The sample should teach AI agents how to: + - Find issues by ID pattern (`.issues/open/{id}-*.md` or `.issues/closed/{id}-*.md`) + - Understand issue file structure (YAML frontmatter + Markdown body) + - Determine status by directory location (open/ vs closed/, not a YAML field) + - Parse and work with issue references (e.g., "#001", "issue 001") +- Suggest common agent instruction file names: + - CLAUDE.md (for Claude Code) + - AGENTS.md (for general AI agents) + - .cursorrules (for Cursor IDE) +- Keep the output concise but informative +- Make it easy for users to understand the benefit of setting this up + +## Success Criteria + +- [ ] `gi init` command prints AI agent instruction guide after directory structure +- [ ] Sample instruction text is clear and copy-paste ready +- [ ] Output mentions multiple agent instruction file types +- [ ] Instructions cover key concepts: file naming, finding by ID, YAML frontmatter, status determination +- [ ] Users understand how to set up their AI agents to work with git-issue diff --git a/cmd/init.go b/cmd/init.go index d1921e4..6f34e51 100644 --- a/cmd/init.go +++ b/cmd/init.go @@ -44,6 +44,57 @@ func runInit(cmd *cobra.Command, args []string) error { fmt.Println(" └── template.md # Template for new issues") fmt.Println() fmt.Println("You can now create issues with 'gi create '") + fmt.Println() + + // Display AI agent instruction guidance + printAIAgentInstructions() return nil } + +func printAIAgentInstructions() { + fmt.Println("💡 AI Agent Integration") + fmt.Println() + fmt.Println("To help AI coding agents (Claude Code, Cursor, etc.) work with your issues,") + fmt.Println("add the following instructions to your CLAUDE.md, AGENTS.md, or .cursorrules file:") + fmt.Println() + fmt.Println("─────────────────────────────────────────────────────────────────────────") + fmt.Println() + fmt.Println("## Issue Management") + fmt.Println() + fmt.Println("This project uses git-issue for managing issues as Markdown files.") + fmt.Println() + fmt.Println("### Finding Issues") + fmt.Println() + fmt.Println("When a user references an issue like \"#001\" or \"issue 001\":") + fmt.Println() + fmt.Println("1. Search for the file in `.issues/open/` or `.issues/closed/`") + fmt.Println("2. File naming pattern: `{id}-{slug}.md` (e.g., `001-implement-feature.md`)") + fmt.Println("3. Use glob pattern: `.issues/open/001-*.md` or `.issues/closed/001-*.md`") + fmt.Println("4. Read the full issue file including YAML frontmatter and Markdown body") + fmt.Println() + fmt.Println("### Issue File Format") + fmt.Println() + fmt.Println("```markdown") + fmt.Println("---") + fmt.Println("id: \"001\"") + fmt.Println("assignee: username") + fmt.Println("labels: [bug, backend]") + fmt.Println("created: 2025-11-14T10:30:00Z") + fmt.Println("updated: 2025-11-14T14:20:00Z") + fmt.Println("---") + fmt.Println() + fmt.Println("# Issue Title") + fmt.Println() + fmt.Println("## Description") + fmt.Println() + fmt.Println("Full issue description...") + fmt.Println("```") + fmt.Println() + fmt.Println("**Important:** Status is determined by directory location (`.issues/open/`") + fmt.Println("= open, `.issues/closed/` = closed), NOT by a field in the YAML frontmatter.") + fmt.Println() + fmt.Println("─────────────────────────────────────────────────────────────────────────") + fmt.Println() + fmt.Println("For more details, see: https://github.com/Allra-Fintech/git-issue") +} From 2d30ad1ad88c2b4bfb754c2d9849822de0a41652 Mon Sep 17 00:00:00 2001 From: JonghunYu <yuzong@naver.com> Date: Wed, 7 Jan 2026 14:31:23 +0900 Subject: [PATCH 3/3] chore: update instruction content --- cmd/init.go | 43 +++++++++++++++++++------------------------ 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/cmd/init.go b/cmd/init.go index 6f34e51..a8b7768 100644 --- a/cmd/init.go +++ b/cmd/init.go @@ -60,41 +60,36 @@ func printAIAgentInstructions() { fmt.Println() fmt.Println("─────────────────────────────────────────────────────────────────────────") fmt.Println() + fmt.Println("# AI Agent Instructions") + fmt.Println() fmt.Println("## Issue Management") fmt.Println() - fmt.Println("This project uses git-issue for managing issues as Markdown files.") + fmt.Println("This project uses [gi](https://github.com/Allra-Fintech/git-issue) for managing issues as Markdown files.") fmt.Println() fmt.Println("### Finding Issues") fmt.Println() - fmt.Println("When a user references an issue like \"#001\" or \"issue 001\":") - fmt.Println() - fmt.Println("1. Search for the file in `.issues/open/` or `.issues/closed/`") - fmt.Println("2. File naming pattern: `{id}-{slug}.md` (e.g., `001-implement-feature.md`)") - fmt.Println("3. Use glob pattern: `.issues/open/001-*.md` or `.issues/closed/001-*.md`") - fmt.Println("4. Read the full issue file including YAML frontmatter and Markdown body") + fmt.Println("- **Open issues**: Located in `.issues/open/`") + fmt.Println("- **Closed issues**: Located in `.issues/closed/`") + fmt.Println("- **Issue file naming**: `{id}-{title-slug}.md` (e.g., `001-user-auth-bug.md`)") fmt.Println() - fmt.Println("### Issue File Format") + fmt.Println("### When a user references an issue") fmt.Println() - fmt.Println("```markdown") - fmt.Println("---") - fmt.Println("id: \"001\"") - fmt.Println("assignee: username") - fmt.Println("labels: [bug, backend]") - fmt.Println("created: 2025-11-14T10:30:00Z") - fmt.Println("updated: 2025-11-14T14:20:00Z") - fmt.Println("---") + fmt.Println("If a user says \"implement #001\" or \"fix issue 001\":") fmt.Println() - fmt.Println("# Issue Title") + fmt.Println("1. Search for the file matching the issue ID in `.issues/open/` or `.issues/closed/`") + fmt.Println("2. Read the entire issue file to understand requirements") + fmt.Println("3. Parse the YAML frontmatter for metadata (assignee, labels)") + fmt.Println("4. Note: Status is determined by directory location (open/ = open, closed/ = closed)") + fmt.Println("5. Use the issue description and details to guide your implementation") fmt.Println() - fmt.Println("## Description") + fmt.Println("Example: For \"#001\", look for `.issues/open/001-*.md`") fmt.Println() - fmt.Println("Full issue description...") - fmt.Println("```") + fmt.Println("### Working with issues") fmt.Println() - fmt.Println("**Important:** Status is determined by directory location (`.issues/open/`") - fmt.Println("= open, `.issues/closed/` = closed), NOT by a field in the YAML frontmatter.") + fmt.Println("- Always read the full issue before implementing") + fmt.Println("- Reference the issue file path in your responses") + fmt.Println("- Status is determined by directory: move files between open/ and closed/ to change status") + fmt.Println("- Maintain the YAML frontmatter structure when editing issues") fmt.Println() fmt.Println("─────────────────────────────────────────────────────────────────────────") - fmt.Println() - fmt.Println("For more details, see: https://github.com/Allra-Fintech/git-issue") }